60 lines
3.3 KiB
Markdown
60 lines
3.3 KiB
Markdown
# Workflow-MCP-Server
|
|
|
|
MCP-Server (Model Context Protocol) des Workflow-Systems. Erlaubt KI-Clients, Workflows zu erstellen, zu bearbeiten, zu starten und mit laufenden Instanzen zu interagieren.
|
|
|
|
## Endpoint & Auth
|
|
|
|
- **URL:** `https://workflow.flurneuordnung-sachsen.de/mcp` (JSON-RPC 2.0 ueber HTTP POST, „Streamable HTTP")
|
|
- **Auth:** HTTP-Header `Authorization: Bearer <token>`
|
|
- **Keys:** werden im Workflow-Dashboard (`dashboard.php` → Card „MCP-API-Keys") erstellt. Der Klartext-Token ist **nur einmal** bei der Erstellung sichtbar (Server speichert nur den SHA-256-Hash).
|
|
|
|
## Scopes
|
|
|
|
Jeder Key traegt eine Auswahl aus drei Scopes; `tools/list` zeigt nur erlaubte Tools, `tools/call` prueft den Scope.
|
|
|
|
| Scope | Tools |
|
|
|---|---|
|
|
| `read` | workflow_list, workflow_get, workflow_validate, workflow_instances, workflow_status, workflow_log |
|
|
| `author` | workflow_create, workflow_update |
|
|
| `interact` | workflow_start, workflow_interact |
|
|
|
|
## Tools
|
|
|
|
| Tool | Zweck |
|
|
|---|---|
|
|
| `workflow_list` | Alle Definitionen (workflows/*.xml) mit ID/Task-Anzahl. |
|
|
| `workflow_get` | XML-Definition eines Workflows. |
|
|
| `workflow_validate` | Workflow-XML auf Wohlgeformtheit + Grundstruktur pruefen. |
|
|
| `workflow_instances` | Laufende/vergangene Instanzen (filterbar nach status/type/assignee). |
|
|
| `workflow_status` | Detailstatus einer Instanz (Status, Bearbeiter, Kontext, Tokens). |
|
|
| `workflow_log` | Fachliches Audit-Log einer Instanz. |
|
|
| `workflow_create` | Neue Definition anlegen (Fehler, wenn Name existiert). |
|
|
| `workflow_update` | Definition ueberschreiben (mit automatischem Backup). |
|
|
| `workflow_start` | Neue Instanz starten und ersten Schritt ausfuehren. |
|
|
| `workflow_interact` | Laufende Instanz weiterfuehren; optional Kontextvariablen einspielen. |
|
|
|
|
## Beispiel
|
|
|
|
```bash
|
|
curl -s -X POST https://workflow.flurneuordnung-sachsen.de/mcp \
|
|
-H "Authorization: Bearer wfmcp_..." \
|
|
-d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"workflow_list\",\"arguments\":{}}}"
|
|
```
|
|
|
|
## Technik
|
|
|
|
Code unter `0_workflow/mcp/`: `index.php` (Bootstrap + Auth + JSON-RPC-Transport), `McpServer.php` (Protokoll + Registry + Scope-Enforcement), `WorkflowTools.php` (Fachlogik), `McpKeys.php` (Key-Verwaltung, Tabelle `WORKFLOW_MCP_KEY`). nginx: exakte `location = /mcp` noetig (sonst faengt der Scan-Blocker den slash-losen Pfad ab).
|
|
|
|
|
|
## Verbinden mit claude.ai (OAuth)
|
|
|
|
Der claude.ai-Connector nutzt **OAuth 2.1** (statische Bearer-Keys funktionieren dort nicht). Der Server bildet OAuth auf die MCP-Keys ab.
|
|
|
|
1. In claude.ai einen **Custom Connector** anlegen, als URL **nur** `https://workflow.flurneuordnung-sachsen.de/mcp` eintragen — KEIN client_id / kein Key in die Connector-Felder.
|
|
2. Auf **Verbinden** klicken. Es öffnet sich eine Anmeldeseite des Workflow-MCP.
|
|
3. Dort den `wfmcp_…`-Key (aus dem Dashboard) eingeben → Zugriff erlauben. Das erteilte Token trägt die Scopes dieses Keys.
|
|
|
|
Discovery/Endpunkte (automatisch genutzt): `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`, `/register` (DCR), `/authorize`, `/token`.
|
|
|
|
**Fehler „nur die Startseite erscheint" / „invalid_client":** Der Connector wurde mit dem Key als client_id angelegt (ohne Discovery). Connector entfernen und neu hinzufügen — dann registriert sich claude.ai selbst.
|