Conatus MCP Server

Ein unabhängig installierbarer Model Context Protocol-Server für den selbst gehosteten Conatus-Aufgabenmanager.

Er stellt agentensichere Werkzeuge für Projekte, Abschnitte, Aufgaben, Labels, Kommentare und Erinnerungen bereit. Er unterstützt lokale stdio-Clients und entfernte Streamable-HTTP-Clients. Das dauerhafte Löschen ist absichtlich nicht verfügbar.

Anforderungen

• Node.js 20 oder neuer

• Eine erreichbare Conatus-Installation mit der /api/v1-API

• Ein eingeschränkter API-Token, erstellt unter Einstellungen → API-Tokens

Related MCP server: Google Tasks MCP Server

Lokale stdio-Einrichtung

Der lokale Modus ist die empfohlene Standardeinstellung. Der KI-Host startet einen MCP-Prozess für das konfigurierte Aufgabenmanager-Konto.

Ein-Befehl-Einrichtung

Führen Sie den interaktiven Installer aus, um Ihre Conatus-URL und den eingeschränkten API-Token zu validieren, und registrieren Sie den Server dann bei Claude Desktop, Claude Code, Cursor oder einer anderen JSON-MCP-Konfigurationsdatei:

npx -y conatus-mcp setup

Der Installer gibt den Token niemals aus, überprüft ihn, bevor er eine Konfigurationsdatei ändert, und schränkt die geschriebene Konfigurationsdatei auf Berechtigungen nur für den Besitzer ein, wo das Betriebssystem dies unterstützt. Starten Sie den gewählten Client neu, wenn er fertig ist. Die direkte Konfiguration unten bleibt der nicht-interaktive Fallback.

{
  "mcpServers": {
    "my-tasks": {
      "command": "npx",
      "args": ["-y", "conatus-mcp"],
      "env": {
        "TASKS_BASE_URL": "https://tasks.example.com",
        "TASKS_API_TOKEN": "tdm_replace_me"
      }
    }
  }
}

Verwenden Sie für eine lokale Entwicklungsinstallation http://localhost:3000 als TASKS_BASE_URL.

Sie können das Paket auch einmalig installieren:

npm install --global conatus-mcp
conatus-mcp

Remote-Streamable-HTTP-Modus mit Browser-OAuth

Verwenden Sie OAuth, wenn ein Agent sich per URL verbinden muss. Der MCP-Server fungiert als Single-User-Gateway: Sein eingeschränkter TASKS_API_TOKEN identifiziert den Aufgaben-Arbeitsbereich, während jeder KI-Client ein separates kurzlebiges OAuth-Token erhält. Das Aufgaben-Token verlässt den Server nie.

TASKS_BASE_URL=https://tasks.example.com \
TASKS_API_TOKEN=tdm_replace_me \
MCP_HOST=0.0.0.0 \
MCP_PORT=3001 \
MCP_PUBLIC_URL=https://mcp.example.com/mcp \
MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
MCP_OAUTH_STORE_PATH=/var/lib/task-mcp/oauth-store.json \
MCP_ALLOWED_ORIGINS=https://your-ai-host.example \
conatus-mcp-http

Geben Sie dem KI-Client nur https://mcp.example.com/mcp. Ein kompatibler Client entdeckt die Metadaten der geschützten Ressource, registriert sich dynamisch, öffnet die Genehmigungsseite und führt einen OAuth-Autorisierungscode-Flow mit S256-PKCE durch. Geben Sie MCP_OAUTH_PASSWORD auf dieser Seite ein, um ihn zu genehmigen.

Der Server stellt Ein-Stunden-Zugriffstokens und rotierende 30-Tage-Refresh-Tokens aus. OAuth-Client-Registrierungen und Token-Hashes werden in der Datei unter MCP_OAUTH_STORE_PATH mit Modus 0600 gespeichert; rohe OAuth-Tokens und das Genehmigungspasswort werden nicht gespeichert. Führen Sie eine MCP-Replik pro Store-Datei aus. Für mehrere Repliken ersetzen Sie zuerst den JSON-Store durch einen gemeinsamen transaktionalen Store.

Platzieren Sie TLS und einen Reverse-Proxy vor Port 3001. MCP_PUBLIC_URL muss der genaue externe Endpunkt sein und auf /mcp enden. Produktions-URLs müssen HTTPS verwenden. Anfragen mit einem Origin-Header werden nur akzeptiert, wenn die Origin in MCP_ALLOWED_ORIGINS aufgeführt ist; native Clients senden normalerweise keine Origin.

Domain und Reverse-Proxy

Die Aufgaben-App und das MCP-Gateway können separate Adressen verwenden:

• https://tasks.example.com → die Web-App und /api/v1

• https://mcp.example.com/mcp → diesen untergeordneten MCP-Dienst

