mirror of
https://github.com/Part-DB/Part-DB-server.git
synced 2026-08-03 23:21:44 +00:00
104 lines
5.5 KiB
PHP
104 lines
5.5 KiB
PHP
<?php
|
|
/*
|
|
* This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
|
|
*
|
|
* Copyright (C) 2019 - 2026 Jan Böhmer (https://github.com/jbtronics)
|
|
*
|
|
* This program is free software: you can redistribute it and/or modify
|
|
* it under the terms of the GNU Affero General Public License as published
|
|
* by the Free Software Foundation, either version 3 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU Affero General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Affero General Public License
|
|
* along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace App\Services\InfoProviderSystem\DTOs;
|
|
|
|
use ApiPlatform\Metadata\ApiResource;
|
|
use ApiPlatform\Metadata\GetCollection;
|
|
use ApiPlatform\Metadata\McpToolCollection;
|
|
use ApiPlatform\OpenApi\Model\Operation;
|
|
use App\Mcp\DTO\ListInfoProvidersInput;
|
|
use App\Services\InfoProviderSystem\Providers\ProviderCapabilities;
|
|
use App\State\Mcp\ListInfoProvidersProcessor;
|
|
use Symfony\Component\Serializer\Annotation\Groups;
|
|
|
|
/**
|
|
* Immutable, structured description of an info provider, returned by InfoProviderInterface::getProviderInfo()
|
|
* and (via the 'info_provider:read' group) exposed as the REST GET /api/info_providers collection and the
|
|
* list_info_providers MCP tool.
|
|
*
|
|
* disabledHelp, oauthAppName and settingsClass are internal-only (used by the settings UI) and deliberately
|
|
* not tagged with the 'info_provider:read' group, so they never appear in the API/MCP output.
|
|
*/
|
|
#[ApiResource(
|
|
uriTemplate: '/info_providers',
|
|
description: 'An info provider which can be used to search for parts and retrieve part details.',
|
|
operations: [
|
|
new GetCollection(
|
|
openapi: new Operation(summary: 'List the info providers which are currently active and can be used for searching parts.'),
|
|
security: 'is_granted("@info_providers.create_parts")',
|
|
provider: ListInfoProvidersProcessor::class,
|
|
),
|
|
],
|
|
normalizationContext: ['groups' => ['info_provider:read']],
|
|
paginationEnabled: false,
|
|
mcp: [
|
|
'list_info_providers' => new McpToolCollection(
|
|
title: 'List available info providers',
|
|
description: 'List the info providers (e.g. distributors like Digikey, Mouser, LCSC) which are currently active and can be used with search_info_providers and get_info_provider_part_details. Ask for the user\'s confirmation before using expensive providers (e.g. distributors with strict rate limits or which cost money to use).',
|
|
annotations: ['readOnlyHint' => true, 'destructiveHint' => false, 'idempotentHint' => true, 'openWorldHint' => false],
|
|
normalizationContext: ['groups' => ['info_provider:read']],
|
|
security: 'is_granted("@info_providers.create_parts")',
|
|
input: ListInfoProvidersInput::class,
|
|
processor: ListInfoProvidersProcessor::class,
|
|
),
|
|
],
|
|
)]
|
|
readonly class ProviderInfoDTO
|
|
{
|
|
public function __construct(
|
|
/** @var string A unique key for this provider (e.g. "digikey"), which is saved into the database and used to identify the provider */
|
|
#[Groups(['info_provider:read'])]
|
|
public string $key,
|
|
/** @var string The (user friendly) name of the provider (e.g. "Digikey"), will be translated */
|
|
#[Groups(['info_provider:read'])]
|
|
public string $name,
|
|
/** @var string|null A short description of the provider (e.g. "Digikey is a ..."), will be translated */
|
|
#[Groups(['info_provider:read'])]
|
|
public ?string $description = null,
|
|
/** @var string|null The url of the provider (e.g. "https://www.digikey.com") */
|
|
#[Groups(['info_provider:read'])]
|
|
public ?string $url = null,
|
|
/** @var string|null A help text which is shown when the provider is disabled, explaining how to enable it */
|
|
public ?string $disabledHelp = null,
|
|
/** @var string|null The name of the OAuth app which is used for authentication (e.g. "ip_digikey_oauth"). If this is set a connect button will be shown */
|
|
public ?string $oauthAppName = null,
|
|
/** @var class-string|null The class name of the settings class which contains the settings for this provider (e.g. "App\Settings\InfoProviderSettings\DigikeySettings"). If this is set a link to the settings will be shown */
|
|
public ?string $settingsClass = null,
|
|
/**
|
|
* A list of capabilities this provider supports (which kind of data it can provide).
|
|
* Not every part have to contain all of these data, but the provider should be able to provide them in general.
|
|
* Currently, this list is purely informational and not used in functional checks.
|
|
* @var ProviderCapabilities[]
|
|
*/
|
|
#[Groups(['info_provider:read'])]
|
|
public array $capabilities = [],
|
|
/**
|
|
* @var bool True if this provider is considered "expensive" (e.g. it has a strict rate limit or costs money to use), false otherwise.
|
|
* Users should be asked for confirmation before using an expensive provider, when making multiple requests (e.g. when searching for multiple parts at once),
|
|
* and more careful caching should be used for expensive providers.
|
|
*/
|
|
#[Groups(['info_provider:read'])]
|
|
public bool $expensive = false,
|
|
) {
|
|
}
|
|
}
|