docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/mcp-bundle/README.md
новий файл +93
−0
1
+
# MCP Bundle
2
+
3
+
:::block class="floatinginfobox"
4
+
<include>(docs/api/mcp-bundle/.info.md)
5
+
:::
6
+
7
+
MCP-сервер ([Model Context Protocol](https://modelcontextprotocol.io)) для [JsonRpcBundle](/docs/api/json-rpc-bundle): методи вашого JSON-RPC API стають інструментами (tools), які AI-агенти — Claude Code, Cursor, Gemini CLI, OpenAI — викликають через Streamable HTTP.
8
+
9
+
Це тонкий адаптер, як і [REST Bundle](/docs/api/rest-bundle): бізнес-логіка лишається в RPC-сервісах, а кожен виклик інструмента — звичайний RPC-запит, який виконує JsonRpcBundle. Перетворення параметрів, DTO, валідація, кеш, блокування, події та формат помилок — ті самі, що й на `/rpc`.
10
+
11
+
## Від методу до інструмента
12
+
13
+
::::columns
14
+
:::col
15
+
**Ваш код**
16
+
17
+
```php
18
+
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
19
+
use Ufo\McpBundle\Attribute\McpTool;
20
+
use Ufo\RpcObject\RPC;
21
+
22
+
#[RPC\Info('Catalog')]
23
+
#[RPC\APIGroups(['mcp'], withDefault: false)]
24
+
final class CatalogProcedure implements IRpcService
25
+
{
26
+
/**
27
+
* Search products by name.
28
+
* @param string $query Part of the product name
29
+
*/
30
+
#[McpTool(readOnlyHint: true)]
31
+
public function search(string $query, int $limit = 10): array
32
+
{
33
+
// ...
34
+
}
35
+
}
36
+
```
37
+
:::
38
+
39
+
:::col
40
+
**`tools/list` на `/mcp`** (скорочено)
41
+
42
+
```json
43
+
{
44
+
"name": "Catalog.search",
45
+
"description": "Search products by name.",
46
+
"inputSchema": {
47
+
"type": "object",
48
+
"properties": {
49
+
"query": {"type": "string", "description": "Part of the product name"},
50
+
"limit": {"type": "integer", "default": 10}
51
+
},
52
+
"additionalProperties": false,
53
+
"required": ["query"]
54
+
},
55
+
"annotations": {"readOnlyHint": true}
56
+
}
57
+
```
58
+
:::
59
+
::::
60
+
61
+
Більше нічого писати не треба:
62
+
63
+
* `POST /mcp` — MCP-сервер з інструментом `Catalog.search`, захищений RPC-токеном;
64
+
* `GET /mcp/manifest/claude.json` віддає готову конфігурацію Claude Code для підключення (так само `cursor`, `gemini`, `openai`);
65
+
* `GET /mcp/server.json` — документ для публікації в MCP Registry.
66
+
67
+
## Можливості
68
+
69
+
* **Що стає інструментом — визначає група API.** Кожен метод [групи](/docs/api/json-rpc-bundle/functionality/groups) — інструмент з назвою RPC-методу. Кілька ендпоінтів (`/mcp`, `/mcp/internal`, …) поруч, кожен зі своїми методами ([Налаштування](/docs/api/mcp-bundle/config)).
70
+
* **Версії API.** `/mcp/v2` обслуговує [версію](/docs/api/json-rpc-bundle/functionality/versions) 2 групи.
71
+
* **Роботу робить ядро.** Виклик інструмента проходить через `RpcExecutor` JsonRpcBundle ([Інструменти](/docs/api/mcp-bundle/tools)).
72
+
* **Схеми й тексти для агентів.** `inputSchema` / `outputSchema` з метаданих методів; назви й описи з перекладів ядра за `Accept-Language`, зокрема окремо для групи; підказки `#[McpTool]`.
73
+
* **Обидві епохи протоколу MCP** на одному URL: із сесіями (сесії в кеш-пулі ядра) і stateless 2026-07-28 ([HTTP і безпека](/docs/api/mcp-bundle/http_security)).
74
+
* **Та сама безпека.** RPC-токени ядра (401/403), 404 для вимкненої групи чи відсутньої версії, CORS, захист від DNS rebinding, ліміт тіла запиту.
75
+
* **Discovery.** `server.json` для MCP Registry і маніфести клієнтів ([server.json і маніфести](/docs/api/mcp-bundle/discovery)).
76
+
* **Розширюваність.** Перевірка доступності, політика доступу, власні маніфести клієнтів ([Для розробників](/docs/api/mcp-bundle/developers/extensions)).
77
+
78
+
## Обмеження
79
+
80
+
* Без OAuth: доступ — RPC-токен у заголовку ([HTTP і безпека](/docs/api/mcp-bundle/http_security)).
81
+
* Лише tools: без MCP resources і prompts. SDK типово оголошує capabilities `logging` і `completions`, але бандл їх не використовує.
82
+
* Без повідомлень з ініціативи сервера (`GET` на ендпоінт відповідає 405) і без [асинхронних](/docs/api/json-rpc-bundle/functionality/async) викликів чи [webhook](/docs/api/json-rpc-bundle/functionality/callback) через MCP.
83
+
84
+
:::info
85
+
<include>(change_log/latest.md)
86
+
:::
87
+
88
+
## З чого почати
89
+
90
+
1. [Встановіть бандл](/docs/api/mcp-bundle/installation) і додайте маршрути MCP.
91
+
2. Додайте RPC-методи в групу ендпоінта — і перевірте `tools/list`.
92
+
3. Налаштуйте [сервер групи](/docs/api/mcp-bundle/config) і, за потреби, [CORS і хости](/docs/api/mcp-bundle/http_security).
93
+
4. Підключіть клієнта за [маніфестом](/docs/api/mcp-bundle/discovery).
uk/docs/api/mcp-bundle/.info.md
новий файл +65
−0
1
+
:::::columns border="1" zebra="1"
2
+
::::row
3
+
:::col width="40%"
4
+
Скачати
5
+
:::
6
+
7
+
:::col
8
+
[Packagist](https://packagist.org/packages/ufo-tech/mcp-bundle)<br>
9
+
[GitHub](https://github.com/UFO-Tech/mcp-bundle)
10
+
:::
11
+
::::
12
+
13
+
::::row
14
+
:::col width="40%"
15
+
Актуальна версія
16
+
:::
17
+
18
+
:::col
19
+
[](https://packagist.org/packages/ufo-tech/mcp-bundle)
20
+
:::
21
+
::::
22
+
23
+
::::row
24
+
:::col width="40%"
25
+
Категорія
26
+
:::
27
+
28
+
:::col
29
+
API
30
+
:::
31
+
::::
32
+
33
+
::::row
34
+
:::col width="40%"
35
+
Тип
36
+
:::
37
+
38
+
:::col
39
+
Symfony Bundle
40
+
:::
41
+
::::
42
+
43
+
::::row
44
+
:::col width="40%"
45
+
Залежності
46
+
:::
47
+
48
+
:::col
49
+
50
+
51
+
52
+
:::
53
+
::::
54
+
55
+
::::row
56
+
:::col width="40%"
57
+
Інші відомості
58
+
:::
59
+
60
+
:::col
61
+
62
+
63
+
:::
64
+
::::
65
+
:::::
uk/docs/api/mcp-bundle/change_log/latest.md
новий файл +1
−0
1
+
<include>(1.0.0.md)
uk/docs/api/mcp-bundle/change_log/1.0.0.md
новий файл +25
−0
1
+
## Версія 1.0 (2026-10-19)
2
+
3
+
Перший реліз: RPC-методи групи API як MCP-інструменти через Streamable HTTP.
4
+
5
+
### Ключові зміни
6
+
7
+
* [Ендпоінт на кожен імпорт маршрутів](/docs/api/mcp-bundle/config): `api_group` — група API ядра, `/mcp/v2` — версія API 2; назви маршрутів містять групу (`mcp_ufo_mcp_endpoint`, …).
8
+
* [Інструменти](/docs/api/mcp-bundle/tools): кожен метод групи; назви й описи з перекладів ядра (зокрема `translations/rpc/<group>.<locale>.yaml`) за `Accept-Language`; самодостатні `inputSchema` / `outputSchema`; підказки `#[McpTool]`.
9
+
* `tools/call` через `RpcExecutor` ядра: `structuredContent: {"result": …}` і той самий JSON текстом; помилки — RPC-помилка ядра з `isError: true`; `rpc.post_response` після відправлення відповіді, один раз на виклик (і в batch).
10
+
* [HTTP і безпека](/docs/api/mcp-bundle/http_security): протокол із сесіями (сесії в кеш-пулі ядра) і stateless 2026-07-28 на одному URL; токени ядра (401/403); 404 для вимкненої групи чи відсутньої версії; CORS, захист від DNS rebinding, `max_body_bytes`.
11
+
* [Discovery](/docs/api/mcp-bundle/discovery): `server.json` для MCP Registry, маніфести для Claude Code, Cursor, Gemini CLI, OpenAI.
12
+
13
+
### Що врахувати
14
+
15
+
Стосується лише застосунків, що використовували бандл з `dev-main` до 1.0.0:
16
+
17
+
* Опцію `session_directory` (загальну і для групи) прибрано — сесії в кеш-пулі ядра; приберіть ключ, інакше «Unrecognized option». `groups` тепер може бути порожнім.
18
+
* Назви маршрутів містять групу (`<group>_ufo_mcp_endpoint`); ручний `name_prefix` у YAML-імпортах не потрібен.
19
+
* Назви й описи беруться лише з перекладів ядра: `ToolTextResolverInterface` і `Ufo\McpBundle\I18n\*` прибрано.
20
+
* Класи перенесено з `Ufo\McpBundle\Services\*` до `Server\*`, `Server\Transport\*`, `Tool\*`; перевірки групи, доступності й токена — з `McpController` до `EventListener\McpRequestListener`.
21
+
22
+
### Зміни оточення
23
+
24
+
* PHP >= 8.4, Symfony ^7.2 | ^8.0 (через JsonRpcBundle).
25
+
* `ufo-tech/json-rpc-bundle` ^10.4.3, `mcp/sdk` ^0.8.1, `symfony/psr-http-message-bridge` ^7.2 | ^8.0, `symfony/yaml` ^7.2 | ^8.0, `nyholm/psr7` ^1.8.