Todo MCP Server

Ein robuster, persistenter Aufgabenverwaltungsserver, der auf dem Model Context Protocol (MCP) mit Python und FastMCP basiert.

Überblick

Der Todo MCP Server bietet Sprachmodellen und KI-Agenten eine persistente, zustandsbehaftete Schnittstelle zur Aufgabenverwaltung. Er wurde mit dem offiziellen Python-MCP-SDK (FastMCP) entwickelt und stellt Tools bereit, die es KI-Assistenten ermöglichen, Aufgaben direkt in ihrem Workflow zu erstellen, zu verfolgen, zu filtern und abzuschließen.

Der Zustand wird lokal in einem strukturierten JSON-Speicher (tasks.json) persistiert, sodass Aufgabendaten Serverneustarts, Client-Wiederverbindungen und mehrschrittige Agentensitzungen überstehen. Die Kommunikation folgt der MCP-Spezifikation über JSON-RPC 2.0 auf Standard-Eingabe/-Ausgabe (stdio).

Related MCP server: Task Manager MCP Server

Architektur & Datenfluss

+-------------------------------------------------------------------+
|                        MCP Host / AI Client                       |
|               (Claude Desktop, Cursor, Antigravity)               |
+-------------------------------------------------------------------+
                                  |
                   JSON-RPC 2.0 over stdin / stdout
                                  v
+-------------------------------------------------------------------+
|                       Todo MCP Server                             |
|                                                                   |
|   +-----------------------------------------------------------+   |
|   |                       FastMCP Engine                      |   |
|   |  - Protocol negotiation & schema reflection               |   |
|   |  - Tool dispatch & argument validation (Pydantic/Typing)  |   |
|   +-----------------------------------------------------------+   |
|                                 |                                 |
|   +-----------------------------+-----------------------------+   |
|   |                             |                             |   |
|   v                             v                             v   |
| [ add_task ]             [ list_tasks ]             [ complete_task ]
|   |                             |                             |   |
|   +-----------------------------+-----------------------------+   |
|                                 |                                 |
|                                 v                                 |
|   +-----------------------------------------------------------+   |
|   |                    Storage Controller                     |   |
|   |  - Atomic read/write operations                           |   |
|   |  - Schema serialization with ISO 8601 UTC timestamps      |   |
|   +-----------------------------------------------------------+   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                      Local Storage: tasks.json                    |
+-------------------------------------------------------------------+

Tool-Referenz

Der Server stellt drei verschiedene Tools für die vollständige Verwaltung des Aufgabenlebenszyklus bereit.

1. add_task

Erstellt einen neuen Aufgabeneintrag und fügt ihn dem persistenten Speicher hinzu.

• Beschreibung: Fügt der Aufgabenliste eine neue Aufgabe hinzu.

• Parameter:

  • title (string, erforderlich): Beschreibung der Aufgabe. Die Länge muss zwischen 1 und 200 Zeichen liegen.

  • priority (string, optional): Dringlichkeitsstufe. Akzeptierte Werte: "low", "medium", "high". Standard: "medium".

• Validierungsregeln:

  • Leere oder nur aus Leerzeichen bestehende Zeichenfolgen werden abgelehnt.

  • Titel mit mehr als 200 Zeichen geben einen Fehler zurück.

  • Nicht konforme Prioritätswerte bestehen die Schema-Validierung nicht.

Beispielanfrage:

{
  "title": "Implement integration test suite",
  "priority": "high"
}

Beispielantwort:

Task added!
  ID:       1
  Title:    Implement integration test suite
  Priority: high
  Status:   pending

2. list_tasks

Ruft gespeicherte Aufgaben mit optionaler Filterung nach Abschlussstatus ab.

• Beschreibung: Listet Aufgaben aus der Aufgabenliste mit optionaler Statusfilterung auf.

• Parameter:

  • status (string, optional): Filterkriterium. Akzeptierte Werte: "all", "pending", "done". Standard: "all".

• Formatierung: Gibt eine formatierte ASCII-Tabelle zurück, die Aufgaben-IDs, Statusindikatoren, Prioritätsstufen und Titel zusammenfasst.

Beispielanfrage:

{
  "status": "pending"
}

Beispielantwort:

Tasks (pending) — 2 found:

  ID  Status    Priority Title
————  ————————— ———————— ————————————————————————————————————————
   1  pending   high     Implement integration test suite
   2  pending   medium   Update project documentation

3. complete_task

Markiert eine vorhandene Aufgabe anhand ihrer eindeutigen numerischen Kennung als abgeschlossen.

• Beschreibung: Markiert eine Aufgabe anhand ihrer numerischen ID als erledigt.

