4.6 KiB
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üstapps/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-Authenticatebei 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 mitwithPermission()+ 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/mcpoder Bereich inapps/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"