Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,66 @@
|
||||
# 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"
|
||||
Reference in new issue
Block a user