Налаштування MCP Bundle

Налаштування складається з двох частин: маршрути визначають, які ендпоінти існують, яку групу і версію API кожен обслуговує; конфігурація ufo_mcp лише налаштовує сервер групи. Конфігурація ніколи не вирішує, які методи стають інструментами і яка версія обслуговується.

Маршрути: один імпорт на ендпоінт

# config/routes/ufo_mcp.yaml
ufo_mcp:
    resource: ../../vendor/ufo-tech/mcp-bundle/config/router.yaml
    prefix: /mcp
    defaults: { api_group: mcp }

ufo_mcp_internal:
    resource: ../../vendor/ufo-tech/mcp-bundle/config/router.yaml
    prefix: /mcp/internal
    defaults: { api_group: internal }

api_group — група API ядра, яку обслуговує ендпоінт. Без нього — типова група ядра general.
Кожен імпорт отримує власні назви маршрутів (mcp_ufo_mcp_endpoint, internal_ufo_mcp_endpoint, …), тож name_prefix не потрібен. Це робить завантажувач маршрутів ядра для YAML-імпортів; у конфігурації маршрутів на PHP чи XML задавайте name_prefix вручну.

Кожен імпорт обслуговує:

Маршрут	Назва	Методи HTTP
`<prefix>`, `<prefix>/{ver}`	`<group>_ufo_mcp_endpoint`	`POST`, `DELETE`, `OPTIONS`; `GET` відповідає 405
`<prefix>/server.json`, `<prefix>/{ver}/server.json`	`<group>_ufo_mcp_server_json`, `<group>_ufo_mcp_server_json_ver`	`GET`
`<prefix>/manifest/{aiName}.json`, `<prefix>/{ver}/manifest/{aiName}.json`	`<group>_ufo_mcp_manifest`, `<group>_ufo_mcp_manifest_ver`	`GET`

{ver} — v1, v2, …; без нього — v1.

Довідник конфігурації

Файл config/packages/ufo_mcp.yaml, кореневий ключ ufo_mcp.

ufo_mcp:
    enabled: true
    instructions: ~
    max_body_bytes: 4194304
    session_ttl: 3600
    mcp_server_info:
        name: 'io.github.your-org/your-app'
        title: 'Your App MCP Server'
        description: 'Exposes Your App RPC services as MCP tools.'
        icons:
            - src: 'https://example.com/icon.png'
              mime_type: 'image/png'
              sizes: ['128x128']
              theme: ~
    groups:
        internal:
            instructions: 'Internal tools.'
            mcp_server_info:
                name: 'io.github.your-org/your-app-internal'

Параметр	За замовчуванням	Опис
`enabled`	`true`	Чи відповідає ендпоінт; інакше 404. Підтримує `'%env(bool:MCP_ENABLED)%'`
`instructions`	`null`	Поле `instructions` у відповіді `initialize` — підказка агенту, як користуватися сервером
`max_body_bytes`	`4194304`	Ліміт тіла запиту в байтах, >= 1; більше тіло — 413
`session_ttl`	`3600`	Скільки секунд живе сесія протоколу із сесіями, >= 1
`mcp_server_info.name`	`null`	Ідентифікатор сервера у форматі reverse-DNS для MCP Registry; `serverInfo.name` в `initialize`. Якщо не задано — `ufo-rpc` в `initialize` і поле відсутнє в `server.json`
`mcp_server_info.title`	`null`	`serverInfo.title` в `initialize` і `title` у `server.json`
`mcp_server_info.description`	`null`	Лише для `server.json`
`mcp_server_info.icons[]`	`[]`	Лише для `server.json`: `src` (обов'язковий), `mime_type`, `sizes`, `theme` (`light` \| `dark`)
`groups.<group>`	—	Необов'язкові перевизначення для групи: ті самі поля `enabled`, `instructions`, `max_body_bytes`, `session_ttl`, `mcp_server_info`

groups — необов'язковий. Групу визначає маршрут; група без власного запису працює на загальних налаштуваннях бандла. Запис лише перевизначає їх поле за полем: незадане (або ~) поле успадковує загальне значення, mcp_server_info теж (група може задати лише name).
Налаштування версії немає. serverInfo.version в initialize і version у server.json — це завжди {ver} запиту.
Опції попередніх збірок (session_directory, server_name, server_version, methods) прибрано; з ними конфігурація падає з «Unrecognized option».

Для групи max_body_bytes і session_ttl не перевіряються конфігурацією так, як загальні значення. Задавайте цілі числа >= 1 — див. Актуальні помилки.

Групи API

Які методи стають інструментами, визначає атрибут ядра #[RPC\APIGroups] на класі чи методі:

use Ufo\RpcObject\RPC;

#[RPC\Info('Catalog')]
#[RPC\APIGroups(['mcp', 'internal'], withDefault: false)]
final class CatalogProcedure implements IRpcService { /* /mcp і /mcp/internal, не /rpc */ }

#[RPC\Info('Admin')]
#[RPC\APIGroups(['internal'], withDefault: false)]
final class AdminProcedure implements IRpcService { /* лише /mcp/internal */ }

Ту саму групу можуть одночасно обслуговувати /rpc/... (JsonRpcBundle) і /mcp/... (цей бандл). Перевірка токенів для групи (ufo_json_rpc.security.providers) діє і для MCP.

Версії API

/mcp і /mcp/v1 обслуговують версію 1, /mcp/v2 — версію 2 групи в ядрі (#[RPC\Info('Catalog', version: 2, removedMethods: [...])]; версія успадковує попередню, див. Версії API). Версія, якої в групи немає, відповідає 404. Група без жодного методу теж відповідає 404.

Сесії та спільний кеш

Клієнти протоколу із сесіями (до 2026-07-28) отримують Mcp-Session-Id. Сесія зберігається в пулі кешу ядра під ключем ufo_mcp_<group>_<session id> з session_ttl групи. Типово це локальний пул на файловій системі; коли MCP обслуговують кілька хостів, спрямуйте його на спільне сховище, інакше сесія, створена на одному хості, буде невідома на іншому:

# config/packages/ufo_json_rpc.yaml
ufo_json_rpc:
    cache:
        pool: 'cache.app'   # наприклад, спільний Redis

Stateless-клієнтам протоколу 2026-07-28 сховище сесій не потрібне.