🚀 DoneTick MCP Server (Model Context Protocol SSE)

Ein vollständiger, produktionsreifer Model Context Protocol (MCP)-Server, der HTTP Server-Sent Events (SSE) für DoneTick (selbst gehostetes Aufgaben- und Haushaltsmanagement) implementiert.

Kompatibel mit Mistral Le Chat, Claude Desktop, LibreChat, n8n, Open WebUI und jedem MCP-Client.

📋 Funktionen

Der Server stellt 57 spezialisierte MCP-Tools bereit, die die DoneTick-API abdecken, einschließlich Abschlussverlauf und Zeiterfassung. Jeder Endpunkt wird von npm run smoke gegen eine Live-Instanz verifiziert.

1. 📝 Aufgaben & Haushalt (donetick_*)

• donetick_list_chores: Aufgaben mit Filtern auflisten (Suche, Projekt, Status).

• donetick_get_chore: Vollständige Aufgabendetails – Wiederholung, Zugewiesene, Unteraufgaben, Labels, Trigger – plus lastCompletedDate, lastCompletedBy und timeSpentSeconds.

• donetick_create_chore: Aufgabe erstellen mit Fälligkeitsdatum, Wiederholung, Priorität, Punkten, Projekt, Unteraufgaben, Labels, Benachrichtigungen, Genehmigung und Sensor-Triggern.

• donetick_update_chore: Teilweise oder vollständige Aktualisierungen. Bricht ab, anstatt blind zu schreiben, wenn die Aufgabe nicht zuerst gelesen werden kann.

• donetick_complete_chore: Aufgabe abschließen und ihre nächste Wiederholung planen.

• donetick_undo_chore: Den letzten Abschluss rückgängig machen.

• donetick_delete_chore: Aufgabe dauerhaft löschen (Archivierung bevorzugen).

• donetick_set_due_date: Fälligkeitsdatum setzen, ändern oder löschen.

• donetick_set_priority: Priorität setzen – 1 ist die höchste (P1), 4 die niedrigste, 0 keine.

• donetick_skip_chore: Die aktuelle Wiederholung überspringen.

• donetick_nudge_chore: Eine Erinnerung an den Zugewiesenen senden.

• donetick_set_chore_notifications: Erinnerungen konfigurieren (Fälligkeitsdatum, Vorab, Nörgeln, Abschluss).

• donetick_set_chore_project, donetick_set_chore_assignee: Aufgabe neu zuweisen.

2. 📊 Abschlussverlauf (donetick_*)

• donetick_get_chore_history: Jeder Abschluss, jedes Überspringen, jede Neuplanung und jeder Fehlversuch für eine Aufgabe, mit einem lesbaren statusName und einer Zusammenfassung. Dies ist der einzige zuverlässige Weg, „erledigt" von „bearbeitet" zu unterscheiden – updatedAt vermischt beides.

• donetick_get_history: Kreisweite Aktivität, filterbar nach Datumsbereich und Status.

• donetick_modify_history_entry: Korrigieren, wann ein Abschluss protokolliert wurde, oder dessen Notizen.

• donetick_delete_history_entry: Einen fehlerhaften Eintrag entfernen.

3. ⏱️ Zeiterfassung (donetick_*)

• donetick_start_chore / donetick_pause_chore: Den aufgabenspezifischen Timer starten bzw. pausieren.

• donetick_get_chore_timer: Gesamte aufgewendete Zeit plus jede Arbeitssitzung.

• donetick_reset_chore_timer: Die angesammelte Zeit zurücksetzen.

• donetick_adjust_time_session / donetick_delete_time_session: Verlauf im Nachhinein korrigieren.

4. 🧩 Unteraufgaben (donetick_*)

• donetick_set_subtasks: Die gesamte Liste ersetzen. Destruktiv, behält aber IDs und Abschlussstatus bei, indem nach Namen abgeglichen wird.

