docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/mcp-bundle/developers/extensions.md
новий файл +75
−0
1
+
# Розширення бандла
2
+
3
+
Усе нижче — звичайне перевизначення сервісу Symfony або тегований сервіс; змінювати бандл не потрібно.
4
+
5
+
| Що | Як | Для чого |
6
+
| --- | --- | --- |
7
+
| `Availability\McpAvailabilityCheckerInterface` | аліас сервісу | Чи відповідає група взагалі (інакше 404) |
8
+
| `Security\McpAccessPolicyInterface` | аліас сервісу | CORS origins і allowlist хостів для захисту від DNS rebinding |
9
+
| `ClientManifest\McpClientManifestGeneratorInterface` | тег `ufo_mcp.client_manifest_generator` з ключем `key` | Маніфест для іншого клієнта |
10
+
| `translations/rpc/<group>.<locale>.yaml` | переклади ядра | Тексти для агента без змін у коді |
11
+
| `#[McpTool]` | атрибут на методі | Підказки `ToolAnnotations` |
12
+
13
+
## Доступність групи
14
+
15
+
`McpAvailabilityCheckerInterface::isEnabled(string $group): bool` вирішує, чи група взагалі відповідає (інакше 404). Типовий `DefaultMcpAvailabilityChecker` читає `enabled` (`ufo_mcp.groups.<group>.enabled` з fallback на `ufo_mcp.enabled`). Замініть його для feature flag, перемикача для тенанта чи вікна обслуговування:
16
+
17
+
```php
18
+
use Ufo\McpBundle\Availability\McpAvailabilityCheckerInterface;
19
+
20
+
final readonly class FeatureFlagAvailability implements McpAvailabilityCheckerInterface
21
+
{
22
+
public function __construct(private FeatureFlags $flags) {}
23
+
24
+
public function isEnabled(string $group): bool
25
+
{
26
+
return $this->flags->isOn('mcp.'.$group);
27
+
}
28
+
}
29
+
```
30
+
31
+
```yaml
32
+
# config/services.yaml
33
+
services:
34
+
Ufo\McpBundle\Availability\McpAvailabilityCheckerInterface: '@App\Mcp\FeatureFlagAvailability'
35
+
```
36
+
37
+
Ваша реалізація повністю замінює перевірку з конфігурації; якщо потрібні обидві, викличте типову самостійно.
38
+
39
+
## Хости та origins
40
+
41
+
`McpAccessPolicyInterface` — див. [CORS і DNS rebinding](/docs/api/mcp-bundle/http_security).
42
+
43
+
## Маніфест для іншого клієнта
44
+
45
+
```php
46
+
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;
47
+
use Ufo\McpBundle\ClientManifest\McpClientManifestGeneratorHolder;
48
+
use Ufo\McpBundle\ClientManifest\McpClientManifestGeneratorInterface;
49
+
use Ufo\McpBundle\ConfigService\McpGroupConfig;
50
+
51
+
#[AutoconfigureTag(McpClientManifestGeneratorHolder::TAG, ['key' => 'acme'])]
52
+
final class AcmeAgentManifestGenerator implements McpClientManifestGeneratorInterface
53
+
{
54
+
public function generate(McpGroupConfig $group, string $endpointUrl, string $tokenHeaderName): array
55
+
{
56
+
return [
57
+
'servers' => [
58
+
$group->name => ['url' => $endpointUrl, 'headers' => [$tokenHeaderName => '<UFO_MCP_TOKEN>']],
59
+
],
60
+
];
61
+
}
62
+
}
63
+
```
64
+
65
+
Маніфест віддається за адресою `<prefix>/manifest/acme.json` у форматі, якого очікує конфігураційний файл цього клієнта. Ключ має відповідати `[\w-]+` і не збігатися з вбудованими (`claude`, `cursor`, `gemini`, `openai`). `$endpointUrl` — абсолютний URL ендпоінта з запиту, `$tokenHeaderName` — `ufo_json_rpc.security.token_name`. Не вставляйте в маніфест справжній токен.
66
+
67
+
## Тексти для агента
68
+
69
+
Переклади групи (`translations/rpc/<group>.<locale>.yaml`) описують метод для AI-агента інакше, ніж у документації OpenRPC, без змін у коді — див. [Заголовок і опис](/docs/api/mcp-bundle/tools). Бандл-розширення може постачати власні переклади через `ufo_json_rpc.translations.paths` ядра.
70
+
71
+
## Усе, що пропонує ядро
72
+
73
+
Виклик інструмента — RPC-запит ядра, тож [точки розширення JsonRpcBundle](/docs/api/json-rpc-bundle/developers) діють без змін: слухачі [подій](/docs/api/json-rpc-bundle/functionality/events) (`rpc.request`, `rpc.pre_execute`, `rpc.post_execute`, `rpc.pre_response`, `rpc.post_response`, `rpc.error`), конвертери параметрів, валідатори токенів і провайдери токенів для груп, пул кешу відповідей.
74
+
75
+
Інші пакети екосистеми — на сторінці [Розширення JsonRpcBundle](/docs/api/json-rpc-bundle/developers/extensions).