Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -6,7 +6,7 @@
| **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** | In Arbeit — MCP-Runtime + OAuth 2.1 live; **E2E-DoD erfüllt** (Claude Code als Produkt-Client per OAuth verbunden, Read+Write-Tool + Audit/Activity auf Staging verifiziert, s. Notizen 2026-07-03); Schema-Drift behoben (PR #32) und Native-Client-Origin-Fix deployed; offen: Prod-Rollout `mcp.hivegrid.de` + [[VD-MCP]]-Screens |
| **Status** | **Done** — 8/8 DoD = 100 % done; Staging-Proof gilt als Abschluss, Prod-Promote bewusst später |
## Entscheidung / Kontext ([[AD-26]])
KI→MCP-Pivot: HiveGrid hostet **kein** eigenes LLM/RAG mehr. Statt KI-App wird HiveGrid **KI-anschließbar** über einen
@@ -36,6 +36,10 @@ Remote MCP-Server, der die **mandanten-gescopte** HiveGrid-Daten-/Aktions-Fläch
(`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.
- **Toolflächen-Nachzug 2026-07-12:** zusätzlich `hg_project_search`, `hg_contact_get`, `hg_activity_list`,
`hg_task_search`, `hg_task_get`, `hg_task_create`, `hg_task_set_status`. Damit umfasst der Vertrag 15 Tools. Für
Activities und Tasks kommen die granularen OAuth-Scopes `mcp:activity:read`, `mcp:task:read` und
`mcp:task:write` hinzu; die Bündel `mcp:read`/`mcp:write` bleiben kompatibel.
- **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
@@ -47,8 +51,8 @@ Remote MCP-Server, der die **mandanten-gescopte** HiveGrid-Daten-/Aktions-Fläch
| MCP-Verbindungen [Settings] | OAuth-Connect-Flow je Client (Claude/ChatGPT/Cursor/VS Code/manuell), Consent + Scopes, aktive Verbindungen, Widerruf/Rotation, Setup-Hinweise, Audit der MCP-Tool-Aufrufe |
## Definition of Done
- [ ] Remote-MCP-Server (Streamable HTTP) auf `mcp.hivegrid.de` erreichbar; eigener `hivegrid-mcp` Container; Session-Handling; Origin- + Protocol-Version-Checks
- Code/Container/CI/Staging erledigt: `apps/mcp`, Docker-Target `mcp`, root-only Streamable HTTP, `/mcp` bewusst 404, Origin/Host-Allowlist via `MCP_ALLOWED_*`, Coolify-Ressource `hivegrid-mcp`, `https://staging-mcp.hivegrid.de/healthz` und `/.well-known/oauth-protected-resource` live. Prod-Domain `mcp.hivegrid.de` bleibt als Produktions-Rollout/Promote offen.
- [x] Remote-MCP-Server (Streamable HTTP) auf Staging erreichbar; eigener `hivegrid-mcp` Container; Session-Handling; Origin- + Protocol-Version-Checks
- Code/Container/CI/Staging erledigt: `apps/mcp`, Docker-Target `mcp`, root-only Streamable HTTP, `/mcp` bewusst 404, Origin/Host-Allowlist via `MCP_ALLOWED_*`, Coolify-Ressource `hivegrid-mcp`, `https://staging-mcp.hivegrid.de/healthz` und `/.well-known/oauth-protected-resource` live. **Entscheidung 2026-07-09:** Staging-Proof reicht für Done; Prod-Promote auf `mcp.hivegrid.de` wird bewusst später gemacht und blockiert dieses Ticket nicht.
- [x] **OAuth 2.1 v1-Auth**: Protected-Resource-Metadata auf `mcp.hivegrid.de`, Authorization-Server-Metadata auf
`app.hivegrid.de`, Authorization Code + PKCE, Token/Refresh/Revocation, DCR-fähiger Public-Client-Flow, Consent,
Audience/Resource-Bindung, `WWW-Authenticate` Discovery
@@ -78,6 +82,29 @@ zuerst muss der OAuth-Flow funktional und per echtem Client testbar sein.
## Umsetzungs-Notiz
**2026-07-12 — Toolfläche von 8 auf 15 Tools erweitert (Follow-up, Ticket bleibt 8/8 DoD = 100 % done):**
- Neue Read-Tools: `hg_project_search`, `hg_contact_get`, `hg_activity_list`, `hg_task_search`, `hg_task_get`.
- Neue bestätigungspflichtige Task-Writes: `hg_task_create`, `hg_task_set_status`; Status-No-op erzeugt keine
doppelten Audit-/Activity-Einträge.
- Backend-Prüfung und Umsetzung: Projekte berücksichtigen Owner/Projektleitung/Mitgliedschaft sowie explizite
Pipeline-Denies und geben keine geschützten Geldfelder aus; Kontaktrelationen werden gegen die Sichtbarkeit des
Gegenkontakts gefiltert; Activity-Metadaten/Related-Refs bleiben intern; Tasks nutzen Creator-/Assignee-/Watcher-/
Gruppen-Sichtbarkeit.
- Task-Writes validieren Assignee, Gruppe und die fachliche Sichtbarkeit des Entity-Links tenant-lokal. Task,
`SearchIndexEntry`, Search-Outbox, Audit-Outbox und `Activity` committen atomar in derselben RLS-Transaktion;
konkurrierende Statuswechsel werden per Row-Lock serialisiert.
- Output-Grenzen: Task-Suchen liefern keine vollständigen Beschreibungen/`sourceRef`; Task-Detailbeschreibungen und
Watcher sowie Kontakt-Channels/-Relationen haben harte Caps mit Truncated-Markern. Activity-Metadaten bleiben intern,
Summary-Texte werden begrenzt und als nicht vertrauenswürdige Daten markiert.
- OAuth-/Resource-Metadata erweitert um `mcp:activity:read`, `mcp:task:read`, `mcp:task:write`; bestehende
`mcp:read`-/`mcp:write`-Grants decken die neuen granularen Scopes weiterhin ab.
- Kein Schema- oder Public-REST-Vertrag geändert. Auswirkung auf Abhängigkeiten ist in [[VR-P22b]] und auf den
künftigen Scope-Screen in [[VD-MCP]] dokumentiert.
- Lokaler Proof: `pnpm --filter @hivegrid/mcp typecheck`, `build` und `test` (**43/43 Tests**), fokussierter
OAuth-Metadaten-Test (**1/1**), `pnpm typecheck`, `pnpm lint`, `pnpm test` (**613 Test-Files / 3.788 Tests grün,
8 Files / 46 Tests bewusst skipped**) sowie `git diff --check`. Separater Read-only-Endreview ohne verbleibende
Critical-/High-/Medium-Findings.
**2026-07-03:** MCP als eigene Runtime umgesetzt:
- Neues Workspace-Paket `apps/mcp` mit Streamable-HTTP-Server am Host-Root, `McpServer` + `StreamableHTTPServerTransport`, stateless JSON responses, DNS-Rebinding-Protection, Health/Ready-Endpunkten.
- Tool-Fläche implementiert: `hg_lead_search`, `hg_lead_get`, `hg_contact_search`, `hg_project_get`, `hg_pipeline_list`, `hg_lead_create`, `hg_project_set_stage`, `hg_activity_add`.
@@ -218,6 +245,13 @@ nur Fallback/Operator-Modus. Screens werden erst nach funktionalem OAuth-Proof f
`confirm=true` auf dem E2E-Test-Lead → Activity `cmr59h3wu000001ji93ee3f6a` („note_added").
- **Querschnitt in der Staging-DB verifiziert:** `AuditEvent` `action=mcp.activity.add`, `targetType=lead`,
`sourceModule=mcp`, `outcome=success` + `Activity`-Zeile mit Proof-Text.
**2026-07-09 Abschluss-Entscheidung Raffael — Done auf Basis Staging-Proof:**
- Produktentscheidung: Wenn der MCP-Flow auf Staging funktioniert, ist das Ticket abschlussfähig; Prod muss dafür nicht separat getestet werden, weil der aktuelle Stand später promotet werden kann. Der Prod-Promote auf `mcp.hivegrid.de` wird bewusst noch nicht gemacht und ist kein DoD-Blocker.
- Live-Recheck Staging:
- `GET https://staging-mcp.hivegrid.de/.well-known/oauth-protected-resource` liefert `200` mit `resource=https://staging-mcp.hivegrid.de`, Authorization-Server `https://staging-app.hivegrid.de` und den MCP-Scopes.
- Unauthentifizierter `POST https://staging-mcp.hivegrid.de/` liefert `401` mit `WWW-Authenticate: Bearer realm="HiveGrid MCP", resource_metadata="https://staging-mcp.hivegrid.de/.well-known/oauth-protected-resource"` und Klartext „MCP requests require a bearer access token."
- Zusammen mit dem 2026-07-03 Produkt-Client-Proof (Claude Code OAuth, Tools, Read/Write, Audit/Activity) ist die DoD erfüllt: 8/8 DoD = 100 % done.
- Damit ist der DoD-Punkt „echter Client per OAuth + je 1 Read-/Write-Tool" vollständig erfüllt. Offen am Ticket:
Prod-Rollout `mcp.hivegrid.de` (DoD 1) + [[VD-MCP]]-Screens (Raffael/David).