crank/docs/mcp-interface.md

MCP Interface

1. Назначение документа

Этот документ фиксирует, как именно платформа публикует operations в виде MCP tools и какой transport используется в MVP.

Главная цель - убрать неопределенность вокруг вопроса "каким именно будет MCP server" до начала реализации.

2. Архитектурное решение

Для MVP mcp-server должен публиковать tools через network-oriented MCP transport.

Рекомендуемое решение:

• основной transport: Streamable HTTP;
• отдельный mcp-server как сервис;
• stdio не является обязательной частью MVP.

Причина:

• проект задуман как MCPaaS, а не как локальный single-process adapter;
• нужен удаленный доступ к опубликованным tools;
• published tools должны обновляться без пересборки и без локального обертывания каждого клиента.

3. Модель публикации tools

Каждая published operation превращается в один MCP tool.

Соответствие:

• одна published version;
• один tool name;
• одна input schema;
• один результат.

Публикация tool основана на:

• operation.name
• tool_description
• input_schema
• published runtime view

4. Что делает mcp-server

mcp-server должен:

• загрузить published operations из registry;
• преобразовать их в MCP tool definitions;
• принимать вызовы tools от MCP clients;
• валидировать вход;
• делегировать исполнение в runtime;
• возвращать нормализованный output.

5. Что не делает mcp-server

mcp-server не должен:

• читать draft-конфигурации;
• управлять versioning;
• импортировать YAML;
• выполнять CRUD;
• заниматься protobuf discovery;
• содержать бизнес-логику admin UI.

6. Published runtime view

mcp-server должен работать не с полной admin-конфигурацией, а с runtime-ready view.

В published runtime view остаются:

• operation_id
• protocol
• target
• input_schema
• output_schema
• input_mapping
• output_mapping
• execution_config
• tool_description

В published runtime view не должны попадать:

• raw uploaded samples;
• generated draft metadata;
• YAML import metadata;
• UI-specific helper fields.

7. Transport для MVP

Поддерживается

• Streamable HTTP

Не обязательно в MVP

• stdio
• дополнительные transport adapters

Если позже понадобится локальная интеграция, stdio можно добавить как отдельный transport layer поверх того же runtime.

8. MCP lifecycle

MVP-контракт mcp-server строится вокруг JSON-RPC методов MCP:

• initialize
• notifications/initialized
• ping
• tools/list
• tools/call

Сессия создается на initialize и идентифицируется через MCP-Session-Id. Согласованная версия протокола возвращается и читается через MCP-Protocol-Version.

Пока сессии хранятся in-memory внутри mcp-server, чего достаточно для MVP и demo-сценариев.

Tool listing

После initialize и notifications/initialized:

1. клиент вызывает tools/list;
2. mcp-server перечитывает published operations по refresh policy;
3. строит или обновляет in-memory catalog tools;
4. отдает список tools через MCP JSON-RPC result.

Tool call

1. MCP client вызывает tool.
2. mcp-server находит published runtime view.
3. Валидирует input относительно schema.
4. Делегирует вызов в mcpaas-runtime.
5. Возвращает результат.

9. Обновление tools

После публикации новой версии:

1. admin-api фиксирует published version в registry.
2. registry обновляет published_operations.
3. mcp-server не требует restart и не опирается на ручной reload signal.
4. mcp-server выполняет controlled refresh опубликованного каталога по interval-based policy.
5. Новый tool contract становится доступен MCP clients.

10. Именование tools

Рекомендуется использовать стабильные tool names:

• crm_create_lead
• user_get_profile
• inventory_list_items

Требования:

• имя уникально в пределах платформы;
• имя не зависит от внутреннего numeric version;
• rename operation должен считаться отдельным осознанным изменением.

11. Ошибки MCP слоя

На MCP слое нужно различать:

• schema validation error;
• mapping error;
• adapter execution error;
• external service error;
• internal runtime error.

mcp-server не должен терять стадию ошибки при трансляции ответа клиенту.

12. Практический итог

Для MVP достаточно следующей фиксации:

• mcp-server - отдельный сервис;
• transport - Streamable HTTP;
• одна published operation = один MCP tool;
• reload published tools без пересборки сервиса;
• никакой draft-логики или admin CRUD в MCP слое.