• donetick_add_subtask: Eine Unteraufgabe anhängen, die anderen bleiben unverändert.

• donetick_complete_subtask / donetick_uncomplete_subtask: Eine Unteraufgabe abhaken, per ID oder per Name.

• donetick_remove_subtask: Eine Unteraufgabe löschen, ohne die Liste neu zu schreiben.

Hinweis: Das Abschließen einer wiederkehrenden Aufgabe löscht deren Unteraufgaben, anstatt sie abzuhaken. Das ist DoneTicks eigenes Verhalten und bereitet das nächste Vorkommen vor.

5. 🗄️ Archivierung & Genehmigung (donetick_*)

• donetick_list_archived_chores, donetick_archive_chore, donetick_unarchive_chore: Reversible Alternative zum Löschen.

• donetick_approve_chore, donetick_reject_chore: Abschlüsse bei Aufgaben mit requireApproval prüfen.

6. 🏷️ Labels & Tags (donetick_*)

• donetick_list_labels: Labels auflisten, mit Fallback auf Extraktion aus Aufgaben.

• donetick_create_label, donetick_update_label, donetick_delete_label: Siehe die Einschränkung unten – diese erfordern ein JWT.

• donetick_set_chore_labels, donetick_add_chore_label: Labels an einer Aufgabe anbringen.

7. ⚡ Smart Things & Ereignis-Trigger (donetick_*)

• donetick_list_things, donetick_create_thing, donetick_update_thing, donetick_delete_thing.

• donetick_set_thing_state: Einen Sensor oder Zähler aktualisieren und dabei automatisch verknüpfte Aufgaben auslösen.

• donetick_get_thing_history: Jeder Zustand, den ein Thing hatte, und wann.

• donetick_link_thing_chore / donetick_unlink_thing_chore: Trigger-Bedingungen (eq, neq, gt, lt, gte, lte).

8. 📁 Projekte (donetick_*)

• donetick_list_projects, donetick_create_project, donetick_update_project, donetick_delete_project.

9. 👥 Kreise, Mitglieder & Filter (donetick_*)

• donetick_get_circle_info, donetick_list_members, donetick_list_filters.

Related MCP server: Deferno MCP Server

📅 Daten und Prioritäten

Daten. DoneTick bindet jedes Datum an eine Go-time.Time, akzeptiert also nur RFC3339. Der Connector akzeptiert zusätzlich YYYY-MM-DD und YYYY-MM-DD HH:mm und löst sie in DONETICK_TIMEZONE (Standard UTC) um DONETICK_DEFAULT_DUE_TIME (Standard 18:00) auf. Setzen Sie beide, wenn „morgen fällig" eine sinnvolle lokale Stunde bedeuten soll und nicht Mitternacht UTC.

Prioritäten. DoneTick zählt abwärts: 1 ist die höchste Priorität, in der Web-UI als rotes P1 angezeigt, und 4 ist die niedrigste; 0 bedeutet keine Priorität. Versionen vor 2.0.0 dokumentierten dies umgekehrt, sodass Aufgaben, die über die alten Beschreibungen geschrieben wurden, invertierte Werte tragen können.

⚠️ Bekannte Einschränkungen

• Labels können mit einem API-Schlüssel nicht erstellt oder bearbeitet werden. DoneTick hängt /api/v1/labels hinter eine reine JWT-Middleware, anders als jede andere Route. Das Lesen fällt auf die Extraktion von Labels aus Aufgaben zurück; verwalten Sie sie in der Web-UI.

• Es kann keine beliebige Dauer protokolliert werden. POST /chores/{id}/do akzeptiert keinen Wert für aufgewendete Zeit, und der Handler für manuelle Dauer von DoneTick ist zwar definiert, wird aber nie geroutet. Verwenden Sie Start/Pause oder passen Sie die Grenzen einer Sitzung danach an.

• Verlaufsfenster sind in Tagen. DoneTicks limit ist eine Anzahl von Tagen, nicht von Zeilen; since/until werden nach dem Abruf clientseitig angewendet.

