todo-mcp

MCP-сервер, хранилище которого — файл TODO.md, который можно читать, редактировать вручную и смотреть в диффе. Записи выполняются байтовой склейкой диапазонов: файл остаётся вашим — свёрстанные вручную таблицы, отступы табами и любой текст вне рамок задачи никогда не пере-сериализуются.

Для MCP-клиентов говорит на stdio, для всего остального — на Streamable HTTP.

Благодарность

Основано на CalamityAdam/mcp-todo, который дал исходный каркас: форму фабрики createTodoMcpServer, обёртку Express для Streamable HTTP и обработку сессий.

Почти всё остальное не сохранилось. Та версия хранила задачи как нумерованные записи в JSON-блобе ~/.mcp-todos.json и трёх инструментах над { id, title, done }. Эта версия заменяет хранилище на markdown-документ, меняет числовые ID на слаг-идентификаторы и расширяет набор инструментов до семи: статусы, области, ссылки-хлебные крошки, датированные заметки в логе, полнотекстовый поиск и обнаружение дубликатов. Общей реализации между проектами больше нет.

Апстрим не содержит файла LICENSE; его package.json объявляет лицензию ISC, и именно её ведёт дальше этот репозиторий.

Установка

Запускайте прямо из GitHub, без клонирования:

npx github:adrianhardy/todo-mcp

После внесённого изменения выполняйте npx --ignore-saving github:adrianhardy/todo-mcp, чтобы подтянуть свежие правки.

Для обычной работы достаточно установить один раз и больше не думать:

npm i -g github:adrianhardy/todo-mcp
todo-mcp

Оба пути при установке собирают проект из исходников через скрипт prepare, поэтому dist/ никогда не закоммичивается. Нужен Node 20 или новее.

Использование

todo-mcp по умолчанию запускает HTTP-сервер, потому что именно это удобно, когда человек запускает его в терминале. Задайте MCP_STDIO=1, чтобы вместо этого говорить на stdio — это то, что хочет MCP-клиент, поднимающий сервер в качестве субпроцесса.

С MCP-клиентом

{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["-y", "github:adrianhardy/todo-mcp"],
      "env": { "MCP_STDIO": "1" }
    }
  }
}

При глобальной установке это превращается в "command": "todo-mcp" с тем же блоком env.

Рабочая директория решает, какой файл вы получите. Значение TODO_FILE резолвится относительно cwd процесса и по умолчанию равно TODO.md, поэтому клиент, запущенный в проекте, правит именно его todo-список. Задайте TODO_FILE как абсолютный путь, если нужен один общий список независимо от того, откуда стартует сервер.

По HTTP

PORT=8080 TODO_MCP_TOKEN=$(openssl rand -hex 32) todo-mcp

• POST /mcp — JSON-RPC запросы

• GET /mcp — SSE-поток для уведомлений сервера

• DELETE /mcp — завершение сессии

Если задать TODO_MCP_TOKEN, все три маршрута потребуют заголовок Authorization: Bearer <token>. Если переменная не задана, аутентификация отключена: это подходит исключительно localhost и больше нигде.

Конфигурация

Файл .env читается, если он есть. Смотрите .env.example.

Хранилище

TODO.md — это и есть хранилище, а не JSON-блоб. Файл заодно становится записью: он прочитаем, доступен для ручного редактирования и виден в git-диффе.

Задача — это секция с ## . Полями, за которые отвечает сервер, находится в блоке комментария сразу под заголовком; всё, что ниже, — текст, за который отвечает человек.

## Feature Idea version two: the new widget which tracks things

<!-- todo
id: feature-idea-version-two
area: inventory
status: next
refs: [./src/do_stuff.ts, ClassName.Method, OtherClassName]
created: 2026-08-19
updated: 2026-08-22
-->

**Next step:** close the ledger. ClassName.Method uses 0.25 and it needs 17.2%.

**Already known:** ...

### Log

- 2026-08-22 Slab_Wall_1x3 not started; parade places 24 of those to every 6 of the 3x3.

Идентификаторы — это слёги, а не числа, поэтому они переживают переупорядочивание и удаление. Порядок в файле — это порядок приоритета, поэтому отдельного поля приоритета нет.

Записи — это байтовые склейки: операция изменения перезаписывает только тот диапазон, который ей принадлежит. Свёрстанные вручную таблицы, отступы табами и любой текст вне задачи не пере-сериализуются никогда — их нельзя перетешь или потерять. Обработчики сериализуются с помощью блокировки, потому что два параллельных цикла чтение-модификация-запись склеили бы данные по смещениям, которые уже не соответствуют исходному файлу.

Дизайн

• Список — это сокращение. list_todos возвращает однострочный индекс и никогда не выводит тела задач. get_todo возвращает одну целую секцию. Ожидаемый путь запроса — q или ref; отдавать всё подряд — исключение.

• Захват требует одного поля. Обязателен только title, и новые задачи по умолчанию получают статус captured. Инструмент, который требует от человека указать область и следующий шаг в момент обнаружения, попросту не использовался, — а файл оправдывает себя только в том случае, если записываешь вещи по мере их нахождения. Триаж позже переводит captured в open/next/parked/someday.

Значения статусов

Инструменты

• list_todos — сокращённый индекс; фильтры area, status, ref, q, limit

• get_todo — полный markdown одной задачи, включая её содержимое

• add_todo — добавить задачу; обязателен только title. Сообщает о возможных дубликатах

• update_todo — изменить любое поле; переписывается только переданное

• append_note — добавить датированный пункт в журнал задачи

• set_status — сдвиг задачи по триажу

• remove_todo — удалить задачу и её текст. Лучше вместо этого использовать set_status done

Ресурсы

• todos://list — однострочный индекс открытых задач

Архитектура

• src/todo.ts — markdown-хранилище: разбор, патчинг по байтовому диапазону, запрос, дедуп

• src/server.ts — поверхность MCP-инструментов. Чистая фабрика, без побочных эффектов при импорте

• src/http.ts — Streamable HTTP транспорт, аутентификация и карта сессий

• src/cli.ts — бинарник todo-mcp; выбирает транспорт и запускает его