docs: redesign architecture around workspaces and agents

docs/mcp-interface.md

@@ -2,40 +2,34 @@
 
 ## 1. Назначение документа
 
-Этот документ фиксирует, как именно платформа публикует operations в виде MCP tools и какой transport используется в MVP.
-
-Главная цель - убрать неопределенность вокруг вопроса "каким именно будет MCP server" до начала реализации.
+Этот документ фиксирует, как именно платформа публикует agents и operations в виде MCP tools и какой transport используется в целевой модели.
 
 ## 2. Архитектурное решение
 
-Для MVP `mcp-server` должен публиковать tools через network-oriented MCP transport.
+`mcp-server` публикует tools через network-oriented MCP transport.
 
-Рекомендуемое решение:
+Решение:
 
 - основной transport: `Streamable HTTP`;
 - отдельный `mcp-server` как сервис;
-- `stdio` не является обязательной частью MVP.
-
-Причина:
-
-- проект задуман как `Crank`, а не как локальный single-process adapter;
-- нужен удаленный доступ к опубликованным tools;
-- published tools должны обновляться без пересборки и без локального обертывания каждого клиента.
+- `stdio` не является обязательной частью текущего scope.
 
 ## 3. Модель публикации tools
 
-Каждая published operation превращается в один MCP tool.
+Каждая published operation превращается в один MCP tool внутри конкретного published agent.
 
 Соответствие:
 
-- одна published version;
-- один tool name;
+- один published agent;
+- набор `AgentOperationBinding`;
+- один tool name на binding;
 - одна input schema;
 - один результат.
 
 Публикация tool основана на:
 
-- `operation.name`
+- `agent.slug`
+- `operation.name` или binding-level `tool_name`
 - `tool_description`
 - `input_schema`
 - `published runtime view`
@@ -44,7 +38,7 @@
 
 `mcp-server` должен:
 
-- загрузить published operations из registry;
+- загрузить published agents и их bindings из registry;
 - преобразовать их в MCP tool definitions;
 - принимать вызовы tools от MCP clients;
 - валидировать вход;
@@ -62,12 +56,12 @@
 - заниматься protobuf discovery;
 - содержать бизнес-логику admin UI.
 
-## 6. Published runtime view
+## 6. Runtime view
 
-`mcp-server` должен работать не с полной admin-конфигурацией, а с runtime-ready view.
-
-В published runtime view остаются:
+В runtime view остаются:
 
+- `workspace_id`
+- `agent_id`
 - `operation_id`
 - `protocol`
 - `target`
@@ -78,29 +72,30 @@
 - `execution_config`
 - `tool_description`
 
-В published runtime view не должны попадать:
+В runtime view не попадают:
 
 - raw uploaded samples;
 - generated draft metadata;
 - YAML import metadata;
 - UI-specific helper fields.
 
-## 7. Transport для MVP
+## 7. MCP endpoint model
 
-### Поддерживается
+Канонический endpoint:
 
-- `Streamable HTTP`
+```text
+/mcp/v1/{workspace_slug}/{agent_slug}
+```
 
-### Не обязательно в MVP
+Этот endpoint определяет:
 
-- `stdio`
-- дополнительные transport adapters
-
-Если позже понадобится локальная интеграция, `stdio` можно добавить как отдельный transport layer поверх того же runtime.
+- tenant boundary;
+- конкретный curated toolset;
+- набор usage и log labels.
 
 ## 8. MCP lifecycle
 
-MVP-контракт `mcp-server` строится вокруг JSON-RPC методов MCP:
+Поддерживаемые JSON-RPC методы:
 
 - `initialize`
 - `notifications/initialized`
@@ -108,37 +103,32 @@ MVP-контракт `mcp-server` строится вокруг JSON-RPC мет
 - `tools/list`
 - `tools/call`
 
-Сессия создается на `initialize` и идентифицируется через `MCP-Session-Id`.
-Согласованная версия протокола возвращается и читается через `MCP-Protocol-Version`.
-
-Пока сессии хранятся in-memory внутри `mcp-server`, чего достаточно для MVP и demo-сценариев.
-
 ### Tool listing
 
-После `initialize` и `notifications/initialized`:
-
 1. клиент вызывает `tools/list`;
-2. `mcp-server` перечитывает published operations по refresh policy;
-3. строит или обновляет in-memory catalog tools;
-4. отдает список tools через MCP JSON-RPC result.
+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. MCP client вызывает tool.
-2. `mcp-server` находит published runtime view.
-3. Валидирует input относительно schema.
-4. Делегирует вызов в `crank-runtime`.
-5. Возвращает результат.
+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.
-3. `mcp-server` не требует restart и не опирается на ручной reload signal.
-4. `mcp-server` выполняет controlled refresh опубликованного каталога по interval-based policy.
-5. Новый tool contract становится доступен MCP clients.
+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
 
@@ -150,9 +140,9 @@ MVP-контракт `mcp-server` строится вокруг JSON-RPC мет
 
 Требования:
 
-- имя уникально в пределах платформы;
-- имя не зависит от внутреннего numeric version;
-- rename operation должен считаться отдельным осознанным изменением.
+- имя уникально в пределах одного agent;
+- имя не зависит от numeric version;
+- один и тот же operation может публиковаться под разными именами в разных agents.
 
 ## 11. Ошибки MCP слоя
 
@@ -164,14 +154,11 @@ MVP-контракт `mcp-server` строится вокруг JSON-RPC мет
 - external service error;
 - internal runtime error.
 
-`mcp-server` не должен терять стадию ошибки при трансляции ответа клиенту.
-
 ## 12. Практический итог
 
-Для MVP достаточно следующей фиксации:
-
 - `mcp-server` - отдельный сервис;
 - transport - `Streamable HTTP`;
-- одна published operation = один MCP tool;
+- endpoint определяется парой `workspace + agent`;
+- одна published operation = один MCP tool внутри agent;
 - reload published tools без пересборки сервиса;
 - никакой draft-логики или admin CRUD в MCP слое.