🔒 Sicherheit & OWASP-Härtung

• OWASP A01 & A07 (Zugriffskontrolle & Timing-Angriffe): Authentifizierungs-Token-Prüfung in konstanter Zeit (crypto.timingSafeEqual).

• OWASP A02 (Kryptografische Fehler & Informationsleck): Geheimnis-Schwärzung in Logs und sichere /health-Telemetrie ohne Anmeldedaten.

• OWASP A03 (Injection & SSRF): Strikte Protokoll-Sanitisierung (http:, https:) verhindert Protokoll-Injection oder SSRF (file://, gopher://).

• OWASP A04 (Denial of Service): Strikte JSON-Body-Lastgrenzen (1mb) und aktive SSE-Sitzungslimits mit Verbindungsbereinigung.

• OWASP A05 (Fehlkonfiguration der Sicherheit): Gehärtete HTTP-Header (X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 0, Referrer-Policy: no-referrer, X-Powered-By deaktiviert). Docker-Ausführung ohne Root (USER node).

🐳 Schnellstart mit Docker

1. Eine docker-compose.yml erstellen

services:
  mcp-donetick:
    image: ghcr.io/bibiwan/mcp_donetick:latest
    container_name: mcp-donetick
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - HOST=0.0.0.0
      - DONETICK_URL=http://donetick:2021
      - DONETICK_TOKEN=
      # Resolves date-only inputs such as "2026-08-30" to a local hour
      - DONETICK_TIMEZONE=Europe/Paris
      - DONETICK_DEFAULT_DUE_TIME=18:00
      - MCP_AUTH_TOKEN=
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

2. Den Container starten

docker compose up -d

🤖 Mit Mistral Le Chat verbinden

1. Gehen Sie in Mistral Le Chat zu Einstellungen ➔ Tools & MCP (oder Connectors).

2. Klicken Sie auf „MCP-Server hinzufügen".

3. Füllen Sie die Verbindungseinstellungen aus:

   • Name: DoneTick

   • URL: https://<your-server-host>:3000/sse

   • Authentifizierung: Bearer Token

   • Token: <Ihr DoneTick-API-Token> (generiert in DoneTick ➔ Einstellungen ➔ API-Token)

4. Speichern und mit dem Chatten beginnen!

Beispiel-Prompts:

• „Welche Aufgaben sind überfällig oder heute fällig?"

• „Erstelle eine Aufgabe ‚Espressomaschine reinigen' für nächsten Sonntag mit hoher Priorität und Unteraufgaben: ‚Brühgruppe rückspülen', ‚Boiler entkalken'."

• „Verknüpfe Aufgabe #21 mit meinem Kaffeezähler (Thing #11), um auszulösen, wann immer der Zähler >= 100 ist."

• „Markiere Aufgabe #5 als abgeschlossen mit 20 Punkten."

🧪 Entwicklung & Tests

# Install dependencies
npm install

# Run the test suite with coverage.
# Enforces an 80% floor on statements, branches, functions and lines.
npm test

# Build TypeScript
npm run build

# Start local server
npm start

Live-Smoke-Test

Die Unit-Testsuite mockt axios und beweist damit, dass die Payloads wie beabsichtigt geformt sind – nicht, dass DoneTick sie akzeptiert. Vor dem Taggen eines Releases den Smoke-Test gegen eine echte Instanz ausführen:

DONETICK_URL=https://donetick.example DONETICK_TOKEN=xxx npm run smoke

Er erstellt nur Objekte mit dem Präfix [mcp-test], übt jeden Endpunkt aus, den der Connector verwendet, löscht das Erstellte und weigert sich, etwas ohne dieses Präfix zu löschen. Bestehende Aufgaben werden nie verändert.

📄 Lizenz

MIT-Lizenz. Zur freien Verwendung, Modifikation und Verbreitung.