Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
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).
|
||||
|
||||
|
||||
Reference in new issue
Block a user