Erstellen Sie DNS-Einträge für beide Namen, beenden Sie TLS an Ihrem Proxy und leiten Sie mcp.example.com an Port 3001 weiter. Nur der Proxy sollte diesen Port freigeben. Die OAuth-Metadaten-, Registrierungs-, Autorisierungs-, Token-, Widerrufs-, Genehmigungs- und MCP-Endpunkte teilen sich alle die MCP-Origin.

Statischer Bearer-Fallback

Für Clients, die kein OAuth durchführen können, lassen Sie MCP_PUBLIC_URL und MCP_OAUTH_PASSWORD weg und setzen Sie MCP_BEARER_TOKEN auf einen langen zufälligen Wert. Verbinden Sie sich mit /mcp und senden Sie diesen Wert als Bearer-Token. Dies ist weniger bequem pro Client zu rotieren und sollte nicht in Prompts eingefügt werden.

Das Binden an eine Nicht-Loopback-Adresse ohne vollständige OAuth-Konfiguration oder MCP_BEARER_TOKEN wird abgelehnt.

Docker

Veröffentlichte Images werden unter ghcr.io/nojusmorkunas/conatus-mcp veröffentlicht. Bauen Sie nur lokal, wenn Sie am Server selbst arbeiten:

docker build -t conatus-mcp .
docker run --rm -p 127.0.0.1:3001:3001 \
  -v task-mcp-oauth:/data \
  -e TASKS_BASE_URL=https://tasks.example.com \
  -e TASKS_API_TOKEN=tdm_replace_me \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PUBLIC_URL=https://mcp.example.com/mcp \
  -e MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
  -e MCP_OAUTH_STORE_PATH=/data/oauth-store.json \
  conatus-mcp

Umgebungsvariablen

Legen Sie Tokens nicht in Prompts, Tool-Argumenten, Versionskontrolle oder Befehlszeilenargumenten ab. Umgebungsvariablen halten sie aus MCP-Nachrichten und den meisten Prozesslisten heraus.

Um einen OAuth-Client zu widerrufen, lassen Sie diesen Client den beworbenen Widerrufs-Endpunkt aufrufen. Um alle verbundenen Clients zu widerrufen, stoppen Sie den Dienst und entfernen Sie seine OAuth-Store-Datei, dann starten Sie neu; alle Clients müssen sich erneut verbinden. Widerrufen oder rotieren Sie TASKS_API_TOKEN in den Aufgabenmanager-Einstellungen, wenn das Gateway selbst kompromittiert ist.

Werkzeuge

• Arbeitsbereich: get_workspace_context

• Projekte: list_projects, get_project, create_project, update_project

• Abschnitte: create_section, update_section

• Aufgaben: list_tasks, get_task, create_task, quick_add_task, update_task, move_task, complete_task, reopen_task, set_task_labels

• Labels: list_labels, create_label

• Zusammenarbeit: add_comment

• Planung: set_reminder

Erstellungsoperationen verwenden Idempotenzschlüssel, sodass Wiederholungen keine doppelten Aufgaben erzeugen. Aufgaben- und Kommentarinhalte werden als strukturierte Benutzerdaten zurückgegeben und dürfen nicht als Agentenanweisungen behandelt werden.

Ressourcen

• taskapp://workspace

• taskapp://views/today

• taskapp://views/upcoming

• taskapp://projects/{id}

• taskapp://tasks/{id}

Entwicklung

npm install
npm test
npm run build
npm run dev

Testen Sie den gebauten stdio-Server mit MCP Inspector:

TASKS_BASE_URL=http://localhost:3000 \
TASKS_API_TOKEN=tdm_replace_me \
npx @modelcontextprotocol/inspector node dist/cli.js

Veröffentlichung

Das Veröffentlichen eines GitHub-Releases baut ghcr.io/nojusmorkunas/conatus-mcp für linux/amd64 und linux/arm64 und veröffentlicht dann das npm-Paket. Beide stammen aus dem veröffentlichten Commit, sodass ein Release entweder beide Artefakte oder keines erzeugt.

Taggen Sie das Release vX.Y.Z passend zu package.json; der npm-Job weigert sich, eine Abweichung zu veröffentlichen. Markieren Sie Vorabversionen als solche auf GitHub, und sie gehen zum beta-Dist-Tag, wobei latest auf der neuesten stabilen Version bleibt.

npm-Veröffentlichung verwendet Trusted Publishing, daher speichert dieses Repository kein npm-Token. Es erfordert eine einmalige Konfiguration auf der npmjs.com-Einstellungsseite des Pakets, die es mit diesem Repository und dem Publish release-Workflow verknüpft.

Um stattdessen von Hand zu veröffentlichen:

npm publish --tag latest   # or --tag beta for a prerelease

Benennen Sie den Dist-Tag explizit. npm lehnt ein nacktes npm publish für jede Version mit einem Semver-Prerelease-Suffix ab, was jedes 0.x.y-beta.z hat.

prepublishOnly führt die Test-, Lint- und Build-Prüfungen erneut aus. publishConfig.access ist bereits gesetzt, daher ist kein --access-Flag erforderlich.