a.tolmachev
165 lines
4.9 KiB
Markdown
165 lines
4.9 KiB
Markdown
# MCP Interface
|
||
|
||
## 1. Назначение документа
|
||
|
||
Этот документ фиксирует, как именно платформа публикует agents и operations в виде MCP tools и какой transport используется в целевой модели.
|
||
|
||
## 2. Архитектурное решение
|
||
|
||
`mcp-server` публикует tools через network-oriented MCP transport.
|
||
|
||
Решение:
|
||
|
||
- основной transport: `Streamable HTTP`;
|
||
- отдельный `mcp-server` как сервис;
|
||
- `stdio` не является обязательной частью текущего scope.
|
||
|
||
## 3. Модель публикации tools
|
||
|
||
Каждая published operation превращается в один MCP tool внутри конкретного published agent.
|
||
|
||
Соответствие:
|
||
|
||
- один published agent;
|
||
- набор `AgentOperationBinding`;
|
||
- один tool name на binding;
|
||
- одна input schema;
|
||
- один результат.
|
||
|
||
Публикация tool основана на:
|
||
|
||
- `agent.slug`
|
||
- `operation.name` или binding-level `tool_name`
|
||
- `tool_description`
|
||
- `input_schema`
|
||
- `published runtime view`
|
||
|
||
## 4. Что делает `mcp-server`
|
||
|
||
`mcp-server` должен:
|
||
|
||
- загрузить published agents и их bindings из registry;
|
||
- преобразовать их в MCP tool definitions;
|
||
- принимать вызовы tools от MCP clients;
|
||
- валидировать вход;
|
||
- делегировать исполнение в runtime;
|
||
- возвращать нормализованный output.
|
||
|
||
## 5. Что не делает `mcp-server`
|
||
|
||
`mcp-server` не должен:
|
||
|
||
- читать draft-конфигурации;
|
||
- управлять versioning;
|
||
- импортировать YAML;
|
||
- выполнять CRUD;
|
||
- заниматься protobuf discovery;
|
||
- содержать бизнес-логику admin UI.
|
||
|
||
## 6. Runtime view
|
||
|
||
В runtime view остаются:
|
||
|
||
- `workspace_id`
|
||
- `agent_id`
|
||
- `operation_id`
|
||
- `protocol`
|
||
- `target`
|
||
- `input_schema`
|
||
- `output_schema`
|
||
- `input_mapping`
|
||
- `output_mapping`
|
||
- `execution_config`
|
||
- `tool_description`
|
||
|
||
В runtime view не попадают:
|
||
|
||
- raw uploaded samples;
|
||
- generated draft metadata;
|
||
- YAML import metadata;
|
||
- UI-specific helper fields.
|
||
|
||
## 7. MCP endpoint model
|
||
|
||
Канонический endpoint:
|
||
|
||
```text
|
||
/mcp/v1/{workspace_slug}/{agent_slug}
|
||
```
|
||
|
||
Этот endpoint определяет:
|
||
|
||
- tenant boundary;
|
||
- конкретный curated toolset;
|
||
- набор usage и log labels.
|
||
|
||
## 8. MCP lifecycle
|
||
|
||
Поддерживаемые JSON-RPC методы:
|
||
|
||
- `initialize`
|
||
- `notifications/initialized`
|
||
- `ping`
|
||
- `tools/list`
|
||
- `tools/call`
|
||
|
||
### Tool listing
|
||
|
||
1. клиент вызывает `tools/list`;
|
||
2. `mcp-server` извлекает `workspace_slug` и `agent_slug` из path;
|
||
3. перечитывает published agent по refresh policy;
|
||
4. строит или обновляет in-memory catalog tools только для этого agent;
|
||
5. отдает список tools через MCP JSON-RPC result.
|
||
|
||
### Tool call
|
||
|
||
1. клиент вызывает tool;
|
||
2. `mcp-server` определяет `workspace` и `agent`;
|
||
3. находит binding нужной operation внутри published agent;
|
||
4. валидирует input относительно schema;
|
||
5. делегирует вызов в `crank-runtime`;
|
||
6. возвращает результат.
|
||
|
||
## 9. Обновление tools
|
||
|
||
После публикации новой operation version или agent version:
|
||
|
||
1. `admin-api` фиксирует published version в registry;
|
||
2. `registry` обновляет published operations или published agents;
|
||
3. `mcp-server` не требует restart;
|
||
4. выполняется controlled refresh опубликованного каталога;
|
||
5. новый tool contract становится доступен MCP clients.
|
||
|
||
## 10. Именование tools
|
||
|
||
Рекомендуется использовать стабильные tool names:
|
||
|
||
- `crm_create_lead`
|
||
- `user_get_profile`
|
||
- `inventory_list_items`
|
||
|
||
Требования:
|
||
|
||
- имя уникально в пределах одного agent;
|
||
- имя не зависит от numeric version;
|
||
- один и тот же operation может публиковаться под разными именами в разных agents.
|
||
|
||
## 11. Ошибки MCP слоя
|
||
|
||
На MCP слое нужно различать:
|
||
|
||
- schema validation error;
|
||
- mapping error;
|
||
- adapter execution error;
|
||
- external service error;
|
||
- internal runtime error.
|
||
|
||
## 12. Практический итог
|
||
|
||
- `mcp-server` - отдельный сервис;
|
||
- transport - `Streamable HTTP`;
|
||
- endpoint определяется парой `workspace + agent`;
|
||
- одна published operation = один MCP tool внутри agent;
|
||
- reload published tools без пересборки сервиса;
|
||
- никакой draft-логики или admin CRUD в MCP слое.
|