Todoha MCP Model Context Protocol

Подключение LLM-агентов (Claude Desktop, Claude Code, Cursor, …) к Todoha — управление задачами через MCP-tools поверх того же публичного API.

1. Endpoint

URL: POST /api/public/v1/mcp
Transport: Streamable HTTP (JSON-RPC 2.0)
Auth: Bearer Personal Access Token (PAT)
Sessions: Stateless — каждый запрос независим
Tools (v2): 41 (см. ниже)

2. Создать PAT

В UI Todoha → Настройки → Токены API → Создать.
Полный токен показывается один раз в формате todoha_pat_<строка> — скопируй сразу.
Токен привязан к твоему user_uuid: все tools работают только с твоими задачами.

3. Tools

Tool	Назначение	Ключевые аргументы
`create_task`	Создать задачу	`title`, `parentUuid?`, `todos?`, `_idempotencyKey?`
`list_tasks`	Список с фильтрами	`status?`, `projectId?`, `parentUuid?`, `limit?`
`get_task`	Получить одну	`uuid`
`update_task`	Partial update	`uuid`, любые поля из create
`complete_task`	Идемпотентный шорткат: status=done	`uuid`
`delete_task`	Удалить (cascade на подзадачи)	`uuid`
`add_comment`	Добавить комментарий (атрибутируется именем PAT)	`uuid`, `text`
`list_goals`	Список целей (read-only)	`status?` (active/done)
`get_goal`	Получить одну цель	`uuid`
`get_task_kv`	Прочитать все свойства задачи (kv)	`uuid`
`set_task_kv`	Установить свойство задачи (map-семантика)	`uuid`, `key`, `value`
`delete_task_kv`	Удалить свойство задачи	`uuid`, `key`

Цели (goals) read-only: задача связана с целью через goalUuid. REST-аналоги: GET /goals, GET /goals/{uuid}.

Life tools (scope: life:read / life:write)

Tool	Scope	Назначение
`life_list_contacts`	life:read	Список контактов
`life_get_contact`	life:read	Контакт по uuid
`life_create_contact`	life:write	Создать контакт
`life_update_contact`	life:write	Обновить контакт
`life_delete_contact`	life:write	Soft-delete контакт
`life_list_notes`	life:read	Список заметок
`life_get_note`	life:read	Заметка по uuid
`life_create_note`	life:write	Создать заметку
`life_update_note`	life:write	Обновить заметку
`life_delete_note`	life:write	Soft-delete заметка
`life_list_interactions`	life:read	Список взаимодействий
`life_get_interaction`	life:read	Взаимодействие по uuid
`life_create_interaction`	life:write	Создать взаимодействие
`life_update_interaction`	life:write	Обновить взаимодействие
`life_delete_interaction`	life:write	Soft-delete
`life_list_journal`	life:read	Список дневниковых записей
`life_get_journal`	life:read	Запись дневника по uuid
`life_create_journal`	life:write	Создать запись дневника
`life_update_journal`	life:write	Обновить запись
`life_delete_journal`	life:write	Soft-delete
`life_list_inbox`	life:read	Список inbox-элементов
`life_get_inbox`	life:read	Inbox-элемент по uuid
`life_create_inbox`	life:write	Создать inbox-элемент
`life_update_inbox`	life:write	Обновить inbox-элемент
`life_delete_inbox`	life:write	Soft-delete
`life_sort_inbox`	life:write	Переместить inbox → модуль (транзакционно)
`life_search`	life:read	Кросс-модульный поиск
`life_search_contacts`	life:read	Поиск контактов

Relation tools (scope выводится из прав на объекты-концы)

Связь разрешена, если у PAT есть право на группы обоих концов: task → tasks, Life-объекты (contact/note/interaction/journal/inbox) → life. Явный relations:read/relations:write тоже работает.

Tool	Требуемый доступ	Назначение
`create_relation`	write на обе группы концов (task↔contact → tasks:write + life:write)	Создать связь между двумя объектами
`list_relations`	read на группу объекта (task → tasks:read, Life → life:read)	Список связей объекта (outgoing + incoming)
`delete_relation`	write на обе группы концов связи	Удалить связь по uuid

Actions tools (scope: actions:read / actions:write — явный grant)

Старые PAT без scope НЕ получают actions:* автоматически — нужен явный выбор при создании токена.

Tool	Scope	Назначение
`act_list_actions`	actions:read	Список определений кнопок
`act_get_action`	actions:read	Получить кнопку по id
`act_list_events`	actions:read	Лог активности (фильтр по дате, TZ-aware)
`act_create_action`	actions:write	Создать новую кнопку
`act_update_action`	actions:write	Обновить кнопку (тип нельзя менять)
`act_reorder_actions`	actions:write	Изменить порядок кнопок
`act_complete_action`	actions:write	Отметить кнопку выполненной
`act_uncomplete_action`	actions:write	Снять отметку выполнения
`act_delete_action`	actions:write	Удалить кнопку (cascade на события)
`act_log_event`	actions:write	Записать событие (сервер денорм. имя)
`act_delete_event`	actions:write	Удалить событие из лога

Полные input-schemas → tools/list через JSON-RPC, либо Swagger UI с разделом /mcp.

4. Подключение к клиентам

Claude Desktop

В claude_desktop_config.json:

{
  "mcpServers": {
    "todoha": {
      "type": "http",
      "url": "https://<your-host>/api/public/v1/mcp",
      "headers": {
        "Authorization": "Bearer todoha_pat_<your-token>"
      }
    }
  }
}

Перезапусти Claude Desktop — в чате появится индикатор todoha (6 tools).

Claude Code

В корне проекта файл .mcp.json или команда:

claude mcp add --transport http todoha \
  https://<your-host>/api/public/v1/mcp \
  --header "Authorization: Bearer todoha_pat_<token>"

Cursor / другие MCP-клиенты

Те же три параметра: URL endpoint'а, transport http (Streamable HTTP), header Authorization. Конкретный синтаксис конфига зависит от клиента.

5. Проверка через curl

Список tools (без MCP-клиента):

curl -X POST https://<your-host>/api/public/v1/mcp \
  -H "Authorization: Bearer todoha_pat_<token>" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Создать задачу:

curl -X POST https://<your-host>/api/public/v1/mcp \
  -H "Authorization: Bearer todoha_pat_<token>" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"create_task","arguments":{"title":"Через MCP"}}}'

6. Idempotency и мониторинг

В create_task передавай _idempotencyKey для retry-safe создания — повтор с тем же ключом вернёт оригинальный uuid.

Каждый MCP-вызов пишется в серверный app_log с полями mcp_tool, user_uuid, duration_ms, status — можно строить дашборды без парсинга бодов.

Подробнее — docs/public-api-mcp.md.

7. Безопасность

PAT хранится bcrypt-хешем; полный токен только у тебя.
Не клади PAT в публичные репозитории / shared dotfiles.
Утечка → Настройки → Токены API → Revoke.
Rate-limit на endpoint — тот же, что у REST (Retry-After при 429).