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

chk-mcp — версионирование и план развития

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

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

Документ фиксирует политику версионирования инструмента chk-mcp, его соотношение с версиями External API системы analytics.vitrip.store, и план развития (roadmap). Нужен для команд, которые планируют разрабатывать инструмент дальше или переходить на следующие версии API без потери совместимости.

Две оси версионирования​

У chk-mcp две независимые оси версии:

  1. Версия инструмента — semver x.y.z (сейчас 0.2.1). Меняется при изменениях самого пакета: новые tools, рефакторинг клиента, изменение конфигурации, исправления багов.
  2. Версия API — v1, v2, … Меняется когда analytics.vitrip.store выпускает следующую мажорную версию External API.

Эти две оси связаны, но не зависят друг от друга. Например:

  • 0.2.0 может добавить новые tools для существующего v1 (без изменений со стороны API).
  • 0.3.0 может добавить поддержку v2 параллельно с уже поддерживаемым v1.
  • 1.0.0 — стабилизация после набора production-опыта; v1 и v2 поддерживаются параллельно.

Политика поддержки версий API​

Соответствует политике External API: v1 и v2 живут параллельно. chk-mcp следует тому же принципу:

  1. Старые версии не удаляются. Когда мы добавим поддержку v2, ничего из v1-инструментов не исчезнет. Агент, написанный под v1, продолжит работать.

  2. Каждая версия API — отдельный namespace внутри пакета. Структура папок (план):

    chk_mcp/
    ├── server.py             # маршрутизация всех tools — vN_*
    ├── v1/
    │   ├── client.py         # ChkClientV1
    │   ├── errors.py
    │   └── tools.py          # описание tools для v1
    └── v2/                   # будет добавлено когда API v2 выйдет
        ├── client.py
        ├── errors.py
        └── tools.py

    Сейчас (версия 0.1.0) для упрощения кода client.py, errors.py лежат в корне пакета. При появлении v2 мы перенесём их в chk_mcp/v1/ без поломки совместимости (импорт-shim сохранит публичные имена).

  3. Префикс tool-ов содержит версию API. Сейчас tools называются chk_* (без префикса версии — потому что только v1). При появлении v2 мы переименуем tools первой версии в chk_v1_* и добавим chk_v2_*. Альтернатива — оставить chk_* для v1 как алиас для chk_v1_* ещё на одну минорную версию для плавного перехода. Решение принимается перед выпуском поддержки v2.

  4. Конфиг поддерживает обе версии одновременно. Через переменные CHK_TOKEN_V1, CHK_TOKEN_V2 или раздельный config.toml:

    [v1]
    token = "chk_..."
    base_url = "https://analytics.vitrip.store/api/external/v1/"

    [v2]
    token = "chk_..."
    base_url = "https://analytics.vitrip.store/api/external/v2/"

  5. Deprecation объявляется заблаговременно. Когда v1 будет признан устаревшим со стороны API, chk-mcp начнёт возвращать deprecation-warning в ответы tools первой версии (поле _deprecation_notice в ответе). За 6 месяцев до окончания поддержки v1 будет помечен DeprecationWarning в Python-коде, ещё за 3 месяца — выпущена мажорная версия chk-mcp, в которой v1 удалён.

Roadmap​

Roadmap фиксирует план, а не обязательство. Конкретные сроки появятся когда задачи станут активными.

Версия 0.1.0 — 29.04.2026 (выпущена)​

Готово:

  • 13 tools 1:1 с эндпоинтами External API v1.
  • Async httpx клиент.
  • Типизированные ошибки (5 классов).
  • Конфиг через env + config.toml.
  • Документация в DocMap (4 документа).

Версия 0.2.0 — 29.04.2026 (выпущена)​

Цель: production-ready состояние с автоматическими тестами и базовой телеметрией.

Готово:

  • Pytest suite: 55 тестов покрывают все 13 методов клиента, маппинг 5 типов ошибок, конфиг (env + toml + дефолты), регистрацию MCP tools, dispatch, retry-поведение. Запускается через pytest tests/.
  • Структурное логирование (chk_mcp/_logging.py) в stderr, уровень настраивается через CHK_LOG_LEVEL. Запросы/ответы логируются без раскрытия токена.
  • Retry на сетевых ошибках для GET-запросов (3 попытки, экспоненциальный backoff 0.5s/1s/2s, перехватываются ConnectError/ConnectTimeout/ReadTimeout/RemoteProtocolError). Write-методы (PATCH/POST/PUT) не ретраятся для предотвращения дублирования.
  • Sentinel для explicit null deadline в items_planning_set — клиент различает «поле не передано» и «поле передано как null», корректно пробрасывает JSON null до API.
  • JSON-Schema deadline теперь принимает ["string", "null"] — соответствует документации API.
  • Описания enum значений для priority (low/medium/high) и status (pending/in_progress/done/blocked).
  • Безопасное хранение токена: токен вынесен из ~/.claude.json в ~/.config/chk-mcp/config.toml с правами chmod 600. Backup-файл с токеном удалён.
  • Network errors оборачиваются в ChkAPIError(code="network_error") вместо raw httpx-исключений — единообразная структура ошибок.
  • CHANGELOG.md в корне проекта.

