todo-app/mcp
Krzysztof kuhy Rudnicki f3facdd2ee
Some checks are pending
dependency freshness / dependencies on newest stable (push) Waiting to run
file-length / file length <= 250 lines (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
release-apk / release (APK) (push) Waiting to run
One Python, always the newest
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-28 19:41:02 +02:00
..
scripts Add read-only MCP server for the backlog 2026-07-10 21:20:39 +02:00
todo_mcp Latest stable dependencies, and the gate that keeps them there 2026-08-28 14:46:50 +02:00
.gitignore Add read-only MCP server for the backlog 2026-07-10 21:20:39 +02:00
pyproject.toml One Python, always the newest 2026-08-28 19:41:02 +02:00
README.md Add read-only MCP server for the backlog 2026-07-10 21:20:39 +02:00

todo backlog MCP server

A small, standalone, read-only MCP server that lets Claude Code (and its subagents) query the todo app's backlog.

The todo app is Dart/Flutter and stores notes in a sqlite_crdt database that must never be touched from outside the app (CRDT writes corrupt cross-device merge). Instead, this server reads the app's exported BACKLOG.md — the canonical NotesMarkdown snapshot written by Settings → "Export notes".

Staleness note

BACKLOG.md is a manual export, so it can be out of date. Every tool result includes the file's modification time (mtime) so you can judge freshness. If the file is missing, tools return backlog_found: false with a message telling you to export it from the app — they never crash.

Tools (all read-only)

  • list_backlog(priority: str | None = None, status: str | None = None, limit: int = 100) — notes, optionally filtered by priority (low/medium/high) and/or status (todo/inProgress/done/abandoned), plus total, returned, and mtime.
  • get_note(note_id: str) — one note by id, or found: false.
  • backlog_stats() — counts by_status and by_priority, total, and mtime.

Nothing here writes to the database or to BACKLOG.md.

Setup

mcp/scripts/setup_mcp.sh

This creates ~/.venvs/todo-mcp, installs this package (which pulls in the mcp SDK), and verifies the imports. The server is registered via the repo-root .mcp.json; restart Claude Code in this repo and approve the project MCP server prompt. Override the backlog location with TODO_BACKLOG_PATH (defaults to ~/todo/BACKLOG.md).

Development

~/.venvs/todo-mcp/bin/pip install -e mcp pytest pytest-cov ruff mypy
~/.venvs/todo-mcp/bin/python -m pytest mcp/todo_mcp/tests \
    --cov=todo_mcp --cov-branch --cov-report=term-missing --cov-fail-under=100