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

4.6 KiB

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"