chk-mcp — справочник инструментов

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

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

Полный каноничный справочник по 13 инструментам MCP-сервера chk-mcp. Для каждого tool описано: каноничное назначение, обязательные и опциональные поля, требуемые scope, примеры запроса, формат ответа, типичные ошибки.

Это документ для MCP-агента, который вызывает tools напрямую, и для разработчика, который пишет код, использующий клиент ChkClient напрямую (без MCP-обёртки). Полный референс самого API смотри в External API v1 — полное руководство.

Общие правила

Формат ответа

Все tools при успехе возвращают data-часть API-envelope как JSON-строку в TextContent. То есть оригинальный API-ответ:

{"ok": true, "data": {...}, "meta": {...}}

…превращается в JSON {...} — только содержимое data. meta.request_id доступен только в ошибках (для трассировки) — в успешных ответах он отбрасывается, чтобы не засорять контекст агента.

Формат ошибки

При ошибке tool возвращает payload вида:

{
  "error": {
    "code": "scope_missing",
    "message": "У токена нет нужного scope",
    "http_status": 403,
    "request_id": "req_xxxxxxxxxxxx"
  }
}

Для нереалистичных ошибок (отсутствие сети, парс-ошибка JSON, отсутствие файла при upload) — поле code будет internal или non_json_response.

Идемпотентность

GET-вызовы идемпотентны — можно повторять. PATCH/POST/PUT — не повторять автоматически при сетевых ошибках, чтобы не дублировать действия (комментарии, ответы, attachments). Если ответ не пришёл, проверить состояние через chk_items_get перед повторной попыткой.

1. chk_auth_me

Назначение. Проверить токен и узнать, под каким пользователем работает сервер.

Когда вызывать. Первым после регистрации сервера, чтобы убедиться что всё работает. Не нужен для штатной работы.

Scope: auth:me.

Поля: нет.

Ответ:

{
  "user": {"id": 3, "name": "Олександр Носаков", "role": "admin"},
  "token": {
    "label": "Claude",
    "scopes": ["auth:me", "projects:read", "..."],
    "expires_at": null
  }
}

2. chk_projects_list

Назначение. Получить список проектов, видимых пользователю.

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

Scope: projects:read.

Поля:

Поле	Тип	Required	Описание
`limit`	integer (1–200)	нет	Максимум проектов в ответе
`offset`	integer (≥0)	нет	Сдвиг для пагинации
`archived`	boolean	нет	Включить архивные проекты (по умолчанию — без них)

Пример:

{"limit": 20, "archived": false}

Ответ: объект {projects: [...]}, где каждый проект содержит id, name, description, deadline, verdict, is_archived, archived_at, created_at, updated_at, overdue_count, due_tomorrow_count, sections_count, progress, project_wide_visibility.

3. chk_projects_get

Назначение. Получить карточку одного проекта по id.

Scope: projects:read.

Поля:

Поле	Тип	Required
`id`	integer	да

Пример: {"id": 15}

Ответ: объект проекта с теми же полями, что в chk_projects_list, плюс детализация (например, расширенная статистика).

4. chk_projects_tree

Назначение. Получить полную структуру проекта: разделы → чек-листы → пункты.

Когда вызывать. Когда нужен общий обзор структуры выбранного проекта.

Scope: projects:read.

Поля:

Поле	Тип	Required
`id`	integer	да

Замечание. Если у пользователя неполный доступ к части проекта, дерево вернётся усечённым — без скрытых разделов.

5. chk_projects_search

Назначение. Поиск внутри проекта по содержимому: названиям, текстам пунктов, ответам, комментариям, ссылкам.

Когда вызывать. Главный рабочий сценарий поиска нужного item_id в большом проекте: знаем project_id, ищем по ключевому слову, находим пункт, работаем дальше по точному item_id.

Scope: projects:search.

Поля:

Поле	Тип	Required	Описание
`id`	integer	да	Project_id для поиска
`q`	string	нет	Текст поискового запроса
`entity_type`	string	нет	Сузить до одного типа: `item` / `answer` / `comment` / `link`
`item_id`	integer	нет	Точечный поиск по конкретному пункту (полезно для проверки наличия)
`limit`	integer (1–200)	нет	Максимум результатов
`offset`	integer (≥0)	нет	Сдвиг для пагинации

Пример:

{"id": 15, "q": "API documentation", "entity_type": "item", "limit": 50}

6. chk_items_get

Назначение. Получить полную карточку пункта со всем содержимым.

Scope: items:read.

Поля:

Поле	Тип	Required
`id`	integer	да

Ответ. Объект пункта с полями: text, description, status, deadline, priority, requires_answer, participants, comments[], answers[], attachments[], document_links[], verdict, rework_reason, rework_deadline, status_history[], member_scopes, effective_participants, can_* флаги.

Внимание. Поля text, description, verdict, rework_* в API v1 — read-only. Их можно читать, но менять через API нельзя. См. раздел «Каноничные границы v1» ниже.

