Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/VR-MCP.md
T

67 lines
4.6 KiB
Markdown

# VR-MCP · MCP-Server (Read- + Action-Tools für externe KI-Clients)
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | v2-P4 — MCP (ersetzt „KI-Tiefe", [[AD-26]]) |
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · Start 18.07. · fällig 2026-07-20 |
| **Status** | geplant (NEU — KI→MCP-Pivot) |
## Entscheidung / Kontext ([[AD-26]])
KI→MCP-Pivot: HiveGrid hostet **kein** eigenes LLM/RAG mehr. Statt KI-App wird HiveGrid **KI-anschließbar** über einen
**MCP-Server** (Model Context Protocol). Externe KI-Clients (Claude Desktop/Cursor/ChatGPT) docken an, **lesen**
HiveGrid-Daten und führen **Aktions-Tools** aus — die Inferenz liegt beim Client. Ersetzt [[VR-P25]] (HiveMind/RAG,
zurückgestellt). Baut auf der Public-API-Fläche ([[VR-P22a]]/[[VR-P22b]]) auf — **keine Doppelarbeit**.
## Was zu bauen ist
Remote MCP-Server, der die **mandanten-gescopte** HiveGrid-Daten-/Aktions-Fläche als MCP-**Tools** exponiert:
- **Transport:** Streamable HTTP (stateless Start), eigener Service-Bereich; **SDK `@modelcontextprotocol/sdk`** (das
Gerüst `apps/web/app/modules/mcp/` existiert bereits). Kein stdio, kein deprecated SSE.
- **Auth Stufe 1:** **API-Key-Bearer** (aus [[VR-P22b]] — Key → Tenant + User + Scopes). 401 mit `WWW-Authenticate`
bei Fehlschlag. **Stufe 2 (später, eigenes Ticket/CR):** OAuth 2.1 (PKCE, RFC 9728 Protected-Resource-Metadata,
RFC 8707 Resource-Indicators) für „Connect-in-Minutes".
- **Read-Tools:** `hg_lead_search`/`hg_lead_get`, `hg_contact_search`, `hg_project_get`, `hg_pipeline_list`
(`readOnlyHint`). (Tools statt Resources — breiterer Client-Support.)
- **Write-Tools:** `hg_lead_create`, `hg_project_set_stage`, `hg_activity_add` — je mit `withPermission()` +
**Client-Confirmation** + `auditEvent`/`logActivity`. Annotations (`destructiveHint`/`idempotentHint`) gesetzt.
- **Tenant aus dem Token** (NIE aus Tool-Argumenten) → `withTenantScope()` + RLS als zweite Mauer.
- **Security:** Rate-Limit pro Tenant/Token, Output-Limits + Pagination, Zod-Input-Validierung (Fehler als
`isError:true`), Origin- + Protocol-Version-Checks, **kein Token-Passthrough**, Tenant-Daten sind **Daten, nie
Instruktionen** (Prompt-Injection-Härtung).
## Benötigte Screens (Backend bedient — Design liefert [[VD-MCP]])
| Screen [Route] | Kern-Inhalt |
|---|---|
| MCP-Verbindungen [Settings] | API-Key generieren/rotieren/widerrufen + Scopes; aktive Verbindungen; Setup-Anleitung für Clients (Connector-URL + Key); Audit der MCP-Tool-Aufrufe |
## Definition of Done
- [ ] Remote-MCP-Server (Streamable HTTP) erreichbar; Session-Handling; Origin- + Protocol-Version-Checks
- [ ] **Auth Stufe 1** (API-Key-Bearer → Tenant/User/Scopes aus [[VR-P22b]]); 401+`WWW-Authenticate`
- [ ] **Read-Tools** (Lead/Contact/Project/Pipeline) tenant-gescopt via `withTenantScope()` + RLS
- [ ] **Write-Tools** mit `withPermission()` + Client-Confirmation + `auditEvent` + `logActivity`; Annotations gesetzt
- [ ] Rate-Limit pro Tenant; Output-Limits + Pagination; Zod-Validierung; Prompt-Injection-Härtung; kein Token-Passthrough
- [ ] Konnektor `tenantHasModule('mcp')`; RLS auf allen Tenant-Tabellen
- [ ] E2E: echter Client (Claude Desktop Custom Connector) verbunden + je 1 Read-/Write-Tool ausgeführt
- [ ] (Stufe 2 OAuth 2.1 → Folge-Ticket/CR, nicht in diesem Scope)
## Technische Bausteine
- `@modelcontextprotocol/sdk` (Server), `StreamableHTTPServerTransport`; eigener Service (`apps/mcp` oder Bereich in
`apps/api`) — **nicht** in RR7-Loader/Action quetschen.
- Auth/Scopes/Rate-Limit aus [[VR-P22b]] wiederverwenden; Tenant-Context-Middleware (Reihenfolge: TLS → Origin →
Protocol-Version → Token+Audience → Tenant-Context → Rate-Limit → Zod → `withPermission` → Handler → Output-Truncation
→ Audit).
- Querschnitt-Hülle: `withTenantScope`/`withPermission` (M004), `auditEvent` (M001), `logActivity`, `notify` (M011),
Klartext-Fehler (M002) auch in Tool-`isError`-Texten.
- Ausgangspunkt: vorhandenes `apps/web/app/modules/mcp/` (mcp.server.ts / mcp-tools.server.ts / fetch-transport.server.ts).
## Abhängigkeiten
- **blocked-by:** [[VR-P22a]] (Read-Endpoints + OpenAPI-Vertrag), [[VR-P22b]] (API-Key-Auth/Scopes/Rate-Limit) — beide
fällig 17.07., also **vor** dem MCP-Slot (18.07.) → kein Konflikt.
- **blocks:** — (Endpunkt der v2-MCP-Schiene)
- **Ersetzt:** [[VR-P25]] (HiveMind/RAG, zurückgestellt)
## Quellen
- [[AD-26]] (KI→MCP-Pivot) · MCP-Spec Rev. 2025-11-25 (modelcontextprotocol.io: Authorization/Transports/Tools/Security)
· TypeScript-SDK (github.com/modelcontextprotocol/typescript-sdk) · Anthropic „Writing tools for agents"