Schedule MCP · Persönliches Projektplanungs-Tool

Minimalistisches persönliches Projektplanungs-Tool. Ein Python-Dienst übernimmt zwei Rollen gleichzeitig:

1. MCP-Server: Anbindung an XiaoZhi AI über Plattformen wie Verdure MCP Platform / imcp.pro, sodass XiaoZhi deine Planungsdaten per Sprache/Dialog einfach lesen und schreiben kann und regelbasiert Terminerinnerungen ausgibt (die verbleibende natürliche Sprachorganisation übernimmt das DeepSeek-v4-Modell auf der XiaoZhi-Serverseite).

2. REST-API + PC-Frontend: Der PC-Browser greift direkt auf die /app-Seite des bereitgestellten Dienstes zu (oder öffnet lokal web/index.html und zeigt auf die Bereitstellungsadresse) und bietet eine übersichtliche Anzeige und Bearbeitung von Kalender / Gantt-Diagramm (bearbeitbar) / Multi-Projektverwaltung / To-do-Planung (kurzfristig/langfristig).

Die Datenspeicherung verwendet SQLite (null zusätzliche Abhängigkeiten), nach der Bereitstellung sofort einsatzbereit, kein lokaler Backend-Betrieb erforderlich.

Referenzprojekt: shiikun-cn/tarot-mcp (MCP-over-HTTP-Kompatibilitätsmodus ist nachweislich funktionsfähig).

Funktionsübersicht

Related MCP server: Todoist MCP Server

Projektstruktur

schedule-mcp/
├── app.py                     # Flask 主服务：MCP JSON-RPC 兼容层 + REST API + 前端托管
├── db.py                      # SQLite 数据层 + 设置 + 自动任务状态 + 提醒规则引擎 + 备份/恢复
├── requirements.txt           # 仅 Flask + gunicorn（SQLite 用标准库）
├── Dockerfile                 # 容器镜像（gunicorn 生产启动，PORT 环境变量）
├── .gitignore
├── .github/workflows/
│   └── keep-alive.yml         # 服务保活（Render 免费版必须，详见下文说明）
├── web/
│   └── index.html             # PC 端前端（单文件，无外部依赖）
├── smoke-test.mjs             # 端到端冒烟测试（35 项断言）
├── seed-demo.mjs              # 演示数据播种（日期相对今天）
└── data/                      # SQLite 数据库文件（data/schedule.db，不入库）

Datenmodell

Alle Datumsformate: YYYY-MM-DD. Erinnerungen werden nicht in der Datenbank gespeichert, sondern von der Regel-Engine in Echtzeit berechnet.

Hinweis: Die alten Projektstatus paused/completed werden beim Start automatisch zu planned/archived migriert; die Felder progress (Aufgabenfortschritt) und due_date (To-do-Fälligkeitsdatum) wurden auf Produktebene entfernt (Datenbankspalten bleiben für die Kompatibilität mit alten Backups erhalten, werden aber beim Lesen/Schreiben und Anzeigen nicht mehr verwendet).

Regeln für den automatischen Aufgabenstatus (wirksam nach Aktivierung in den Einstellungen)

• Heute vor dem Startdatum → todo (offen)

• Heute zwischen Startdatum und Ende/Fälligkeitsdatum → doing (laufend)

• Heute nach dem Ende/Fälligkeitsdatum → done (abgeschlossen, vermeidet Anhäufung von "überfällig")

• Aufgabe ohne jegliche Datumseigenschaft → Status bleibt unverändert

• Bei Neuanlage/Aktualisierung von Aufgaben sofortige Einordnung (nicht durch die Tages-Idempotenz eingeschränkt); die vollständige Ausführung läuft pro Tag nur einmal (last_auto_date-Idempotenz), die Schaltfläche "Jetzt ausführen" im Einstellungsfeld erzwingt die Ausführung

• Bei jeder Abfrage von Aufgaben/Terminen wird ebenfalls automatisch ausgelöst (falls aktiviert)

MCP-Tool-Liste (16 Stück, für XiaoZhi-AI-Aufrufe)