• Parameter:

  • task_id (integer, erforderlich): Die eindeutige numerische Kennung, die der Aufgabe zugewiesen wurde.

• Verhalten:

  • Aktualisiert den Aufgabenstatus auf "done".

  • Setzt das Feld completed_at auf den aktuellen ISO-8601-UTC-Zeitstempel.

  • Idempotent: Wenn die Aufgabe bereits abgeschlossen ist, benachrichtigt das Tool den Client, ohne Zeitstempel zu beschädigen.

  • Wenn die ID nicht existiert, wird eine Fehlerantwort mit der Liste der aktuell gültigen IDs zurückgegeben.

Beispielanfrage:

{
  "task_id": 1
}

Beispielantwort:

Task 1 completed!
  Title:        Implement integration test suite
  Completed at: 2026-08-20T09:46:17.466797+00:00

Tool-Übersichtstabelle

Datenmodell & Persistenz

Aufgabendatensätze werden als UTF-8-kodierte JSON-Arrays serialisiert. Standardmäßig werden die Datensätze in tasks.json im aktuellen Arbeitsverzeichnis gespeichert. Der Speicherdateipfad kann über die Umgebungsvariable TODO_FILE angepasst werden.

Schemadefinition

[
  {
    "id": 1,
    "title": "Implement integration test suite",
    "priority": "high",
    "status": "done",
    "created_at": "2026-08-20T09:46:17.362387+00:00",
    "completed_at": "2026-08-20T09:46:17.466797+00:00"
  },
  {
    "id": 2,
    "title": "Update project documentation",
    "priority": "medium",
    "status": "pending",
    "created_at": "2026-08-20T09:46:17.384689+00:00",
    "completed_at": null
  }
]

Feldspezifikationen

• id (integer): Automatisch inkrementierende positive Ganzzahl-Kennung.

• title (string): Aufgabenbeschreibung (1–200 Zeichen).

• priority (string): Dringlichkeitsklassifizierung ("low", "medium", "high").

• status (string): Lebenszyklusphase ("pending" oder "done").

• created_at (string): ISO-8601-formatierter UTC-Zeitstempel, der bei der Erstellung aufgezeichnet wird.

• completed_at (string | null): ISO-8601-formatierter UTC-Zeitstempel, der beim Abschluss aufgezeichnet wird.

Anforderungen

• Python: Version 3.10 oder höher

• Abhängigkeiten:

  • mcp[cli]>=1.28,<2

Installation & Einrichtung

1. Repository klonen

git clone https://github.com/moazhassan751/mcp-todo-server.git
cd mcp-todo-server

2. Virtuelle Umgebung erstellen

# Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate

3. Abhängigkeiten installieren

pip install -r requirements.txt

Ausführungsmodi

Standardausführung (stdio)

Führen Sie den Server direkt für die Produktion oder die MCP-Host-Integration aus:

python server.py

Entwickler-Inspektion (MCP Inspector)

Der MCP Inspector bietet eine interaktive, browserbasierte Oberfläche zum Testen von Tools, Inspizieren von Schemas und Simulieren von Anfragen:

mcp dev server.py

Der Inspector wird gestartet und stellt eine lokale Oberflächen-URL bereit (in der Regel http://localhost:6274).

Client-Integrationsanleitung

Um den Todo MCP Server mit Ihrer bevorzugten KI-Umgebung zu verbinden, konfigurieren Sie den Server in der MCP-Konfigurationsdatei Ihres Clients.

Claude Desktop

Bearbeiten Sie Ihre Claude-Desktop-Konfigurationsdatei:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

Cursor

Fügen Sie Folgendes zu .cursor/mcp.json in Ihrem Projekt- oder globalen Verzeichnis hinzu:

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

Antigravity IDE

Fügen Sie Folgendes zu .agents/mcp_config.json in Ihrem Arbeitsbereich hinzu:

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

Testen & Verifizierung

Das Repository enthält umfassende automatisierte Testskripte:

Standard-Testsuite

Testet grundlegende Tool-Aufrufe, Parametervalidierungen und Ausgabeformatierung:

python test_server.py

Multi-Sitzungs-Audit-Test

Simuliert separate Client-Verbindungen, startet den Serverprozess über Sitzungen hinweg neu und validiert, dass der persistente Speicher den Zustand korrekt beibehält:

python audit_test.py

Projektstruktur

mcp-todo-server/
├── server.py           # Core MCP server definition and tool implementations
├── test_server.py      # Automated stdio protocol unit tests
├── audit_test.py       # Multi-session persistence and edge-case verification
├── requirements.txt    # Package dependencies
├── .gitignore          # Version control ignore definitions
└── README.md           # Technical documentation and integration reference

Lizenz

Dieses Projekt ist Open Source und unter der MIT-Lizenz verfügbar.