# Подключение к Ritodo через MCP

> Спецификация для агента и разработчика клиента: транспорт, аутентификация, права (scopes), инструменты, ошибки и правила безопасных изменений MCP-сервера Ritodo.

## Транспорт

- Адрес: `https://app.ritodo.com/api/v1/mcp`.
- Streamable HTTP, JSON-RPC 2.0. Версия протокола `2025-06-18`; принимаются также `2025-03-26` и `2024-11-05`.
- Только `POST`. `GET` возвращает `405` (серверных SSE-потоков нет).
- Методы: `initialize`, `ping`, `tools/list`, `tools/call`, `prompts/list`, `prompts/get`. Уведомления (запрос без `id`) принимаются с ответом `202`. Пакеты (массивы) не поддерживаются.
- Если клиент шлёт заголовок `Origin`, он должен входить в список разрешённых сервером.

## Аутентификация

Заголовок `Authorization: Bearer tnd_…`. Токен пользователь выпускает сам в приложении, раздел «MCP-доступ»: название, срок (30 дней, 90 дней, 1 год или бессрочно) и права. Секрет показывается один раз; сервер хранит только отпечаток, поэтому потерянный токен восстановить нельзя — его заменяют новым.

## Права (scopes)

`board:read`, `board:write`, `board:delete`, `task:read`, `task:write`, `task:delete`, `comment:read`, `comment:write`, `tag:read`, `tag:write`, `tag:delete`, `attachment:read`.

`write` включает `read` своей группы. `delete` не включает `write`. Список `tools/list` содержит только инструменты, доступные токену: не пытайтесь вызывать то, чего там нет.

## Инструменты

| Группа | Инструменты | Минимальное право |
| --- | --- | --- |
| Доски | `boards_list`, `boards_get` | `board:read` |
| Доски | `boards_create`, `boards_update`, `boards_archive` | `board:write` |
| Доски | `boards_delete` (нужен `confirm=true`) | `board:delete` |
| Задачи | `tasks_list`, `tasks_get`, `tasks_time_entries_list` | `task:read` |
| Задачи | `tasks_create`, `tasks_update`, `tasks_move`, `tasks_archive`, `tasks_restore`, `tasks_copy`, `tasks_plan`, `tasks_time_entries_create`, `tasks_time_entries_update`, `tasks_time_entries_delete` | `task:write` |
| Задачи | `tasks_delete` (нужен `confirm=true`) | `task:delete` |
| Комментарии | `comments_list` | `comment:read` |
| Комментарии | `comments_create`, `comments_update`, `comments_delete` | `comment:write` |
| Теги | `tags_list`, `tags_get` | `tag:read` |
| Теги | `tags_create`, `tags_update`, `tags_attach`, `tags_detach` | `tag:write` |
| Теги | `tags_delete` (нужен `confirm=true`) | `tag:delete` |
| Вложения | `attachments_list` (только метаданные проверенных файлов) | `attachment:read` |

Точные схемы аргументов берите из `tools/list`, а не из памяти: они — источник истины.

## Готовые сценарии (prompts)

- `decompose_task(task_id)` — разбить задачу на подзадачи.
- `triage_inbox(board_id)` — разобрать входящие.

Оба требуют права `task:write`. Подробности — в [сценариях работы агента](https://ritodo.com/agents/playbooks.md).

## Ошибки

Ошибка инструмента приходит в результате с `isError=true`, а в `structuredContent` лежат `code` и `message`.

| Код | Что делать |
| --- | --- |
| `not_found` | Объекта нет или он чужой; не повторять с тем же id |
| `insufficient_scope` | Токену не хватает права; сообщить пользователю, какое нужно |
| `invalid_arguments` | Исправить аргументы по схеме из `tools/list` |
| `version_conflict` | Задачу изменили; перечитать её и повторить с актуальной версией (`current_version` в `data`) |
| `confirmation_required` | Спросить пользователя и только после согласия повторить с `confirm=true` |
| `tag_name_conflict`, `conflict` | Такое имя или состояние уже есть; выбрать другое или перечитать |

HTTP-уровень: `401` — токен неверен, истёк, отозван или пользователь заблокирован; `403` — запрещённый `Origin`; `429` — превышен лимит вызовов, ждите `Retry-After` секунд (по умолчанию лимит 120 вызовов в минуту на токен).

## Правила безопасных изменений

1. **Перед записью — чтение.** `tasks_update` требует `expected_version`; берите версию из свежего `tasks_get`.
2. **Удаление только с согласия человека.** Удаляйте по конкретному id и с `confirm=true`; массового удаления по фильтру нет. Предпочитайте `tasks_archive`.
3. **Повторы безопасны для создания.** Передавайте `idempotency_key` в создающих инструментах: повторный запрос вернёт тот же объект.
4. **Всё журналируется.** Каждый вызов попадает в аудит токена (без аргументов), изменения задач помечаются источником `mcp`. Пользователь видит последние 20 вызовов и может отозвать токен мгновенно.
5. **Минимум прав.** Просите у пользователя «Только чтение» для анализа и «Чтение и запись» для планирования; полный доступ не нужен для большинства задач.

## Подключение клиента

- Claude Code: `claude mcp add` с адресом сервера и заголовком `Authorization`.
- Cursor и VS Code: запись в `mcpServers` с `url` и `headers`.
- Claude Desktop: через `mcp-remote`.

Готовые команды с подставленным адресом и токеном показывает карточка «Подключение» в приложении.