habitica-mcp

Ein MCP-Server für eine selbst gehostete Habitica-Instanz, bereitgestellt über Streamable HTTP, sodass er als normaler Netzwerkdienst läuft anstatt als stdio-Subprozess pro Client.

Warum es das gibt

Der bestehende Community-Server (iBreaker/habitica-mcp-server) hartkodiert https://habitica.com/api/v3, unterstützt nur stdio und wurde seit drei Tagen nach seiner Erstellung nicht mehr gepflegt. Nichts davon funktioniert für eine selbst gehostete Instanz hinter einem Ingress.

Hier ist HABITICA_BASE_URL erforderlich, ohne Standardwert — eine falsche Instanz ist unmöglich statt nur unattraktiv.

Related MCP server: habitca-mcp

Tools

Konfiguration

Endpunkte: POST/GET/DELETE /mcp und GET /healthz.

Designentscheidungen

Vier Entscheidungen, die tragend und nicht offensichtlich sind:

Antwortprojektion statt Paginierung. Habiticas GET /tasks/user liefert history: [{date, value}] bei jeder Gewohnheit und täglichen Aufgabe — ein Eintrag pro Bewertungsereignis über die gesamte Lebensdauer des Kontos, und das ist standardmäßig aktiviert. Die API bietet kein Limit/Offset, daher ist die Lösung Projektion: Dieser Server sendet immer history=false und projiziert zusätzlich jede Aufgabe auf ein festes Feldschema, sodass eine Schemaänderung seitens der API nicht stillschweigend Hunderte KB in den Modellkontext einbringen kann. get_user_stats verwendet ?userFields= aus demselben Grund.

Der Listenfilter ist plural und unregelmäßig. GET /tasks/user?type= akzeptiert habits | dailys | todos | rewards | completedTodos (beachte dailys), während der Anfragekörper den Singular habit | daily | todo | reward verwendet. Die Tools verwenden die Singularform und mappen intern; die Übergabe der Singularform an den Listenendpunkt führt zu 400.

Die Host-Validierung ist auf /mcp beschränkt, nicht app-weit. createMcpExpressApp wendet sie global an, was sowohl Kubelet-Probes (ein httpGet-Probe sendet Host: <podIP>, und Pod-IPs können nie in einer Allowlist stehen) als auch Blackbox-Monitoring (das Host: <svc>.<ns>.svc sendet) brechen würde. /healthz liegt daher außerhalb der Absicherung; es legt nichts offen, und der DNS-Rebinding-Schutz ist nur für die JSON-RPC-Oberfläche relevant.

/healthz meldet nur Prozess-Lebendigkeit — niemals Habitica-Erreichbarkeit. Ein Konnektivitätscheck würde einen Habitica-Neustart in einen CrashLoopBackOff verwandeln, und die Liveness-Probe würde dann einen Prozess wiederholt beenden, der vollkommen gesund ist und einfach nichts zu sagen hat. Habitica-Ausfälle erscheinen stattdessen als saubere, tool-spezifische JSON-RPC-Fehler.

Transport

Zustandsloses Streamable HTTP (sessionIdGenerator: undefined), aufgebaut auf @modelcontextprotocol/server v2 — dem aktuellen Hauptversionszweig, dessen HTTP-Transport in den separaten Adaptern @modelcontextprotocol/express / @modelcontextprotocol/node lebt. Die ausgehandelte Protokollversion ist 2025-11-25 (LATEST_PROTOCOL_VERSION im SDK); v1.x ist jetzt nur noch Sicherheits- und Fehlerbehebungsmodus.

Ein frischer McpServer + Transport wird pro Anfrage erstellt und beim close-Ereignis der Antwort abgebaut. Die Konstruktion pro Anfrage ist notwendig, nicht nur ordentlich: SDK v1 wirft bei zustandslosem Transport eine Ausnahme („Stateless transport cannot be reused across requests"), weil Wiederverwendung Nachrichten-ID-Kollisionen zwischen gleichzeitigen Clients verursachen würde.

Die Kosten sind real und wissenswert: Jede Anfrage erstellt 11 zod→JSON-Schema-Konvertierungen neu, die etwa 0,5 MB Müll pro Aufruf erzeugen. Dieser wird unter GC-Druck wiederverwertet (1500 sequenzielle Aufrufe stabilisierten sich bei ~193 MiB mit einem 96-MB-Heap-Limit), anstatt zu leaken, aber genau deshalb benötigt der Dienst mehr Speicher, als der Leerlauf-Fußabdruck vermuten lässt.

GET /mcp antwortet mit 405 und Allow: POST. Das ist spezifikationskonform (ein Server darf den eigenständigen Stream verweigern) und genau das, was der MCP-Client erwartet — er behandelt 405 als „kein Server-Stream hier" und bricht ab.

Eine frühere Version versuchte es kulanter und antwortete mit einem leeren SSE-Stream. Das verursachte eine Endlosschleife von Wiederverbindungen: Der Client behandelt einen sauber beendeten Stream ohne Antwort als abgerissene Verbindung und plant neu, aber sein Wiederholungszähler erhöht sich nur bei Fehlern — ein erfolgreicher leerer Stream setzte also nichts zurück. Gemessen bei ~1 Anfrage/s: 1 → 4 → 8 → 12 GETs über 12 Sekunden Leerlauf, also grob 86.000 Anfragen pro Tag pro verbundenem Client, ohne dass irgendwo ein Fehler auftauchte. Mit 405 bleibt es bei genau 1.

Zustandslosigkeit hat einen echten Preis, nicht nur Vorteile: Server→Client-Roundtrips (Sampling, Elicitation) und unaufgeforderte *ListChanged-Benachrichtigungen können nicht funktionieren, weil die Antwort des Clients als neue HTTP-Anfrage eintrifft, die auf einer frischen Serverinstanz ohne Erinnerung an den ausstehenden Aufruf landet. Fortschrittsbenachrichtigungen funktionieren jedoch — sie reiten auf dem eigenen Stream der ursprünglichen Anfrage. Das spielt für eine CRUD-Tool-Oberfläche keine Rolle, aber bauen Sie darauf keine dieser Fähigkeiten auf.

Sicherheit

Der /mcp-Endpunkt ist nicht authentifiziert. Die Habitica-Anmeldedaten liegen serverseitig, sodass jeder, der den Endpunkt erreichen kann, die gesamte Aufgabenliste des Kontos lesen und schreiben kann. Das ist beabsichtigt — ein Auth-Proxy vor einem MCP-Endpunkt würde MCP-Clients brechen — und der Grund, warum der Dienst auf ein privates Netzwerk und eine einzelne Replik beschränkt ist.

Das API-Token ist eine benutzerstufige Habitica-Anmeldedaten (von Habitica selbst im Klartext gespeichert), sodass ein Leck einen vollständigen Kontokompromiss bedeutet. Die gesamte Protokollausgabe läuft durch einen schwärzenden Logger, mit einem Test, der sicherstellt, dass das Token in keiner ausgegebenen Zeile erscheint.

Entwicklung

npm ci
npm test
npm run lint && npm run typecheck
npm run build && node dist/index.js

Lizenz

MIT