# 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

### Tool listing

При старте и после reload:

1. `mcp-server` читает список published operations.
2. Строит in-memory registry tools.
3. Отдает их через MCP list tools.

### 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` получает reload signal или выполняет controlled refresh.
4. Новый 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 слое.