7. chk_items_status_set

Назначение. Изменить статус пункта.

Scope: items:status.write.

Поля:

Поле	Тип	Required	Допустимые значения
`id`	integer	да	—
`status`	string (enum)	да	`pending` / `in_progress` / `done` / `blocked`

Пример:

{"id": 299, "status": "in_progress"}

Типичные сценарии: агент берётся за пункт → in_progress. Агент завершил работу → done. Внешняя зависимость заблокировала прогресс → blocked (с комментарием через chk_comments_create).

8. chk_items_planning_set

Назначение. Обновить плановые поля пункта: дедлайн, приоритет, флаг «требуется развёрнутый ответ».

Scope: items:planning.write.

Поля:

Поле	Тип	Required	Описание
`id`	integer	да	—
`deadline`	string \| null	нет	Три каноничные формы: ISO-строка `YYYY-MM-DD` устанавливает; `null` или пустая строка `""` очищают
`priority`	string (enum)	нет	`low` / `medium` / `high`
`requires_answer`	boolean	нет	Требуется ли развёрнутый ответ-артефакт

Замечание. Передаются только те поля, которые нужно изменить. Опущенные не трогаются.

Очистка дедлайна. Чтобы убрать дедлайн, передавай явный JSON null. Этот способ канонический и поддерживается JSON-Schema MCP-tool'а напрямую (тип ["string", "null"]). Пустая строка "" тоже принимается рантаймом — но null предпочтительнее.

9. chk_items_links_set

Назначение. Полностью заменить список document_links у пункта.

Scope: items:materials.write.

Поля:

Поле	Тип	Required	Описание
`id`	integer	да	—
`document_links`	array	да	Полный итоговый список ссылок

Каждая ссылка:

{"kind": "document", "title": "...", "url": "https://..."}

Внимание. Это не «добавить одну ссылку». Это «записать итоговый список». Если хочешь добавить ссылку к существующим — сначала вычитай текущий список через chk_items_get, затем дополни и пошли весь массив. Очистка всех ссылок: {"id": 299, "document_links": []}.

10. chk_items_attachments_upload

Назначение. Загрузить изображения в пункт.

Scope: items:materials.write.

Поля:

Поле	Тип	Required	Описание
`item_id`	integer	да	—
`file_paths`	array of strings	да	Локальные абсолютные пути к файлам

Замечание. Текущий runtime принимает изображения (PNG, JPG, GIF, WebP), не произвольные файлы. Текстовые файлы будут отклонены.

Минимальный рабочий размер — 16×16 пикселей. Изображения меньше отвергаются с 422 validation_error. Рантайм всегда конвертирует загруженное изображение в WebP при сохранении в Cloudflare R2. URL для отдачи файла: /api/items/file.php?id=NNN.

Замечание 2. Файлы читаются с локальной файловой системы MCP-сервера. Это работает потому что сервер запущен на той же машине, что и агент. Удалённый MCP-сервер потребует другой подход (передача через base64 или предварительная загрузка в общий storage).

11. chk_comments_create

Назначение. Добавить текстовый комментарий в пункт.

Scope: comments:write.

Поля:

Поле	Тип	Required	Описание
`item_id`	integer	да	—
`text`	string	да	Текст комментария (минимум 1 символ)

Замечание. Комментарий — только текст. Файлы и ссылки в комментарии не поддерживаются. Для содержательного результата работы используй chk_answers_create (там можно прикладывать ссылки).

12. chk_answers_create

Назначение. Создать содержательный ответ-артефакт по пункту с возможным набором ссылок.

Scope: answers:write.

Поля:

Поле	Тип	Required	Описание
`item_id`	integer	да	—
`text`	string	да	Текст ответа (минимум 1 символ)
`document_links`	array	нет	Список ссылок (формат как в `chk_items_links_set`)

Пример:

{
  "item_id": 299,
  "text": "Готово. Документ создан в DocMap.",
  "document_links": [
    {"kind": "document", "title": "Архитектура", "url": "https://docs.example.com/arch.md"}
  ]
}

13. chk_answers_attachments_upload

Назначение. Загрузить изображения в существующий answer.

Scope: items:materials.write.

Поля:

Поле	Тип	Required	Описание
`answer_id`	integer	да	id ответа, в который грузим
`file_paths`	array of strings	да	Локальные абсолютные пути к файлам

Замечания. Идентичны chk_items_attachments_upload — только изображения, локальная FS, минимум 16×16 пикселей.

Поле status_reset в ответе. Эндпоинт возвращает status_reset: boolean. Если true — статус ответа был сброшен в pending при загрузке (например, ответ был approved/rejected, и добавление вложений требует повторного review). Если false — статус не менялся.

Каноничные границы API v1

Чтобы агент не пытался делать невозможное и не строил планы вокруг отсутствующих возможностей — список того что сознательно не входит в scope v1:

Read-only поля

Эти поля возвращаются в chk_items_get, но изменить их через API v1 нельзя:

