crank/docs/mcp-interface.md

# 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` использует workspace-scoped `platform API keys` как machine credentials.

Контракт:

- клиент передает `Authorization: Bearer crk_...`;
- ключ должен принадлежать workspace из path;
- `read` разрешает `initialize`, `notifications/initialized`, `ping`, `tools/list`;
- `write` разрешает `tools/call`;
- `deploy` сейчас включает те же MCP права, что и `write`, и зарезервирован для deploy-scoped automation;
- успешная аутентификация обновляет `platform_api_keys.last_used_at`.

## 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 слое.