todo-mcp

Ein MCP-Server, dessen Speicher eine TODO.md ist, die du von Hand lesen, bearbeiten und diffen kannst. Schreibvorgänge sind Byte-Range-Splices, damit bleibt die Datei deine: handgeschriebene Tabellen, Tab-Einrückungen und jede Prosa außerhalb einer Aufgabe werden nie neu serialisiert.

Für MCP-Clients spricht er stdio, für alles andere Streamable HTTP.

Danksagung

Basiert auf CalamityAdam/mcp-todo, das das ursprüngliche Grundgerüst lieferte: die Factory-Form von createTodoMcpServer, den Express-Streamable-HTTP-Wrapper und das Session-Handling.

Fast nichts davon hat überlebt. Jene Version verwaltete Todos als nummerierte Datensätze in einem JSON-Blob unter ~/.mcp-todos.json, mit drei Tools über { id, title, done }. Diese Version ersetzt den Speicher durch ein Markdown-Dokument, tauscht numerische IDs gegen Slugs und erweitert die Tool-Oberfläche auf sieben Tools – mit Status, Bereichen, Referenz-Breadcrumbs, datierten Log-Notizen, Volltextsuche und Duplikaterkennung. Die beiden Projekte teilen sich keine Implementierung mehr.

Upstream liefert keine LICENSE-Datei mit; sein package.json deklariert ISC, und genau das trägt dieses Repository weiter.

Installation

Direkt von GitHub ausführen, ganz ohne Klonen:

npx github:adrianhardy/todo-mcp

Nach dem Pushen von Änderungen die neue Version mit npx --ignore-existing github:adrianhardy/todo-mcp übernehmen.

Für den regulären Gebrauch einmal installieren und dann nicht mehr daran denken:

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

Beide Wege bauen bei der Installation über das prepare-Skript aus dem Quellcode, daher wird dist/ nie committet. Node 20 oder neuer.

Verwendung

todo-mcp startet standardmäßig den HTTP-Server, weil das das Nützliche ist, wenn es jemand in einem Terminal ausführt. Setze MCP_STDIO=1, um stattdessen stdio zu sprechen – das will ein MCP-Client, der es als Unterprozess startet.

Mit einem MCP-Client

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

Bei globaler Installation wird daraus "command": "todo-mcp" mit demselben env-Block.

Das Arbeitsverzeichnis entscheidet, welche Datei du bekommst. TODO_FILE wird relativ zum CWD des Prozesses aufgelöst und ist standardmäßig TODO.md; ein in einem Projekt gestarteter Client bearbeitet also die Todo-Liste genau dieses Projekts. Setze TODO_FILE auf einen absoluten Pfad, wenn du eine gemeinsame Liste haben willst, egal wo der Server startet.

Über HTTP

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

• POST /mcp – JSON-RPC-Anfragen

• GET /mcp – SSE-Stream für Server-Benachrichtigungen

• DELETE /mcp – Session beenden

Wenn TODO_MCP_TOKEN gesetzt ist, verlangen alle drei einen Authorization: Bearer <token>. Ist es nicht gesetzt, ist die Authentifizierung deaktiviert – das ist auf localhost in Ordnung, und sonst nirgendwo.

Konfiguration

Eine .env-Datei wird gelesen, falls vorhanden. Siehe .env.example.

Speicher

TODO.md ist der Speicher, kein JSON-Blob. Die Datei ist das Protokoll: lesbar, von Hand bearbeitbar und in git diff-fähig.

Eine Aufgabe ist ein ## -Abschnitt. Felder, die dem Server gehören, leben in einem Kommentarblock direkt unter der Überschrift; alles darunter ist Prosa, die dem Menschen gehört.

## 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.

IDs sind Slugs, keine Nummern, und überleben daher Umsortieren und Löschen. Die Dateireihenfolge ist die Prioritätsreihenfolge; deshalb gibt es kein Prioritätsfeld.

Schreibvorgänge sind Byte-Range-Splices: Eine Mutation überschreibt nur die Spanne, die ihr gehört. Handgeschriebene Tabellen, Tab-Einrückungen und jede Prosa außerhalb eines Aufgabenabschnitts werden nie neu serialisiert, können also nicht umgebrochen oder verloren werden. Die Handler werden über eine Sperre serialisiert, denn zwei verschränkte Read-Modify-Write-Zyklen würden an Offsets spliften, die die Datei nicht mehr beschreiben.

Design

• Liste ist kompakt – list_todos gibt einen einzeiligen Index zurück und niemals Aufgabentexte. get_todo gibt einen ganzen Abschnitt zurück. Der erwartete Pfad ist q oder ref; alles aufzulisten ist die Ausnahme.

• Erfassen braucht genau ein Feld. Nur title ist erforderlich, und neue Aufgaben bekommen standardmäßig den Status captured. Ein Werkzeug, das im Moment des Entdeckens einen Bereich und einen nächsten Schritt erfordert, wird schlicht nicht benutzt – und die Datei zahlt sich erst aus, wenn Dinge festgehalten werden, sobald sie gefunden werden. Die Triage verschiebt captured später zu open/next/parked/someday.

Statuswerte

Tools

• list_todos – kompakter Index; filtert area, status, ref, q, limit

• get_todo – vollständiges Markdown einer Aufgabe, inklusive Freitext

• add_todo – Aufgabe erfassen; nur title ist nötig. Meldet mögliche Duplikate

• update_todo – beliebige Felder ändern; nur das Übergebene wird überschrieben

• append_note – einen datierten Bullet zur Aufgabenchronik hinzufügen

• set_status – eine Aufgabe durch die Triage bewegen

• remove_todo – Aufgabe samt Freitext löschen. set_status done ist vorzuziehen

Ressourcen

• todos://list – einzeiliger Index der offenen Aufgaben

Architektur

• src/todo.ts – der Markdown-Speicher: Parsing, Byte-Range-Patching, Query, Dedup

• src/server.ts – die MCP-Tool-Oberfläche. Reine Factory, keine Seiteneffekte beim Import

• src/http.ts – Streamable-HTTP-Transport, Authentifizierung und Session-Map

• src/cli.ts – die todo-mcp-Binärdatei; wählt einen Transport aus und startet ihn