---
doc_id: PRD-CK8S-PLATFORM-MCP-0001
type: prd
title: kodex — требования к platform-mcp-server
status: active
owner_role: PM
created_at: 2026-05-14
updated_at: 2026-05-28
related_issues: [747, 753, 771, 933, 698, 322]
related_prs: []
related_docsets:
  - docs/domains/platform-mcp-server/architecture/design.md
  - docs/domains/platform-mcp-server/architecture/api_contract.md
  - docs/domains/platform-mcp-server/architecture/contract_strategy.md
  - docs/domains/platform-mcp-server/delivery/platform_mcp_server_delivery.md
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-05-14-platform-mcp-kickoff"
  approved_by: "ai-da-stas"
  approved_at: 2026-05-14
---

# Требования к platform-mcp-server

## TL;DR

- Что строим: платформенный MCP-сервер как безопасную инструментальную поверхность для `agent-manager`, slot-агентов, будущих управляемых интеграций и операторов диагностики.
- Для кого: быстрый `agent-manager`, ролевые агенты в слотах, будущие управляемые интеграции и операторы диагностики.
- Почему: агентам нужен быстрый и контролируемый способ читать актуальные данные платформы и выполнять разрешённые операции без прямого обхода сервисов-владельцев.
- MVP: группы MCP-инструментов для agent/governance/provider/project/runtime/package чтений и команд, ограниченная диагностика, авторизация источника, очистка данных вызова, идемпотентность и correlation id.
- Критерии успеха: MCP не хранит чужую истину, не раскрывает секреты, маршрутизирует операции только к владельцам и даёт `agent-manager` основу для будущих возможностей запуска, сессий и ожидания governance gate.

## Проблема и цель

`agent-manager` и slot-агенты должны быстро получать актуальные данные платформы и выполнять разрешённые операции. Прямой доступ к каждому сервису из агента создаёт дублирование политик, смешивает ответственность и усложняет аудит. Нужна единая MCP-поверхность, которая нормализует вызов, проверяет источник, применяет минимальную границу политики и передаёт команду сервису-владельцу.

Цель `platform-mcp-server` — быть безопасным маршрутизатором инструментов, а не новым доменным сервисом.

## Пользователи и вызывающие стороны

| Вызывающая сторона | Потребность |
|---|---|
| Быстрый `agent-manager` | Получать инструменты для запуска, продолжения, приёмки, ожидания governance gate и чтений соседних доменов. |
| Агент в слоте | Запрашивать платформенные действия, обратную связь владельца, статус runtime и безопасные provider-сигналы. |
| Операторский контур | Получать ограниченную диагностику MCP-поверхности и зависимостей. |
| Будущие управляемые интеграции | Использовать те же правила actor/source binding и policy boundary. |

## Функциональные требования

| ID | Требование | Приоритет |
|---|---|---|
| MCP-FR-1 | Сервис должен принимать MCP-вызовы инструментов только по MCP-протоколу с явным actor/source/run/session/slot контекстом. Codex hook-события принимает отдельный `codex-hook-ingress`, а не MCP-сервер. | Обязательно |
| MCP-FR-2 | Сервис должен раскрывать инструменты через MCP discovery и execution: `tools/list` и `tools/call`. | Обязательно |
| MCP-FR-3 | Операции `Run`, session, flow, role, prompt и ожидания flow должны маршрутизироваться только в `agent-manager`. | Обязательно |
| MCP-FR-3a | Оценка риска, review signals, gate request/decision и release decision должны маршрутизироваться только в `governance-manager`; MCP не создаёт состояние решений и не делает `agent-manager` вторым владельцем gate. | Обязательно |
| MCP-FR-4 | Provider-инструменты должны использовать `provider-hub` write/read операции и не должны ходить напрямую в GitHub/GitLab. | Обязательно |
| MCP-FR-5 | Чтения project/runtime/fleet/package должны идти только к сервисам-владельцам: `project-catalog`, `runtime-manager`, `fleet-manager`, `package-hub`. | Обязательно |
| MCP-FR-6 | Запросы обратной связи, доставка запросов владельцу, уведомления и callbacks должны маршрутизироваться в `interaction-hub`, когда его контракт готов; само решение риска или релиза хранится у `governance-manager`. | Обязательно |
| MCP-FR-7 | Диагностика должна быть ограниченной: readiness, статус зависимостей, классы ошибок, короткие безопасные сообщения без больших логов. | Обязательно |
| MCP-FR-8 | Сервис должен поддерживать идемпотентные команды через `command_id` или idempotency key и единый `correlation_id`. | Обязательно |
| MCP-FR-9 | Сервис должен отклонять вызовы без проверенного source binding или с несовместимым run/slot контекстом. | Обязательно |
| MCP-FR-10 | Сервис должен публиковать или передавать аудит только для решений, отказов, risky operations и permission/gate сценариев. | Обязательно |
| MCP-FR-11 | Сервис должен передавать route/actor/source/correlation context для учёта запросов к внешним провайдерам. Provider-вызовы через MCP-инструменты или будущий CLI-proxy должны маршрутизироваться через `provider-hub`, чтобы лимиты и расход внешних API контролировались в одном контуре. | Обязательно |

