a.tolmachev
243 lines
9.6 KiB
Markdown
243 lines
9.6 KiB
Markdown
# MCP Interface
|
||
|
||
## 1. Назначение документа
|
||
|
||
Этот документ фиксирует, как именно платформа публикует agents и operations в виде MCP tools и какой transport используется в целевой модели.
|
||
|
||
## 2. Архитектурное решение
|
||
|
||
`mcp-server` публикует tools через network-oriented MCP transport.
|
||
|
||
Решение:
|
||
|
||
- основной transport: `Streamable HTTP`;
|
||
- `POST` может завершаться `application/json` или `text/event-stream`;
|
||
- `GET` SSE stream поддерживается как server-to-client канал;
|
||
- отдельный `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;
|
||
- вести `Mcp-Session-Id` и `MCP-Protocol-Version`;
|
||
- принимать вызовы 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.
|
||
|
||
## 7.1. MCP authentication
|
||
|
||
Целевая модель машинной аутентификации для `mcp-server` строится вокруг AI-агента, а не вокруг рабочей области целиком. При этом допустимый способ вызова определяется не только агентом, но и уровнем защиты самой операции.
|
||
|
||
Контракт:
|
||
|
||
- каждому published agent соответствует собственный длинноживущий `agent key`;
|
||
- `agent key` принадлежит одновременно `workspace` и `agent`;
|
||
- в редакции `Community` вызовы допускаются по статическому `agent key`;
|
||
- в управляемой платформе для операций уровня `elevated` должен использоваться короткоживущий токен;
|
||
- в редакции `Enterprise` для операций уровня `strict` должен использоваться одноразовый токен;
|
||
- операция задает обязательный `security_level`, и `mcp-server` обязан отклонять вызов, если представленный credential слабее требуемого уровня;
|
||
- детальная модель уровней зафиксирована в `docs/agent-auth-model.md`.
|
||
|
||
Важно:
|
||
|
||
- Community-сборка должна работать полностью без private token services;
|
||
- commercial token flows должны подключаться через capability-gated server-side integrations.
|
||
- public `mcp-server` должен содержать verification seam для bearer-token credentials, даже если Community по умолчанию использует только static agent key.
|
||
|
||
Verification seam:
|
||
|
||
- Community path сначала проверяет статический `agent key`;
|
||
- если статический ключ не подходит, `mcp-server` делегирует bearer-token verification в отдельный verifier interface;
|
||
- в open-source Community verifier по умолчанию не выдает commercial credentials;
|
||
- private short-lived и one-time token verification подключаются заменой verifier implementation без изменения MCP transport contract.
|
||
|
||
Уровни защиты операции:
|
||
|
||
- `standard`
|
||
- `elevated`
|
||
- `strict`
|
||
|
||
Правило применения:
|
||
|
||
- `standard` допускает статический ключ агента, короткоживущий токен и одноразовый токен;
|
||
- `elevated` допускает короткоживущий токен и одноразовый токен;
|
||
- `strict` допускает только одноразовый токен.
|
||
|
||
## 8. MCP lifecycle
|
||
|
||
Поддерживаемые JSON-RPC методы:
|
||
|
||
- `initialize`
|
||
- `notifications/initialized`
|
||
- `ping`
|
||
- `tools/list`
|
||
- `tools/call`
|
||
|
||
Дополнительно на transport уровне:
|
||
|
||
- `POST /mcp/v1/{workspace_slug}/{agent_slug}` как основной MCP endpoint;
|
||
- `GET /mcp/v1/{workspace_slug}/{agent_slug}` для SSE stream;
|
||
- `DELETE /mcp/v1/{workspace_slug}/{agent_slug}` для explicit session termination, если сервер разрешает client-side session close.
|
||
|
||
### 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. возвращает результат.
|
||
|
||
### Tool call и streaming
|
||
|
||
Поддерживаются четыре execution modes:
|
||
|
||
- `unary`
|
||
- `window`
|
||
- `session`
|
||
- `async_job`
|
||
|
||
Правила публикации:
|
||
|
||
- `unary` и `window` публикуются как один tool;
|
||
- `session` публикуется как `start/poll/stop` family;
|
||
- `async_job` публикуется как `start/status/result/cancel` family.
|
||
|
||
Transport-level SSE не отменяет bounded tool semantics. Даже если `POST` отвечает через `text/event-stream`, итогом вызова должен оставаться управляемый JSON-RPC lifecycle.
|
||
|
||
## 8.1. Multiple SSE connections
|
||
|
||
Crank должен корректно работать, если MCP client держит несколько SSE streams одновременно.
|
||
|
||
Правила:
|
||
|
||
- одно server message отправляется только в один stream;
|
||
- disconnect не считается cancel;
|
||
- cancel выражается отдельным MCP notification или session/job control tool;
|
||
- resumability допустима как будущая возможность, но не обязательна в MVP.
|
||
|
||
## 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`;
|
||
- `POST` и `GET` transport semantics соответствуют MCP spec `2025-06-18`;
|
||
- endpoint определяется парой `workspace + agent`;
|
||
- одна published operation = один MCP tool внутри agent;
|
||
- streaming operations публикуются как bounded tools или tool families;
|
||
- reload published tools без пересборки сервиса;
|
||
- никакой draft-логики или admin CRUD в MCP слое.
|