a.tolmachev
178 lines
6.0 KiB
Markdown
178 lines
6.0 KiB
Markdown
# 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.
|
||
|
||
Причина:
|
||
|
||
- проект задуман как `Crank`, а не как локальный 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. Делегирует вызов в `crank-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 слое.
|