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

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

Ashterix

docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api

uk/docs/api/mcp-bundle/config.md новий файл +112 −0

Налаштування 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 сховище сесій не потрібне.