Claude Integration

Family Todo nutzt das Model Context Protocol (MCP) für die Integration mit Claude. Diese Seite erklärt, wie die Verbindung funktioniert.

Architektur

flowchart TB
    Claude[Claude AI]
    MCP[MCP Server]
    DB[(SQLite)]

    Claude <-->|OAuth 2.0| MCP
    Claude <-->|JSON-RPC| MCP
    MCP -->|raw SQL im Namen des Benutzers| DB

OAuth 2.0 Flow

Die Authentifizierung läuft über einen standardkonformen OAuth 2.0 Flow:

Client Registration: Claude registriert sich als OAuth-Client beim MCP Server
Authorization: Der Benutzer wird zur Anmeldung weitergeleitet
Token Exchange: Nach erfolgreicher Anmeldung erhält Claude einen JWT Access Token
API Access: Alle MCP-Aufrufe werden mit dem Bearer Token authentifiziert

Sicherheit

PKCE (S256): Schutz gegen Authorization Code Interception
JWT Access Tokens: Stateless, signiert mit RS256
Gescopeter Zugriff: Der MCP Server agiert im Namen des angemeldeten Benutzers und liest/schreibt nur dessen Daten

MCP Protocol

Das Model Context Protocol definiert, wie Claude mit externen Tools kommuniziert.

Initialization

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "id": 1
}

Antwort:

{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "family-todo-mcp",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": {}
    }
  },
  "id": 1
}

Verfügbare Tools

Claude kann folgende Tools aufrufen:

Tool	Beschreibung
`list_groups`	Alle Familien des Benutzers anzeigen
`create_group`	Neue Familie erstellen
`delete_group`	Familie löschen
`list_children`	Kinder einer Familie anzeigen
`create_child`	Kind hinzufügen
`update_child`	Kind bearbeiten
`delete_child`	Kind entfernen
`list_tasks`	Aufgaben eines Kindes anzeigen
`create_task`	Aufgabe erstellen
`update_task`	Aufgabe bearbeiten
`delete_task`	Aufgabe löschen
`reset_task`	Erledigte Aufgabe zurücksetzen

Beispiel: Aufgabe erstellen

Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_task",
    "arguments": {
      "childId": "abc123",
      "title": "Hausaufgaben machen",
      "priority": 1
    }
  },
  "id": 5
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "Created task \"Hausaufgaben machen\" (ID: xyz789)"
    }]
  },
  "id": 5
}

Discovery Endpoints

Der MCP Server stellt standardkonforme Discovery-Endpoints bereit:

/.well-known/oauth-authorization-server – OAuth Metadata
/.well-known/oauth-protected-resource – Protected Resource Metadata
/.well-known/jwks.json – Public Keys für JWT Verification

Selbst hosten

Family Todo ist Open Source. Du kannst den MCP Server selbst hosten:

git clone https://github.com/levino/todo-app
cd todo-app
npm install
npm run dev

Der MCP Server liest folgende Umgebungsvariablen:

OAUTH_ISSUER=https://your-domain.com   # öffentliche Issuer-URL des MCP-OAuth-Servers
FRONTEND_URL=https://your-app.com      # Frontend-URL für den Login-Redirect
DB_PATH=/data/app.db                   # SQLite-Datei (gemeinsam mit dem Frontend)

Die vollständige Liste der Variablen und das Produktiv-Deployment (Kubernetes) stehen im README des Repositories.