docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/mcp-bundle/developers/known_issues/open.md
новий файл +17
−0
1
+
# Актуальні помилки
2
+
3
+
Відомі помилки й нестиковки поточної версії MCP Bundle (1.0.0): симптом, причина та обхідний шлях. Помилки ядра — у [Відомих помилках JsonRpcBundle](/docs/api/json-rpc-bundle/developers/known_issues/open). Виправлені — на сторінці [Виправлені помилки](/docs/api/mcp-bundle/developers/known_issues/fixed).
4
+
5
+
<include>(.issues/group-limits-not-validated.md)
6
+
7
+
---
8
+
9
+
<include>(.issues/oauth-not-supported.md)
10
+
11
+
---
12
+
13
+
<include>(.issues/xdebug-coverage-segfault.md)
14
+
15
+
---
16
+
17
+
<include>(.issues/bundle-docs-inconsistencies.md)
uk/docs/api/mcp-bundle/developers/known_issues/.issues/group-limits-not-validated.md
новий файл +15
−0
1
+
### Ліміти групи не перевіряються конфігурацією
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 1.0.0 (поточна). Перевірено за кодом тегу 1.0.0.
5
+
:::
6
+
7
+
**Симптом.** Загальні `max_body_bytes` і `session_ttl` мають бути цілими числами >= 1, інакше контейнер не збирається. Ті самі параметри в `groups.<group>` приймаються будь-якими, і помилка проявляється лише під час запиту:
8
+
9
+
* `max_body_bytes: 0` (або від'ємне) — кожен запит до ендпоінта групи завершується HTTP 500 (`maxBodyBytes must be at least 1.` з транспорту SDK);
10
+
* `session_ttl: 0` або від'ємне — сесія прострочена одразу після створення, клієнт протоколу із сесіями отримує 404 на кожен запит після `initialize`;
11
+
* рядок замість числа — `TypeError` під час створення конфігурації бандла, HTTP 500.
12
+
13
+
**Причина.** У `Configuration` для групи ці поля — `scalarNode` без `min(1)` (щоб приймати `~` як «успадкувати»), а `McpGroupConfig` присвоює значення без перевірки.
14
+
15
+
**Обхідний шлях.** Задавайте для групи цілі числа >= 1 або не задавайте поле зовсім (тоді діє загальне значення). Для змінних оточення використовуйте `%env(int:...)%`.
uk/docs/api/mcp-bundle/developers/known_issues/.issues/oauth-not-supported.md
новий файл +11
−0
1
+
### Клієнти лише з OAuth не можуть підключитися
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 1.0.0 (поточна). Обмеження, зазначене в описі релізу 1.0.
5
+
:::
6
+
7
+
**Симптом.** MCP-клієнт, який не вміє надсилати власний заголовок і чекає авторизації OAuth, отримує 401 і не підключається. Наприклад, MCP Inspector без заголовка з токеном запускає власний OAuth-flow, який завершується невдачею.
8
+
9
+
**Причина.** OAuth не реалізовано: немає `/.well-known/oauth-protected-resource` і заголовка `WWW-Authenticate` у відповіді 401. Доступ — лише RPC-токен ядра в заголовку (`Ufo-RPC-Token`).
10
+
11
+
**Обхідний шлях.** Використовуйте клієнти, що підтримують власні заголовки (Claude Code, Cursor, Gemini CLI, OpenAI Responses API), і [маніфести](/docs/api/mcp-bundle/discovery); у MCP Inspector передавайте `--header "Ufo-RPC-Token: …"`.
uk/docs/api/mcp-bundle/developers/known_issues/.issues/xdebug-coverage-segfault.md
новий файл +11
−0
1
+
### Покриття під Xdebug завершується segmentation fault
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 1.0.0 (поточна). Стосується лише розробки бандла, на роботу застосунку не впливає.
5
+
:::
6
+
7
+
**Симптом.** Запуск тестів з покриттям через Xdebug 3.4.2 (образ `ufotech/php:8.4-fpm`) падає з segmentation fault на тестах, що запускають сервер SDK.
8
+
9
+
**Причина.** Збій самого Xdebug 3.4.2, а не помилка в коді бандла (за описом релізу 1.0); точна причина не встановлена.
10
+
11
+
**Обхідний шлях.** Збирайте покриття через pcov — див. [Тести](/docs/api/mcp-bundle/developers/testing).
uk/docs/api/mcp-bundle/developers/known_issues/.issues/bundle-docs-inconsistencies.md
новий файл +8
−0
1
+
### Нестиковки в документації репозиторію бандла
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 1.0.0 (поточна). Нестиковка документації, на роботу бандла не впливає.
5
+
:::
6
+
7
+
* `README.md` і `README-UA.md` бандла посилаються на документацію за адресою `http://localhost/uk/docs/api/mcp-bundle`. Актуальна документація — на цьому сайті.
8
+
* Приклад «За одну хвилину» в `docs/README.md` (і `-UA`) обіцяє інструмент `Catalog.search` для класу `CatalogProcedure` без `#[RPC\Info]`. Без атрибута ядро бере коротку назву класу, тож інструмент називатиметься `CatalogProcedure.search`. Щоб отримати `Catalog.search`, додайте `#[RPC\Info('Catalog')]`, як у прикладах на цьому сайті.