Перейти к основному содержимому

Руководство оператора MCP

Настройте MCP-сервер CodeGraph, выберите профиль и проверьте формат сообщений, авторизацию, ограничения вызовов и восстановление после ошибок.

Справочник API

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

Выполняйте команды из одобренной локальной копии исходников CodeGraph с его Python-окружением и настроенными серверными зависимостями. Не запускайте второй процесс на занятом порту. Для управляемого развёртывания используйте MCP-подключение администратора вместо локального сервера из исходников. Команды запуска ниже предназначены для Bash, диагностика профиля — для PowerShell.

Канонические stdio и /mcp используют MCP 2026-07-28 без сессии протокола: каждый запрос содержит версию протокола и метаданные клиента. Запрос server/discover возвращает возможности сервера, а tools/list — каталог инструментов активного профиля.

Для стандартного MCP-клиента HTTP-адаптер /agent-plugin/mcp согласует версию 2025-11-25 или 2026-07-28 и преобразует запросы для основного MCP-сервера. Вход и настройка клиента для управляемого сервиса описаны в OAuth и MCP.

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

Если локальный клиент запускает 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

Если порт 27495 занят, выберите свободный локальный порт. Замените значение --port и порт в URL клиента одним и тем же значением.

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

Проверка каталога через stdio

Отправьте запущенному stdio-процессу это JSON-RPC-сообщение через stdin одной строкой. Ниже поля показаны с отступами; при отправке клиент сериализует сообщение в одну строку.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "docs-check",
        "version": "1"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Ответ содержит тот же id и массив result.tools. Перед вызовом инструмента посмотрите его name и inputSchema. Состав каталога определяется активным профилем.

Отправка канонического HTTP-запроса

Отправьте то же JSON-RPC-сообщение методом POST на /mcp. Вместе с данными авторизации, описанными ниже, передайте заголовки для примера tools/list:

Отправка канонического HTTP-запроса
Заголовок Значение
Content-Type application/json
Accept application/json, text/event-stream
MCP-Protocol-Version 2026-07-28
MCP-Method tools/list

Значение MCP-Method должно совпадать с method в JSON-RPC-сообщении. При несовпадении сервер возвращает mcp-method header does not match the request body's method.

Для вызова инструмента задайте MCP-Method: tools/call и заголовок MCP-Name, равный params.name в теле запроса. Например, для codegraph_project_context_status передайте MCP-Name: codegraph_project_context_status. После ответа проверьте результат инструмента: состояние denied с причиной mcp_authentication_required требует авторизации, даже если HTTP-запрос завершился кодом 200.

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

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

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

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

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

Задайте профиль в окружении процесса, который запускает сервер. Например, следующие команды явно выбирают codex. Для ролевого подключения замените codex именем профиля из настроек этого подключения.

CODEGRAPH_MCP_TOOL_PROFILE=codex python -m src.mcp --transport stdio

В PowerShell задайте переменную перед запуском:

$env:CODEGRAPH_MCP_TOOL_PROFILE = 'codex'
python -m src.mcp --transport stdio

При запуске из IDE укажите эту переменную в настройках окружения MCP-подключения. Переподключите клиент и выполните tools/list: ответ покажет выбранный каталог.

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

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-строк отклоняются сервером.
  • Передавайте story_id строкой и используйте компактные канонические идентификаторы, например handoff_v1.
  • Не передавайте db_path или другой путь к хранилищу в инструменты, вызываемые агентом. Сервер определяет хранилище из аутентифицированного контекста проекта.
  • Для выполнения задач PRD передавайте утверждения трассируемости и результаты выполнения тестов как типизированные массивы. Приёмку подтверждают требования, результаты тестов и решения ответственных ролей; код завершения команды, путь и историческая метка статуса дают операционный контекст.
  • Не составляйте вручную пакеты одобрения, финансовых данных и подтверждения полномочий. Используйте только значения, выпущенные или сохранённые авторитетным серверным процессом.

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

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

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

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

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

  1. Выполните python -m src.mcp --help и проверьте транспорт и параметры привязки.
  2. После перезапуска сервера переподключите клиент и обновите каталог инструментов, чтобы получить текущую регистрацию сервера.
  3. Проверьте активный профиль и требуемый ролевой профиль в тексте ошибки.
  4. Для HTTP сначала проверьте аутентификацию и X-Project-ID, а затем меняйте аргументы.
  5. Удалённые алиасы, замена массива строкой или числа контейнером и самостоятельно составленные подтверждения полномочий нарушают формат запроса. Исправьте аргументы по схеме инструмента.

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

  • 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-статуса.
Сообщить об ошибке в документации