Die an die KI zurückgegebenen Daten sind kompakt: Die Metadaten aller Tools enthalten nicht color, created_at, updated_at, project_color; Aufgaben enthalten kein progress, To-do-Planungen kein due_date. content[0].text ist chinesischer, gut lesbarer Text, die Metadaten sind strukturierte Daten, beide Felder sind konsistent.

So kommentierst du Tools aus / änderst sie (wichtig)

Die Definitionen aller Tools sind zentral in der TOOLS-Liste in app.py (ca. Zeilen 260-560), ein Tool entspricht einem Objekt in geschweiften Klammern in der Liste, mit den vier Feldern name / description / inputSchema / handler. Die tools/list-Liste wird automatisch aus TOOLS generiert, Auskommentieren versteckt es vor der KI, kein anderer Code muss geändert werden, nach dem Speichern Dienst neu starten.

Beispiel 1: create_project-Tool auskommentieren (XiaoZhi soll keine Projekte erstellen können)

# app.py 中 TOOLS 列表里，把整个对象包进注释：
    # {
    #     "name": "create_project",
    #     "description": "新建一个项目。…",
    #     "inputSchema": {…},
    #     "handler": tool_create_project,
    # },

Beispiel 2: Nur die Tool-Beschreibung ändern (KI anleiten, wann es verwendet wird)

    {
        "name": "get_reminders",
        "description": "获取事务提醒…。建议每天早上询问用户时优先调用。",
        # ↑ 只改 description 字符串即可
        …
    },

Beispiel 3: Nur "Aufgabenerinnerungs"-Tools behalten

Kommentiere in der TOOLS-Liste alle Nicht-Erinnerungs-Tools (wie create_project, list_tasks, create_todo usw.) komplett aus und behalte nur get_reminders, get_schedule, get_schedule_summary. Nach erneuter Erkennung auf der Verdure-Plattform sieht XiaoZhi nur noch die verbleibenden Tools.

Tipp: Nach dem Auskommentieren empfiehlt es sich, die MCP-Server-Konfiguration auf der Verdure-Plattform erneut zu speichern/zu aktualisieren, um die erneute Erkennung auszulösen. Nach jeder Änderung an TOOLS kannst du den Dienst lokal neu starten und mit node smoke-test.mjs prüfen, ob die Tool-Liste wie erwartet geändert wurde (die Assertion enthält fest verdrahtete 16 Stück; wenn du Tools auskommentierst, passe das expected-Array in diesem Skript entsprechend an).

REST-API (PC-Frontend-Direktverbindung, CORS vollständig geöffnet)

Einheitliche Rückgabe {"code":0,"data":…}; Fehler geben {"code":4xx/5xx,"error":"…"} zurück. Optionale Authentifizierung: Nach Setzen der Umgebungsvariable API_KEY müssen alle Anfragen den Header X-API-KEY mitführen (außer /health und /app, damit Keep-alive und Seitenzugriff nicht beeinträchtigt werden).

Lokaler Schnellstart (Verifizierung)

cd schedule-mcp
python -m venv .venv
# Windows: .venv\Scripts\activate     macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
python app.py        # 默认监听 0.0.0.0:8080，可用环境变量 PORT 修改

💡 gunicorn nur unter Linux verfügbar: gunicorn hängt von Unix fcntl ab, unter Windows lokal nicht direkt ausführbar (Bereitstellung auf Render/Docker-Linux-Containern ist nicht betroffen). Für lokale Debugging-Zwecke immer python app.py verwenden (Flask-Entwicklungsserver, funktional identisch), in der Produktion verwendet das Dockerfile gunicorn.

Verifizierung:

# 1) 健康检查
curl http://127.0.0.1:8080/health

# 2) MCP 握手
curl -X POST http://127.0.0.1:8080/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 3) 列出工具（应 16 个）
curl -X POST http://127.0.0.1:8080/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 4) 今日日程（新工具）
curl -X POST http://127.0.0.1:8080/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_schedule","arguments":{"range":"today"}}}'

# 5) 事务提醒
curl -X POST http://127.0.0.1:8080/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_reminders","arguments":{}}}'

# 6) 设置：星期定义 / 自动任务状态
curl http://127.0.0.1:8080/api/settings
curl -X PUT http://127.0.0.1:8080/api/settings -H "Content-Type: application/json" \
  -d '{"week_start":"sun","auto_task_status":"1"}'