Контрольные точки сжатия контекста и session snapshot нужны платформе как будущие внутренние события `agent-manager`/`runtime-manager`, но не должны описываться как MCP-инструменты или текущие Codex hooks.

## Нефункциональные требования

| Область | Требование |
|---|---|
| Безопасность | Не хранить секреты, сырые данные инструментов, полные prompt, stdout/stderr и исходные данные провайдера. |
| Надёжность | Ошибка одного сервиса-владельца не должна ломать все группы инструментов; ответ должен иметь явный класс зависимости. |
| Производительность | MCP-поверхность должна быть коротким маршрутом без тяжёлой агрегации и без чтения больших данных. |
| Ограничение нагрузки | Нужны rate limits, backpressure, размерные лимиты данных вызова, timeout на вызов владельца и учёт provider-вызовов по actor/source/tool group. |
| Наблюдаемость | Метрики по группам инструментов, отказам политики, задержкам владельцев, срабатываниям очистки и rate limits. |
| Совместимость | Внешняя MCP-поверхность версионируется отдельно от внутренних gRPC-контрактов владельцев. |

## Критерии приёмки

- Сервисная граница явно запрещает владение бизнес-состоянием.
- MVP-группы инструментов описаны без преждевременной детализации proto и AsyncAPI.
- Для каждого класса инструментов указан сервис-владелец.
- Codex hook-события вынесены из `platform-mcp-server` в отдельный `codex-hook-ingress`, а реализация hook emitter и приёма hook-событий поставляется отдельным шагом.
- Безопасность покрывает actor/source/run/slot binding, очистку данных вызова, rate limits, аудит, идемпотентность и correlation id.
- Вызовы к внешним провайдерам можно учитывать и ограничивать независимо от того, пришли они как MCP-вызов инструмента или через будущий управляемый proxy для CLI провайдера.
- Документация отделяет требования от контрактов, каркаса сервиса, hook-событий, инструментальных маршрутов, безопасности и эксплуатации.

## Не-цели

- Не описывать реализацию MCP-инструментов на уровне PRD.
- Не создавать proto, AsyncAPI, миграции или код.
- Не делать `platform-mcp-server` владельцем `Run`, slot, provider artifact, package installation, project policy или диалогов.
- Не начинать `staff-gateway`, `interaction-hub` или полноценный UI.
- Не считать описание связи с `codex-hook-ingress` реализацией hook emitter и приёма hook-событий.

## Риски

| Риск | Митигирующее решение |
|---|---|
| MCP станет скрытым монолитом. | Документы и будущий код требуют маршрутизации к владельцам, без чужой бизнес-логики и чужих таблиц. |
| В БД попадут сырые tool данные. | MVP фиксирует только безопасные сводки, решения, ссылки, отпечатки и ограниченную диагностику. |
| Provider-инструменты начнут обходить `provider-hub`. | Внешняя поверхность остаётся типизированной, а запись идёт через provider write pipeline. |
| `agent-manager` и MCP начнут дублировать gates. | MCP только принимает и маршрутизирует; `agent-manager` хранит ожидание flow и refs, `governance-manager` хранит gate/release decisions, `interaction-hub` отвечает за delivery/callback. |

## Апрув

- request_id: `owner-2026-05-14-platform-mcp-kickoff`
- Решение: approved
- Комментарий: требования к `platform-mcp-server` согласованы как целевое состояние.
