245 lines
22 KiB
Markdown
245 lines
22 KiB
Markdown
# 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** | 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 |
|
|
|
|
## 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**.
|
|
|
|
## Host-/Runtime-Contract (verbindlich)
|
|
|
|
- MCP läuft ausschließlich auf **`mcp.hivegrid.de`** (staging: `staging-mcp.hivegrid.de`).
|
|
- MCP läuft als eigener Coolify-Service/Container **`hivegrid-mcp`** mit eigener Runtime (`apps/mcp`), nicht im Web-
|
|
oder Public-API-Container.
|
|
- Public API bleibt auf `api.hivegrid.de`; MCP-Routen werden nicht unter `app.hivegrid.de` oder `api.hivegrid.de`
|
|
bereitgestellt. Auth/Scopes/Rate-Limit werden aus VR-P22b wiederverwendet, aber die Host-/Runtime-Surface bleibt getrennt.
|
|
- MCP nutzt den Host selbst als Connector-URL; es gibt keinen zusätzlichen `/mcp`-Pfad.
|
|
|
|
## 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) auf `https://mcp.hivegrid.de`; **SDK `@modelcontextprotocol/sdk`**.
|
|
Kein stdio, kein deprecated SSE.
|
|
- **Auth v1:** **OAuth 2.1 Authorization Code + PKCE** für „Connect-in-Minutes" aus Claude/Cursor/ChatGPT.
|
|
MCP ist Resource Server auf `https://mcp.hivegrid.de`; HiveGrid Web ist Authorization Server auf `https://app.hivegrid.de`.
|
|
Pflicht: RFC 9728 Protected-Resource-Metadata, RFC 8414 Authorization-Server-Metadata, Resource-Indicator/Audience-Bindung,
|
|
kurzlebige Access Tokens, rotierende Refresh Tokens, Consent + Widerruf. API-Key-Bearer bleibt nur als Operator-/Fallback-Pfad,
|
|
nicht als primärer User-Connect-Flow.
|
|
- **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] | 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] **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
|
|
- [x] **Fallback/Operator-Auth** (API-Key-Bearer → Tenant/User/Scopes aus [[VR-P22b]]); 401+`WWW-Authenticate`
|
|
- [x] **Read-Tools** (Lead/Contact/Project/Pipeline) tenant-gescopt via `withTenantScope()` + RLS
|
|
- [x] **Write-Tools** mit `withPermission()` + Client-Confirmation + `auditEvent` + `logActivity`; Annotations gesetzt
|
|
- [x] Rate-Limit pro Tenant; Output-Limits + Pagination; Zod-Validierung; Prompt-Injection-Härtung; kein Token-Passthrough
|
|
- [x] Konnektor `tenantHasModule('mcp')`; RLS auf allen Tenant-Tabellen
|
|
- [x] E2E: echter Client per OAuth (Claude/Cursor/ChatGPT oder MCP Inspector) verbunden + je 1 Read-/Write-Tool ausgeführt — **erfüllt 2026-07-03 mit Claude Code** (s. Proof-Notizen unten)
|
|
- Teilproof 2026-07-03: Dynamic Client Registration + Authorization Code + PKCE + Token Exchange auf Staging erfolgreich; offizieller MCP SDK Client verbindet gegen `https://staging-mcp.hivegrid.de/` und listet 8 Tools. Offen: Read-/Write-Tool mit fachlichem Ergebnis; `hg_pipeline_list` scheiterte an fehlender Staging-DB-Tabelle `public.Pipeline` — **aufgelöst 2026-07-03 (Akeshan, s. Notiz unten)**: Migration manuell per `prisma migrate deploy` nachgezogen, Tabelle vorhanden.
|
|
- **Funktionaler Voll-Proof 2026-07-03 abends (Akeshan, s. Notiz unten):** kompletter OAuth-Flow (DCR mit Scopes + Browser-Consent + PKCE) + `tools/list` (8 Tools) + Read-Tool `hg_pipeline_list` (Sales-Pipeline mit 5 Stages) + Write-Tool `hg_lead_create` mit `confirm=true` (InboxLead angelegt) + `AuditEvent` (`mcp.lead.create`, sourceModule `mcp`, outcome `success`) + `Activity` (`lead_created`, „Lead per MCP erstellt.") in der Staging-DB verifiziert. Für den formalen Haken fehlt nur noch der Connect mit einem der **benannten** Produkt-Clients (Claude/Cursor/ChatGPT/MCP Inspector) — funktional ist nichts mehr offen.
|
|
|
|
**Stand 2026-07-03:** Scope-Update: MCP-Runtime/Tools/Deploy sind live und serverseitig verifiziert, aber OAuth 2.1 ist
|
|
ab sofort v1-Pflicht und ersetzt den API-Key-Copy-Flow als primären User-Connect. Screens bleiben Folgearbeit aus [[VD-MCP]];
|
|
zuerst muss der OAuth-Flow funktional und per echtem Client testbar sein.
|
|
|
|
## Technische Bausteine
|
|
- `@modelcontextprotocol/sdk` (Server), `StreamableHTTPServerTransport`; eigener Service **`apps/mcp` → `hivegrid-mcp`**.
|
|
**Nicht** in `apps/web`, `apps/api` oder RR7-Loader/Action quetschen.
|
|
- Auth/Scopes/Rate-Limit aus [[VR-P22b]] wiederverwenden, aber als OAuth-Access-Token-Validierung kapseln; Tenant-Context-Middleware
|
|
(Reihenfolge: TLS → Origin → Protocol-Version → OAuth Token + Audience/Resource → 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).
|
|
2026-07-03 bereinigt: der alte Web-`/mcp`-Code wurde entfernt; MCP lebt jetzt ausschließlich in `apps/mcp`.
|
|
|
|
## Umsetzungs-Notiz
|
|
|
|
**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`.
|
|
- Auth/Scopes/Rate-Limit umgesetzt: Bearer-API-Key, Tenant/User aus Key, `WWW-Authenticate` bei 401, MCP-Scope-Checks, Tenant/API-Key-Limits über Shared Store.
|
|
- Sicherheits- und Cross-Cutting-Wiring umgesetzt: Tenant aus Token, Zod-Inputs, Cursor-Pagination, kompakte Outputs, `confirm=true` für Writes, `withPermission`, `withTenantScope`, `auditEvent`, `logActivity`, Prompt-Injection-Hinweise in Tool-Beschreibungen/Output.
|
|
- Deploy/Runtime vorbereitet: Docker-Target `mcp`, `verify:docker-mcp-runtime-smoke`, Gitea-CI Job für MCP, Deploy-Workflow baut/pusht `web/api/worker/mcp` und deployt `hivegrid-mcp` als abhängige HTTP-Ressource.
|
|
- Web-Altlast entfernt: `apps/web/app/modules/mcp/**` und `apps/web/app/routes/mcp/**` gelöscht; `mcp/**` bleibt nur als disabled/reserved route tree, nicht als aktive Web-Route.
|
|
- Env/Doku aktualisiert: `MCP_HOST`, `MCP_PORT`, `MCP_ALLOWED_HOSTS`, `MCP_ALLOWED_ORIGINS`, `API_KEY_HASH_SECRET`, Env-Katalog, Deployment-Doku.
|
|
|
|
**2026-07-03 Scope-Entscheidung:** OAuth 2.1 wird nicht mehr als spätere Stufe behandelt, sondern als v1-Funktionsscope.
|
|
Begründung: Der gewünschte „Mit Claude/ChatGPT verbinden"-Flow braucht Discovery + Browser-Consent; statische API-Key-Config ist
|
|
nur Fallback/Operator-Modus. Screens werden erst nach funktionalem OAuth-Proof finalisiert.
|
|
|
|
**2026-07-03 OAuth-Implementierung:** OAuth 2.1 serverseitig umgesetzt:
|
|
- Neue Prisma-Modelle/Migration `mcpOAuth.prisma` + `20260703110500_vr_mcp_oauth`: `McpOAuthClient`,
|
|
`McpOAuthAuthorizationCode`, `McpOAuthAccessToken`, `McpOAuthRefreshToken`; Codes/Tokens nur hash-only.
|
|
- Authorization Server im Web: `/.well-known/oauth-authorization-server`, `/oauth/register`, `/oauth/authorize`,
|
|
`/oauth/authorize/approve`, `/oauth/token`, `/oauth/revoke`.
|
|
- MCP Resource Server: `/.well-known/oauth-protected-resource`, `WWW-Authenticate` mit Resource-Metadata, OAuth-Bearer-
|
|
Validierung mit Audience/Resource-Bindung; API-Key bleibt Fallback/Operator-Pfad.
|
|
- Staging/Prod-Config ergänzt: `MCP_RESOURCE_URL`, `MCP_AUTHORIZATION_SERVER_URL`, optional
|
|
`MCP_OAUTH_TOKEN_HASH_SECRET`; Staging muss `https://staging-mcp.hivegrid.de` und
|
|
`https://staging-app.hivegrid.de` setzen.
|
|
|
|
**Aktueller Proof lokal (OAuth-Änderung):**
|
|
- `pnpm --dir . exec prisma validate`
|
|
- `pnpm --filter @hivegrid/db typecheck`
|
|
- `pnpm --filter @hivegrid/db test -- --run src/api-keys.server.test.ts` (Vitest-Wrapper lief paketweit: 57 Files, 437 Tests grün, 8 skipped)
|
|
- `pnpm --filter @hivegrid/web typecheck`
|
|
- `pnpm --filter @hivegrid/mcp typecheck`
|
|
- `pnpm --filter @hivegrid/mcp test`
|
|
|
|
**2026-07-03 Staging-/MCP-Client-Proof und aktueller Übergabestand:**
|
|
- Commits auf `main`:
|
|
- `368533436` `ci(deploy): stop exporting registry build cache` — behebt Registry-Build-Cache-Export-Timeouts im CI.
|
|
- `646f815b4` `fix(mcp): expose oauth metadata route` — `/.well-known/oauth-authorization-server` als echte Web-Route registriert.
|
|
- `fede041de` `fix(mcp): clarify missing bearer token error` — 401-Text spricht korrekt von OAuth-Bearer-Access-Token.
|
|
- `2663e019b` / `6b97ebf96` — MCP-Transport-Lifecycle gefixt; Server bleibt bis zum HTTP-Response-Finish offen.
|
|
- `ee4c9a394` `fix(db): add project pipeline core migration` — fehlende P8-Projekt-/Pipeline-Core-Migration ergänzt.
|
|
- Manuell verifiziert auf Staging:
|
|
- `https://staging-app.hivegrid.de/.well-known/oauth-authorization-server` liefert `200` inkl. Authorization-/Token-/Registration-Endpunkten.
|
|
- `https://staging-mcp.hivegrid.de/.well-known/oauth-protected-resource` liefert `200` inkl. Resource `https://staging-mcp.hivegrid.de`.
|
|
- Unauthentifizierter MCP-Request liefert `401` mit `WWW-Authenticate` und `resource_metadata`.
|
|
- Dynamic Client Registration (`/oauth/register`) + Browser-Authorize + PKCE-Code-Exchange (`/oauth/token`) funktionieren; Token-Werte wurden nicht dokumentiert.
|
|
- Offizieller `@modelcontextprotocol/sdk` Client verbindet mit OAuth-Bearer-Token und listet Tools:
|
|
`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`.
|
|
- Offen bei Übergabe an Akeshan:
|
|
- Gitea-Deploy-Run `9168` für `ee4c9a394` wurde grün; `https://staging-app.hivegrid.de/healthz` und
|
|
`https://staging-mcp.hivegrid.de/healthz` zeigen beide Revision `ee4c9a394032b66ad8e76895157a0c2527983a81`.
|
|
- Trotzdem scheitert `hg_pipeline_list` weiter mit `The table public.Pipeline does not exist in the current database`.
|
|
Nächster Check: Hat Coolify die Web-Pre-Deployment-Migration wirklich ausgeführt, gegen welche `DATABASE_URL`/`DIRECT_URL`
|
|
lief sie, und nutzt `hivegrid-mcp` dieselbe Staging-DB wie `hivegrid-web`?
|
|
- Nach erfolgreichem Deploy/Migrate erneut testen:
|
|
1. Mit dem bestehenden oder neuem OAuth-Token per MCP SDK `client.listTools()` prüfen.
|
|
2. `client.callTool({ name: "hg_pipeline_list", arguments: {} })` muss nach Migration nicht mehr mit `public.Pipeline does not exist` scheitern.
|
|
3. Für vollständigen E2E danach ein Write-Tool mit `confirm=true` in einem geeigneten Test-Tenant ausführen und Audit/Activity prüfen.
|
|
- Lokaler Proof für die Migration:
|
|
- `pnpm exec prisma validate --config prisma.config.ts`
|
|
- isolierter Postgres-16-Container: Migration `20260703123000_p8_project_pipeline_core/migration.sql` mit `psql -v ON_ERROR_STOP=1` erfolgreich angewendet; Tabellen `Pipeline`, `PipelineStage`, `Projekt` vorhanden.
|
|
|
|
**2026-07-03 (Akeshan) — Staging-Migrations-Blocker aufgelöst (manuell nachgezogen):**
|
|
- **Befund:** `prisma migrate status` im Staging-Web-Container zeigte `20260703123000_p8_project_pipeline_core` als
|
|
einzige nicht angewandte Migration (166/167 applied), obwohl Deploy-Run `9168` grün war und Revision `ee4c9a394`
|
|
lief. **Ursache = wie beim Befund in [[AK-P4a]] (2026-06-23):** Coolify führt den per Deploy-Workflow gesetzten
|
|
`pre_deployment_command` (`prisma migrate deploy`) **nicht zuverlässig** aus — die beiden früheren Migrationen vom
|
|
selben Tag (07:01/09:33 UTC) kamen an, die von Run `9168` nicht. Der Deploy verifiziert auf Staging nur
|
|
Health/Revision, keinen Migrations-Status → das Loch fällt erst beim ersten fachlichen Query auf.
|
|
- **Fix (bewusst nur manueller Trigger, Hook-Reparatur separat):** `pnpm exec prisma migrate deploy --config
|
|
prisma.config.ts` im Staging-Web-Container ausgeführt; Migration sauber angewandt (`_prisma_migrations` 14:25 UTC).
|
|
- **Verifiziert:** `migrate status` → „Database schema is up to date" (167/167); `SELECT count(*)` auf
|
|
`Pipeline`/`PipelineStage`/`Projekt` liefert 3/15/0 statt `TableDoesNotExist`. **Raffaels DB-Frage geklärt:**
|
|
`hivegrid-web` und `hivegrid-mcp` nutzen dieselbe DB (`DATABASE_URL` = `DIRECT_URL` = selbe Postgres-Instanz,
|
|
DB `hivegrid`) — kein URL-Mismatch.
|
|
- **Nächster Schritt E2E:** `client.callTool({ name: "hg_pipeline_list" })` erneut testen (sollte jetzt Daten liefern),
|
|
danach Write-Tool mit `confirm=true` + Audit/Activity-Check.
|
|
- **⚠️ Separater Befund (blockiert Teile des E2E, eigenes Follow-up nötig):** Die Staging-DB hat darüber hinaus
|
|
**massiven Schema-Drift**: `prisma migrate diff` (DB → Schema) zeigt **93 fehlende Tabellen**, für die **gar keine
|
|
Migrations-Files existieren** (AD-21-Muster: Feature-Branch `db push`, Merge-Migration nie erzeugt) — u.a. `Kontakt`,
|
|
`InboxLead`, `Dashboard`, Auftrag-/Automation-/Kalender-/HR-/Forms-Domänen. Konsequenz hier: `hg_contact_search`/
|
|
`hg_lead_search`/`hg_lead_create` laufen auf Staging weiter in `TableDoesNotExist`, bis die fehlenden
|
|
Merge-Migrationen erzeugt sind; sichtbares Symptom in der Web-App: 500 auf `/demo-pro-crm/dashboard`
|
|
(`prisma.dashboard.upsert` → `public.Dashboard` fehlt). Der CI-Gate „migrate deploy gegen leere DB"
|
|
(`infra/LESSONS.md §9`) fängt das nicht — er prüft nur vorhandene Migrations-Files, nicht Schema↔Migrations-Parität
|
|
(dafür bräuchte es `prisma migrate diff --from-migrations --to-schema --exit-code` als Gate).
|
|
|
|
**2026-07-03 abends (Akeshan) — Schema-Drift behoben + funktionaler E2E-Tool-Proof:**
|
|
- **Drift-Befund von heute Mittag ist behoben:** PR #32 (`akeshan/schema-parity-catchup`, gemerged als `cf2d4d678`)
|
|
liefert die AD-21-Aufhol-Migration `20260703150000_ak_schema_parity_catchup` (93 Tabellen/88 Enums, idempotent nach
|
|
P8-Muster) **plus** den neuen CI-Gate `verify:migrations-parity` (Migrations-Replay in ephemeren Postgres, Diff gegen
|
|
`prisma/schema`, verdrahtet im `database`-Job beider CI-Workflows) — „Schema geändert, Merge-Migration vergessen"
|
|
bricht ab jetzt den PR statt erst Staging. Coolify-Hook hat die Migration beim Deploy erneut NICHT ausgeführt →
|
|
manuell nachgezogen, `migrate status` 168/168 up to date, 262 Tabellen; `/demo-pro-crm/dashboard` und `/contacts`
|
|
rendern (vom User im Browser bestätigt).
|
|
- **E2E-Tool-Proof gegen `https://staging-mcp.hivegrid.de/`** (standards-konformer OAuth-2.1-Client, Streamable HTTP):
|
|
1. DCR `/oauth/register` — wichtig: `scope` muss im Registration-Request mitgegeben werden, sonst wird der Client
|
|
nur mit Default-Scope registriert und `/oauth/authorize` lehnt mit „Scope not registered for this client" ab.
|
|
2. Browser-Authorize + Consent (User-Session) + PKCE-S256-Code-Exchange → Access-Token mit allen 9 Scopes (1h).
|
|
3. MCP-Requests brauchen einen **erlaubten `Origin`-Header** (`MCP_ALLOWED_ORIGINS` = `https://staging-app.hivegrid.de`,
|
|
`https://staging-web.hivegrid.de`) — sonst 403 „Invalid Origin header".
|
|
4. `initialize` + `tools/list` → 8 Tools; **Read:** `hg_pipeline_list` liefert die Sales-Pipeline mit 5 Stages
|
|
(tenant-gescopt, Tenant `demo-business-crm`); **Write:** `hg_lead_create` mit `confirm=true` legt
|
|
`InboxLead cmr57zk0f000001mptutf1qf8` an (E2E Proof / vr-mcp-e2e-proof@example.test, status `new`, quelle `custom`).
|
|
5. Querschnitt verifiziert in der Staging-DB: `AuditEvent` (`action=mcp.lead.create`, `targetType=lead`,
|
|
`sourceModule=mcp`, `outcome=success`) + `Activity` (`activityType=lead_created`, `actorKind=automation`,
|
|
„Lead per MCP erstellt.") — beide mit der Lead-Id als Target/Subject.
|
|
- **Rest für den formalen DoD-Haken:** einmaliger Connect mit einem benanntem Produkt-Client
|
|
(Claude/Cursor/ChatGPT/MCP Inspector) — funktional ist der Pfad komplett bewiesen. Danach Prod-Rollout
|
|
(`mcp.hivegrid.de`) + [[VD-MCP]]-Screens.
|
|
|
|
**2026-07-03 spät (Akeshan) — Produkt-Client-Connect (Claude Code) blockiert durch Origin-Check, Fix auf diesem Branch:**
|
|
- **Befund:** Claude Code als benannter Produkt-Client (`claude mcp add --transport http hivegrid-staging
|
|
https://staging-mcp.hivegrid.de`) durchläuft OAuth vollständig (DCR + Consent + Token „authentication successful"),
|
|
wird aber beim Reconnect abgelehnt („Got new credentials, but hivegrid-staging rejected them on reconnect").
|
|
Ursache: die DNS-Rebinding-Protection des MCP-SDK (`StreamableHTTPServerTransport`) lehnt bei konfigurierten
|
|
`allowedOrigins` jeden Request **ohne** `Origin`-Header ab (`Invalid Origin header: undefined`, SDK
|
|
`streamableHttp.js` Origin-Validierung). Native MCP-Clients (Claude Code/Desktop, Cursor, Inspector-CLI) senden
|
|
prinzipbedingt keinen Origin-Header → **kein benannter Produkt-Client konnte verbinden**; der Auth-Check läuft
|
|
vorher und war erfolgreich (deshalb wirkte es wie ein Token-Problem).
|
|
- **Fix (dieser Branch, `apps/mcp/src/transport.ts`):** `buildOriginAllowlist()` — die `allowedOrigins`-Allowlist wird
|
|
nur noch an das SDK durchgereicht, wenn der Request tatsächlich einen `Origin`-Header trägt (Browser-Kontext,
|
|
z.B. browser-basierter MCP Inspector); ohne Origin-Header entfällt nur der Origin-Check, der Host-Check
|
|
(`allowedHosts`) bleibt für jeden Request aktiv. DNS-Rebinding ist ein Browser-Angriff — für native Clients ohne
|
|
Origin ist die Prüfung gegenstandslos. Unit-Test `apps/mcp/src/transport.test.ts`. Proof lokal:
|
|
`pnpm --filter @hivegrid/mcp typecheck` + `test` (9 Tests) + `build` grün.
|
|
- **Rückbau der Client-Anbindung beim Testenden (falls gewünscht):** `claude mcp remove hivegrid-staging -s local`
|
|
entfernt Server + gespeicherte Credentials aus der lokalen Claude-Code-Config (nichts davon liegt im Repo);
|
|
Access-Tokens laufen nach 1h ab. Test-Leads aus `hg_lead_create` sind normale InboxLeads im Tenant und können
|
|
in der Lead-Inbox archiviert/gelöscht werden (z.B. `cmr57zk0f000001mptutf1qf8`, „E2E Proof").
|
|
- **Nach Merge/Deploy:** in Claude Code `/mcp` → `hivegrid-staging` → re-authenticate; danach sollten die 8
|
|
`hg_*`-Tools nutzbar sein → formaler DoD-Haken.
|
|
|
|
**2026-07-03 (Akeshan) — formaler Produkt-Client-Proof mit Claude Code (DoD-Haken gesetzt):**
|
|
- Nach Deploy des Origin-Fixes: Claude Code (`claude mcp add --transport http hivegrid-staging
|
|
https://staging-mcp.hivegrid.de`) verbindet per OAuth (Consent im Browser durch den User), alle 8 `hg_*`-Tools
|
|
verfügbar.
|
|
- **Read:** `hg_pipeline_list` → Sales-Pipeline mit 5 Stages (tenant-gescopt). **Write:** `hg_activity_add` mit
|
|
`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.
|
|
- 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).
|
|
|
|
**Früherer Proof lokal (MCP-Runtime vor OAuth-Nachzug):**
|
|
- `pnpm --filter @hivegrid/mcp build`
|
|
- `pnpm --filter @hivegrid/config test`
|
|
- `pnpm --filter @hivegrid/web test -- app/routes.test.ts app/modules/i18n/visible-shell-copy-i18n.test.ts app/utils/app/PublicRouteSegments.test.ts app/utils/app/HostRouting.server.test.ts`
|
|
- `pnpm typecheck`
|
|
- `pnpm run verify:env-drift`
|
|
- `pnpm run verify:deploy-readiness`
|
|
- `pnpm run verify:deploy-workflow`
|
|
- `pnpm run verify:docker-baseline`
|
|
- `docker build --target mcp --build-arg APP_REVISION=ci-smoke-revision -t hivegrid-mcp:smoke .`
|
|
- `bash scripts/docker-mcp-runtime-smoke.sh hivegrid-mcp:smoke`
|
|
|
|
## 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"
|