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

chk-mcp — MCP-сервер для External API v1 — архитектура

Версия документа: 1.0 Версия инструмента: 0.2.1 Дата: 29.04.2026 Статус: Готов к обсуждению

Назначение документа​

Документ описывает каноничный смысл, архитектуру и место chk-mcp в общей системе работы с проектным трекером analytics.vitrip.store. Это первый документ для тех, кто хочет понять, что это за инструмент и зачем он существует.

Что это такое​

chk-mcp — Model Context Protocol (MCP) сервер на Python 3.11+, дающий любому MCP-клиенту (главный потребитель — Claude Code и Codex) прямой типизированный доступ к External API v1 системы analytics.vitrip.store через 13 каноничных инструментов, отображаемых 1:1 с эндпоинтами API.

Где живёт код: /mnt/d/SITES/chk-mcp/ (отдельный проект, не часть DocMap).

Зачем нужен​

Цель — дать ИИ-агенту, который ведёт проект, тот же уровень работы с трекером, какой есть у человека через веб-интерфейс. Без MCP-сервера агенту пришлось бы:

  • вызывать Bash(curl -X PATCH ...) каждый раз — рукописно, без типизации, с риском ошибок;
  • парсить текстовый JSON-вывод как строку;
  • вручную следить за заголовком Authorization: Bearer ... в каждом вызове;
  • вручную обрабатывать {ok: false, error: {...}};
  • хранить и подставлять токен в каждый вызов.

С MCP-сервером агент видит инструмент chk_items_status_set со схемой {id, status} как нативный tool рядом с Read, Bash, Edit. Вызывает его как обычную функцию, получает структурированный ответ или типизированную ошибку, не задумываясь о токене и заголовках.

Каноничные принципы​

  1. Один эндпоинт API — один MCP-tool. Никаких агрегирующих обёрток, которые «удобнее»: chk_create_task_with_links_and_attachments — антипаттерн. 13 эндпоинтов External API v1 → 13 tools chk_*. Это даёт агенту явное соответствие документации API и позволяет точно понимать, что произошло на каждом шаге.

  2. Типизированные input-схемы через JSON-Schema. Каждый tool описывает свои поля: required, optional, типы, enum для статусов и приоритетов. MCP-клиент видит схему, агент в подсказках видит нужные поля.

  3. Структурированные ошибки. API возвращает {ok: false, error: {code, message}} — сервер маппит каждый код в типизированное Python-исключение (TokenError, ScopeError, ForbiddenError, NotFoundError, ValidationError) и возвращает агенту в виде {error: {code, message, http_status, request_id}}. Агент видит код и понимает, что делать (попросить новый токен, добавить scope, исправить тело запроса).

  4. Безопасное обращение с токеном. Токен живёт в переменной окружения CHK_TOKEN или в файле ~/.config/chk-mcp/config.toml. В логах не появляется. В ответах MCP не возвращается (только auth/me показывает label и список scope, но не сам raw token).

  5. Версионирование API заложено. Этот сервер работает с External API v1. Когда выйдет v2, рядом появится модуль chk_mcp.v2.client и tools chk_v2_*, не заменяющие текущие. Подробнее — см. документ про версионирование и roadmap.

  6. Работа от имени пользователя, не от имени агента. Это унаследовано от модели External API: токен привязан к конкретному пользователю системы (в нашем случае — admin Олександр Носаков), агент действует под его правами. Сервер не скрывает этот факт — auth/me показывает, кто именно подключён.

Архитектура (слои)​

┌─────────────────────────────────────────────────────────────┐
│  MCP-клиент (Claude Code, Codex, любой другой MCP-агент)    │
└─────────────────────────────────────────────────────────────┘
                            │
                            │  stdio, MCP-протокол
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  chk_mcp.server (chk_mcp/server.py)                         │
│  ─ регистрация 13 tools со схемами                          │
│  ─ обработчик call_tool: маршрутизация на ChkClient         │
│  ─ форматирование ответа (TextContent + JSON)               │
│  ─ маппинг исключений → структурированные ошибки агента     │
└─────────────────────────────────────────────────────────────┘
                            │
                            │  Python-вызовы
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  chk_mcp.client.ChkClient (chk_mcp/client.py)               │
│  ─ async-обёртка httpx с предустановленным auth-заголовком  │
│  ─ 13 методов 1:1 с эндпоинтами API                         │
│  ─ распаковка `{ok, data, error, meta}` → data или raise    │
│  ─ корректное закрытие multipart-файлов после загрузки      │
└─────────────────────────────────────────────────────────────┘
                            │
                            │  HTTP/HTTPS
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  https://analytics.vitrip.store/api/external/v1/            │
│  External API v1 (PHP runtime — actual production)          │
└─────────────────────────────────────────────────────────────┘

Поддерживающие модули​

  • chk_mcp.config — загрузка токена и base URL: env-переменные имеют приоритет, fallback на ~/.config/chk-mcp/config.toml. Дефолтный base URL — https://analytics.vitrip.store/api/external/v1/.
  • chk_mcp.errors — иерархия исключений + функция from_response(http_status, code, message, request_id), возвращающая нужный тип исключения по HTTP-статусу и коду ошибки.
  • chk_mcp.__main__ — точка входа python -m chk_mcp. Поднимает stdio-сервер и блокируется до отключения клиента.

Жизненный цикл вызова​

  1. MCP-клиент инициализирует соединение через stdio.
  2. MCP-клиент вызывает list_tools() — сервер возвращает 13 tools со схемами.
  3. Агент вызывает один из tools, например chk_items_status_set с {id: 299, status: "in_progress"}.
  4. Сервер в обработчике call_tool разворачивает аргументы и вызывает client.items_status_set(299, "in_progress").
  5. ChkClient делает PATCH /items/status.php с заголовком Authorization: Bearer ... и телом {"id": 299, "status": "in_progress"}.
  6. API возвращает {ok: true, data: {...}, meta: {request_id: "req_xxx", api_version: "v1"}}.
  7. ChkClient разворачивает envelope, возвращает data как dict.
  8. Сервер сериализует dict в JSON-строку (с поддержкой UTF-8 для русских/украинских названий) и оборачивает в TextContent.
  9. Агент получает структурированный ответ.

При ошибке шаг 6–7 заменяется: ChkClient видит {ok: false}, бросает TokenError/ScopeError/etc., сервер ловит, форматирует payload {error: {...}} и возвращает агенту тем же способом — через TextContent.

Связанная документация​