Отложено в 0.3.0:

  • CI пайплайн (GitHub Actions или локальный): lint + tests на push.
  • Опциональный rate-limit guard со стороны клиента (через httpx.AsyncBaseTransport с задержками при 429).
  • Pydantic-модели для всех успешных ответов API (сейчас работаем с dict[str, Any]).

Версия 0.2.1 — текущая (29.04.2026)​

Цель: документационный patch-релиз — выравнивание DocMap-документации под подтверждённые границы API v1, полученные от разработчика API 29.04.2026.

Готово:

  • Раздел «Каноничные правила и границы API v1» в external-api-v1-full-reference.md — переоформлен из «Наблюдения работы рантайма»; gap'ы переоформлены как сознательные решения первой версии, не недоработки.
  • Новый раздел «Roadmap post-v1» с 4 подтверждёнными направлениями: запись description, verdict / rework слой, soft-archive / inactive (вместо delete), structural editing layer (создание/переименование).
  • Quick-start (external-api-v1-quick-start.md) — три формы deadline (ISO / null / ""), минимум 16×16 px для attachments, поле status_reset на answer attachments, новый раздел «Каноничные границы v1 — что НЕЛЬЗЯ через API».
  • Tools-reference (chk-mcp-tools-reference.md) — read-only поля помечены явно (text, description, verdict, rework_*); новый раздел «Каноничные границы API v1» с альтернативными подходами для 4 типичных «невозможных» задач агента.
  • CHANGELOG.md запись 0.2.1 с подтверждениями разработчика API.

Без изменений в коде — это чисто документационный релиз для согласования терминологии и ожиданий агента с подтверждённой v1-моделью.

Версия 0.3.0 — расширения для удобства агента​

Цель: высокоуровневые композиции без нарушения принципа «один tool — один эндпоинт».

  • Композитный tool chk_items_close_with_answer (создаёт answer + меняет статус на done одним вызовом). Только если практика покажет, что агент часто делает эту пару подряд и хочет атомарного API.
  • Tool chk_session_overview — список проектов + краткая сводка по каждому (active items, overdue, recently updated). Один dashboard-запрос вместо нескольких.
  • Кеширование read-only ответов на короткое окно (5 секунд) — снижает нагрузку при последовательных вызовах одного и того же chk_items_get.

Версия 0.4.0 — поддержка следующей версии API​

Активируется при выходе External API v2.

  • Реструктуризация в chk_mcp/v1/ + chk_mcp/v2/.
  • Tools chk_v2_* рядом с существующими chk_v1_* (алиасы chk_* для v1 сохраняются).
  • Документация v2-специфики (отдельный документ chk-mcp-tools-reference-v2.md рядом с текущим).

Версия 1.0.0 — стабилизация​

Условия для 1.0.0:

  • Минимум 6 месяцев production-эксплуатации без серьёзных багов.
  • Покрытие тестов более 80%.
  • Поддержка минимум одного перехода на следующую версию API (v1 → v2).
  • Зафиксированный публичный API клиента (методы ChkClient).

Что считается breaking change​

Для версии инструмента (semver):

  • Major — удаление или переименование tool, изменение типов полей, удаление публичных методов ChkClient. Например — removal chk_items_status_set или смена id с integer на string.
  • Minor — добавление новых tools, новых опциональных полей, новых ошибок, расширение enum (новый разрешённый статус).
  • Patch — исправление багов без изменения публичного интерфейса.

Для версии API (v1/v2/…) — определяется политикой analytics.vitrip.store, см. раздел «Версионирование API» в External API v1 — полное руководство.

Принципы развития​

  1. Не агрегировать без необходимости. Соблазн сделать «удобный» tool, объединяющий несколько вызовов API, велик. Сопротивляемся: агент должен видеть прозрачное соответствие документации API. Композитные tools допускаются только если многократно подтверждённый паттерн использования (Версия 0.3.0).

  2. Не прятать ошибки. Если API вернул forbidden — агент должен это видеть, не получая сглаженный успешный ответ с пустыми полями. Ошибка — это информация, не помеха.

  3. Не блокировать агента ради «корректности». Сервер не делает retry за агента, не пытается ротировать токен, не сглаживает rate-limit. Эти решения принадлежат агенту, который видит контекст происходящего.

  4. Безопасность токена — превыше удобства. Если выбор между «удобно положить токен в args MCP-конфига» и «требовать config.toml с правами 600» — выбираем второе.

  5. Открытые стандарты. MCP — открытый протокол. httpx — стандарт для async HTTP в Python. pydantic — стандарт для типизации. Не используем замкнутые на одного провайдера решения.

Открытые вопросы и развилки​

  • Префиксование версий tools. Сохранить chk_* как алиас для chk_v1_* после появления v2 или сразу переименовать? Решение — перед началом работы над 0.4.0.
  • Хранение токена. Сейчас env + config.toml. Стоит ли поддержать системные secret-стораджи (gnome-keyring на Linux, Keychain на macOS)? Зависит от целевой аудитории — пока агент работает один на машине, файловая защита достаточна.
  • Логирование. Куда писать структурные логи запросов? stderr (попадает в логи MCP-клиента), отдельный файл ~/.local/state/chk-mcp/log.jsonl, syslog? Решение — перед 0.2.0.
  • Удалённый запуск. Сейчас сервер ожидается на той же машине, что и агент (для multipart-загрузок с локальной FS). Если понадобится удалённый запуск — нужен механизм передачи файлов (presigned upload URL или base64 в args).

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