Руководство оператора MCP — Документация CodeGraph

Этот документ нужен для запуска и диагностики MCP-сервера. Полный каталог инструментов здесь не дублируется: доступный набор зависит от активного профиля и меняется вместе с runtime. После смены профиля или перезапуска проверяйте каталог, который видит подключённый клиент.

Выбор транспорта

Если локальный клиент запускает CodeGraph как дочерний процесс, используйте stdio:

python -m src.mcp --transport stdio

Для Streamable HTTP задайте адрес явно и подключайте клиент к http://127.0.0.1:27495/mcp:

python -m src.mcp --transport http --host 127.0.0.1 --port 27495

Поддерживаются только stdio и http. SSE и прежние совместимые SSE-маршруты удалены.

Аутентификация и область проекта

Stdio считается доверенным локальным транспортом. HTTP по умолчанию требует аутентификацию через Authorization: Bearer <jwt> или X-API-Key: <api-key>. Для сетевых вызовов с областью проекта передавайте X-Project-ID: сервер сопоставляет его с аутентифицированной учётной записью и отклоняет несовпадающие project_key и namespace.

Флаг --no-auth предназначен только для локальной разработки. Команда завершится ошибкой, если не включён параметр security.mcp_allow_no_auth_network_transports; сервер без аутентификации разрешено привязать только к loopback-адресу:

python -m src.mcp --transport http --host 127.0.0.1 --port 27495 --no-auth

Вызов инструмента разрешается после проверки роли, точного носителя и сохранённого approval внутри обработчика. Full- и ролевой профиль задают доступный каталог инструментов.

Выбор и проверка профиля

Без переменной CODEGRAPH_MCP_TOOL_PROFILE команда запускает профиль codex. Для инструментов конкретной линии штатно используются owner-профили. Актуальный каталог инструментов определяйте по выбранному профилю.

В исходном checkout вычисляйте текущий размер профиля, а не переносите число в документацию:

$env:CODEGRAPH_MCP_TOOL_PROFILE = "full"
python -c "from src.mcp.surface_catalog import profile_family_tool_names; print(len(profile_family_tool_names('full')))"

profile_family_tool_names подходит для локальной диагностики исходников. Фактическим подтверждением остаётся каталог, который возвращает запущенный MCP-сервер.

Канонический wire-контракт

Совместимый вход для структурированных полей — нативные массивы и объекты. Удалённые алиасы *_json и контейнеры в виде JSON-строк завершаются fail-closed.
Передавайте story_id строкой и используйте компактные канонические идентификаторы, например handoff_v1.
Не передавайте db_path или другой путь к хранилищу в agent-facing инструменты. Runtime определяет хранилище из аутентифицированного контекста проекта.
Для PRD execution передавайте traceability assertions и test executions нативными типизированными массивами. Приёмку подтверждают требования, результаты тестов и решения ответственных линий; код завершения команды, путь и историческая метка статуса дают операционный контекст.
Не конструируйте approval-, finance- и authority-пакеты вручную. Используйте только значения, выпущенные или сохранённые авторитетным серверным процессом.

Поддерживаемые представления PRD-статуса

codegraph_digital_employee_prd_delivery_status принимает только следующие значения view:

Поддерживаемые представления PRD-статуса
Представление	Назначение
`full`	Полный статус.
`only_blockers`	Компактная проекция блокеров.
`only_pending`	Компактная проекция ожидающих handoff.
`closure_summary`	Блокеры, ожидающие handoff и агрегаты по линиям.
`latest_chain`	Эффективные элементы текущей цепочки handoff.
`projection_gaps`	Разрывы story-проекций и блокеры.

Любое другое значение возвращает unsupported_status_view; алиасов summary и compact нет.

Диагностика неуспешного вызова

Выполните python -m src.mcp --help и проверьте транспорт и параметры привязки.
После перезапуска сервера переподключите клиент и обновите кеш discovery, чтобы получить текущую runtime-регистрацию.
Проверьте активный профиль и требуемый owner-профиль в тексте ошибки.
Для HTTP сначала проверьте аутентификацию и X-Project-ID, а затем меняйте аргументы.
Удалённые алиасы, scalar/container coercion и самостоятельно составленные authority-пакеты — ошибки контракта. Не повторяйте вызов с fallback-формой.

Источники истины

src/mcp/__main__.py — транспорты CLI, привязка, аутентификация и выбор профиля.
src/mcp/surface_catalog.py — семейства профилей, ролевые проекции и удалённые инструменты.
src/mcp/auth.py — HTTP-аутентификация и каноническая привязка области проекта.
src/digital_employees/planning/delivery/prd_delivery_actions_projection_parts/compact_handoffs.py — точный набор представлений PRD-статуса.