Browser öffnen http://127.0.0.1:8080/app für die PC-Panel-Nutzung (Same-Origin-Direktverbindung, keine Konfiguration erforderlich); wenn du web/index.html direkt per Doppelklick öffnest, musst du in den ⚙-Einstellungen die API-Adresse auf http://127.0.0.1:8080 setzen.

Beigefügte Selbsttest-/Demo-Skripte:

node smoke-test.mjs            # 端到端冒烟测试（35 项断言，含自动状态/设置/字段精简）
node seed-demo.mjs             # 播种演示数据（一个项目+4任务+4待办，日期相对今天）

Daten zurücksetzen: data/schedule.db löschen und Dienst neu starten (die Datenbankdatei ist im Repository standardmäßig per gitignore ausgeschlossen).

Bereitstellungsschritte (GitHub → Render → Verdure → XiaoZhi-AI)

Schritt 1: Auf GitHub hochladen

1. Neues Repository auf GitHub erstellen (z. B. schedule-mcp, Private oder Public).

2. Code pushen (nicht data/*.db committen, .gitignore schließt es aus; es wird auch empfohlen, .venv/ nicht zu committen):

cd schedule-mcp
git init
git add .
git commit -m "feat: schedule-mcp 个人排程 MCP 服务"
git branch -M main
git remote add origin https://github.com/<你的用户名>/schedule-mcp.git
git push -u origin main

Schritt 2: Auf Render bereitstellen (kostenlos)

1. render.com öffnen → New → Web Service → dein GitHub-Repository verbinden.

2. Konfiguration:

   • Name: schedule-mcp (beliebig)

   • Environment: Python 3 (oder Docker; bei Docker entfallen die folgenden Build/Start-Angaben)

   • Build Command: pip install -r requirements.txt

   • Start Command: gunicorn -w 2 -b 0.0.0.0:${PORT:-8080} app:app --timeout 30

   • Instance Type: Free

   • (Optional) Environment Variables: API_KEY=dein_zufälliger_Schlüssel (wenn gesetzt, müssen MCP/REST-Anfragen X-API-KEY mitführen)

3. Deploy, auf Build-Abschluss warten. Dienstadresse erhalten: https://schedule-mcp.onrender.com.

4. Verifizieren: Browser öffnen https://schedule-mcp.onrender.com/health sollte {"code":0,"status":"ok",…} zurückgeben.

⚠️ Hinweise zur Render-Free-Version:

• Kostenlose Instanzen schlafen nach ca. 15 Minuten ohne Traffic ein, die nächste Anfrage benötigt einen Kaltstart (erste Antwort langsam, ca. 5-30 Sekunden). → Keep-alive muss aktiviert sein (siehe unten).

• Das Dateisystem der kostenlosen Version ist temporär: Erneutes Bereitstellen/Neustarten löscht die SQLite-Daten. Für den persönlichen Gebrauch wird empfohlen, in den ⚙-Einstellungen regelmäßig "Backup exportieren" durchzuführen oder nach dem Neuaufbau die Daten neu einzugeben (für kurzfristige Alltagsplanung unkritisch).

Schritt 3: Keep-alive aktivieren (für Render-Free-Version erforderlich)

1. .github/workflows/keep-alive.yml bearbeiten, URL auf deine Dienstadresse ändern (z. B. https://schedule-mcp.onrender.com/health).

2. (Optional) Wenn API_KEY gesetzt ist, im GitHub-Repository Settings → Secrets and variables → Actions → New repository secret SERVICE_API_KEY hinzufügen und die entsprechende Zeile im Workflow aktivieren.

3. Änderung pushen. Actions pingt alle 10 Minuten /health, der Dienst bleibt aktiv.

4. Falls der Workflow-Keep-alive ausfällt: cron-job.org verwenden, um GET-Anfragen an die Dienstadresse zu senden. Die Zugriffsfrequenz auf alle 10 bis 14 Minuten einstellen.

Schritt 4: MCP-Server auf der Verdure MCP Platform hinzufügen

1. Bei der Verdure MCP Platform anmelden (falls noch kein Konto, auf dieselbe Weise registrieren wie beim Referenzprojekt; die Plattform verbindet sich mit XiaoZhi / Tuya usw. Assistenten-Endpunkten).

2. Zur Seite "MCP-Server hinzufügen / verwalten" gehen, HTTP-Typ wählen (Verdure erkennt POST / als JSON-RPC, dieser Dienst ist entsprechend implementiert, identisch mit tarot-mcp).

3. Ausfüllen:

   • Dienstadresse (URL): https://schedule-mcp.onrender.com/ (Wurzelpfad genügt, der Dienst verarbeitet MCP-JSON-RPC unter /)

   • Falls Authentifizierung gesetzt ist, den Schlüssel für X-API-KEY eintragen (oder Header gemäß Plattformanforderungen)

4. Nach dem Speichern führt die Plattform automatisch initialize + tools/list-Erkennung durch, die 16 Tools oben sollten sichtbar sein. Wenn die Tool-Liste leer ist, prüfen, ob /health des Dienstes erreichbar ist und ob am Ende der Adresse versehentlich /api usw. angehängt wurde.

5. Den hinzugefügten MCP-Server an deinen XiaoZhi-AI-Assistenten binden (in der Plattform Assistent auswählen → Server verknüpfen).

Schritt 5: XiaoZhi-AI-Sprachverifizierung

Zu XiaoZhi ähnliche Befehle sprechen, um Lesen/Schreiben zu testen:

• "Was steht heute an?" / "Was habe ich heute vor?" → löst get_schedule aus (bevorzugt)

• "Was gibt es zu erinnern?" → löst get_reminders aus

• "Was steht diese Woche an?" / "Was steht diesen Monat an?" → löst get_schedule(range=week/month) aus

• "Notier ein To-do: Flugtickets kaufen, hohe Priorität" → löst create_todo aus

• "Erstell ein Projekt namens Renovierung, November bis Dezember, höchste Priorität" → löst create_project aus

• "Füge dem Renovierungsprojekt eine Aufgabe hinzu: Designkonzept festlegen, fällig am 1. Dezember" → löst create_task aus

• "Welche Projekte habe ich? Wie ist der Fortschritt von Projekt XX?" → löst list_projects / list_tasks / get_gantt_data aus

• "Markiere Aufgabe XX als abgeschlossen" → löst update_task aus

Keep-alive-Erläuterung (Forschungsergebnis)

Fazit: Keep-alive ist keine Anforderung des MCP-Protokolls und auch keine Anforderung der Verdure MCP Platform; es ist nur erforderlich, wenn der Dienst auf einem kostenlosen Hosting mit Schlafmodus bei fehlendem Traffic bereitgestellt wird (z. B. Render Free / Railway-Freikontingent).

Begründung:

1. Die keep-alive.yml im Referenzprojekt tarot-mcp ist ein GitHub-Actions-Zeitplan, der alle 10 Minuten mit curl ein GET auf /health ausführt, wobei die URL auf https://tarot-mcp.onrender.com/health zeigt — dies ist eine Keep-alive-Maßnahme gegen den Schlafmodus der Render-Free-Instanz nach ca. 15 Minuten ohne Traffic.

2. Das MCP-Protokoll selbst (initialize / tools/list / tools/call) hat keine Keep-alive-Anforderungen; die Verdure-Plattform ist eine Verwaltungsebene für "Anbindung + Remote-Injektion", sie ist dafür verantwortlich, die Tools in XiaoZhi zu injizieren, solange dein Dienst online ist, und startet keine schlafenden externen Dienste für dich.

3. Daher:

   • Bereitstellung auf Render Free / Railway-Freikontingent usw. mit Schlafmodus → Keep-alive muss beibehalten werden (sonst ist der Kaltstart bei Tool-Aufrufen durch XiaoZhi langsam oder zeitüberschreitend, schlechte Erfahrung);

   • Bereitstellung auf kostenpflichtigen Dauerinstanzen (Render Starter+, Cloud-Server usw.) oder Verdure-eigenem Hosting (falls von der Plattform unterstützt) → .github/workflows/keep-alive.yml kann gelöscht werden, ohne Nebenwirkungen.

4. Dieses Projekt behält standardmäßig keep-alive.yml bei und passt es an (URL muss auf deine Dienstadresse geändert werden), da die Referenzkette die Render-Free-Version verwendet, was mit deiner Bereitstellungsweise übereinstimmt.

Häufige Fragen

F: Nach der Bereitstellung sagt XiaoZhi "keine verfügbaren Tools"? A: Zuerst prüfen, ob https://<dein-Dienst>/health erreichbar ist; dann auf der Verdure-Plattform die Serverkonfiguration erneut speichern/aktualisieren, um die erneute Erkennung auszulösen. Beachte, dass die Adresse den Wurzelpfad (/) verwenden muss, nicht /api.

F: Wie bringe ich die KI dazu, nur Aufgabenerinnerungen zu machen und weniger Hinzufügen/Löschen-Tools zu haben? A: Siehe oben "So kommentierst du Tools aus / änderst sie" — in der TOOLS-Liste in app.py die nicht benötigten Tools auskommentieren, nach dem Auskommentieren Dienst neu starten und auf Verdure erneut erkennen lassen.

F: Überschreibt der automatische Aufgabenstatus meine manuell gesetzten Abschluss-Status? A: Nach Aktivierung wird der Aufgabenstatus vollständig aus dem Datum abgeleitet (nicht begonnen→offen, laufend→laufend, abgelaufen→abgeschlossen). Wenn du manuell steuern möchtest, schalte den Schalter in den Einstellungen aus; nach dem Ausschalten bleiben nur manuelle Änderungen.

F: Daten nach Neustart der Render-Free-Version verloren? A: Das Dateisystem der kostenlosen Instanz ist temporär. In ⚙ Einstellungen → Backup exportieren regelmäßig JSON speichern; nach dem nächsten Neuaufbau mit "Aus Backup wiederherstellen" importieren (Backup enthält Einstellungen).

F: Wie füge ich API-Authentifizierung hinzu? A: Render-Umgebungsvariable API_KEY=xxx hinzufügen. Danach erfordern MCP (POST /) und REST (/api/*) den X-API-KEY-Header; im Frontend in den ⚙-Einstellungen den Schlüssel eintragen, im Keep-alive-Workflow ein Secret konfigurieren.

F: Kann ich woanders bereitstellen? A: Ja, jedes Hosting, das Python ausführen kann (Railway / Fly.io / Cloud-Server / internes NAS). Die SQLite-Datei liegt in data/, mit persistentem Volume kann Datenverlust vermieden werden.

F: Wie sehe ich, welche Tools XiaoZhi tatsächlich aufgerufen hat? A: In den Render-Logs werden die Parameter und Ergebnisse jedes tools/call ausgegeben; die Tool-Liste kann auch in der GET-Antwort von / eingesehen werden.

Technische Punkte (Kompatibilität mit tarot-mcp beibehalten)

• MCP läuft über JSON-RPC over HTTP (einzelner Endpunkt POST /) und implementiert initialize (protocolVersion 2024-11-05)、notifications/initialized、tools/list、tools/call、ping；für unbekannte Methoden wird ein leeres Ergebnis zurückgegeben. Dies entspricht dem Kompatibilitäts-Patch von tarot-mcp und wurde auf Plattformen wie Verdure / imcp.pro als funktionsfähig verifiziert.

• CORS ist vollständig aktiviert（Access-Control-Allow-Origin: *）, sodass die HTML-Oberfläche auf dem PC das REST-API direkt domänenübergreifend ansprechen kann.

• SQLite nutzt den WAL-Modus sowie eine unabhängige Verbindung pro Anfrage, was zusammen mit den mehreren gunicorn-Workern sicheres Lesen und Schreiben gewährleistet.

• Die Tools geben content[0].text (auf Chinesisch gut verständlich) und metadata (strukturiertes JSON, bereinigt um KI-unrelevante Felder wie color/created_at/updated_at/project_color) zurück, was sowohl das Verständnis der KI als auch die maschinelle Auswertung ermöglicht.

• Die Einstellungen (Status der automatischen Aufgaben / Wochendefinition) werden in der serverseitigen Tabelle settings gespeichert; das Frontend-Panel und die MCP-Abfragen nutzen dieselbe Konfiguration. Die Statistik „diese Woche“ sowie der Frontend-Kalender und der Wochenkalender folgen sämtlich dieser Wochendefinition.