Initialize project scaffold and domain model

docs/mcp-interface.md

@@ -0,0 +1,162 @@
+# 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 слое.