text пункта — текст пункта;
description пункта — описание;
verdict, rework_reason, rework_deadline — verdict workflow.

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

Структурные операции

В v1 нельзя через API:

создавать новые проекты, разделы, чек-листы, пункты;
переименовывать существующие;
удалять comments, answers, attachments, links (в системе нет понятия удаления — только soft-archive в roadmap post-v1);
управлять verdict / rework workflow.

Если задача предполагает создание новой структуры (новый раздел, новый пункт) — это вне scope v1. Просьбу к человеку добавить через веб-интерфейс, потом продолжить работу через API.

Что это значит для каноничных сценариев агента

«Создать новый пункт по результатам анализа» — невозможно. Альтернатива: попросить пользователя создать пункт, потом агент возьмётся за заполнение через chk_items_status_set, chk_comments_create, chk_answers_create.
«Переписать описание пункта» — невозможно. Альтернатива: добавить детальный комментарий или answer с пояснением.
«Удалить ошибочно созданный комментарий» — невозможно. Подход: добавить новый комментарий с пометкой «отменяет предыдущий», ждать soft-archive в следующих версиях API.
«Одобрить пункт» (verdict) — невозможно. Альтернатива: пометить done через status_set, ждать verdict-эндпоинтов в post-v1.

Полная сводка границ — в external-api-v1-full-reference.md, раздел «Каноничные правила и границы API v1».

Справочник scope → tools

Scope	Tools
`auth:me`	`chk_auth_me`
`projects:read`	`chk_projects_list`, `chk_projects_get`, `chk_projects_tree`
`projects:search`	`chk_projects_search`
`items:read`	`chk_items_get`
`items:status.write`	`chk_items_status_set`
`items:planning.write`	`chk_items_planning_set`
`items:materials.write`	`chk_items_links_set`, `chk_items_attachments_upload`, `chk_answers_attachments_upload`
`comments:write`	`chk_comments_create`
`answers:write`	`chk_answers_create`

Если получаешь {error: {code: "scope_missing"}} — токен не имеет нужного scope. Перевыпустить с расширенным набором (см. документ про установку и регистрацию).

Каноничные сценарии работы агента

Сценарий 1: «обновить статус пункта по ходу работы»

chk_projects_search({id: 15, q: "ключевое слово"}) — найти пункт.
chk_items_get({id: <item_id>}) — прочитать карточку.
chk_items_status_set({id: <item_id>, status: "in_progress"}) — взять в работу.
(после выполнения) chk_comments_create({item_id: <item_id>, text: "..."}) или chk_answers_create({...}).
chk_items_status_set({id: <item_id>, status: "done"}) — закрыть.

Сценарий 2: «загрузить артефакт работы»

chk_answers_create({item_id: <item_id>, text: "Готово", document_links: [...]}) — создать ответ.
chk_answers_attachments_upload({answer_id: <answer_id>, file_paths: ["/path/to/screenshot.png"]}) — приложить картинки.

Сценарий 3: «обзор проекта в начале сессии»

chk_projects_list() — что доступно.
chk_projects_get({id: <project_id>}) — детали по выбранному проекту.
chk_projects_tree({id: <project_id>}) — увидеть всю структуру.

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

chk-mcp — архитектура — что это и зачем.
Установка и регистрация в Claude MCP — как поставить.
Версионирование и roadmap — что дальше.
External API v1 — полное руководство — каноничный референс API.

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

Общие правила​

Формат ответа​

Формат ошибки​

Идемпотентность​

1. chk_auth_me​

2. chk_projects_list​

3. chk_projects_get​

4. chk_projects_tree​

5. chk_projects_search​

6. chk_items_get​

7. chk_items_status_set​

8. chk_items_planning_set​

9. chk_items_links_set​

10. chk_items_attachments_upload​

11. chk_comments_create​

12. chk_answers_create​

13. chk_answers_attachments_upload​

Каноничные границы API v1​

Read-only поля​

Структурные операции​

Что это значит для каноничных сценариев агента​

Справочник scope → tools​

Каноничные сценарии работы агента​

Сценарий 1: «обновить статус пункта по ходу работы»​

Сценарий 2: «загрузить артефакт работы»​

Сценарий 3: «обзор проекта в начале сессии»​

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

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

Общие правила

Формат ответа

Формат ошибки

Идемпотентность

1. chk_auth_me

2. chk_projects_list

3. chk_projects_get

4. chk_projects_tree

5. chk_projects_search

6. chk_items_get

7. chk_items_status_set

8. chk_items_planning_set

9. chk_items_links_set

10. chk_items_attachments_upload

11. chk_comments_create

12. chk_answers_create

13. chk_answers_attachments_upload

Каноничные границы API v1

Read-only поля

Структурные операции

Что это значит для каноничных сценариев агента

Справочник scope → tools

Каноничные сценарии работы агента

Сценарий 1: «обновить статус пункта по ходу работы»

Сценарий 2: «загрузить артефакт работы»

Сценарий 3: «обзор проекта в начале сессии»

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