Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VD-MCP.md
T

4.9 KiB
Raw Blame History

VD-MCP · Screens MCP-Server (Verbindungen/Settings)

Typ Screen (Design)
Owner David
Phase v2-P4 — MCP (bedient VR-MCP, AD-26)
Cycle/Fenster v2-W1 — Public-API/Postfach/Abo/KI-Start · Start 16.–20.07. · fällig 2026-07-20
Status geplant (NEU — KI→MCP-Pivot)

Entscheidung / Kontext (AD-26)

KI→MCP-Pivot: keine HiveMind/RAG-UI. HiveGrid wird MCP-Server, an den externe KI-Clients andocken. Dieses Screen-Ticket liefert die Verwaltungs-UI dafür. Ersetzt VD-P25 (zurückgestellt).

Host-/Connector-Contract

  • Connector-URL in der UI ist https://mcp.hivegrid.de (staging: https://staging-mcp.hivegrid.de).
  • MCP ist ein eigener Service/Container hivegrid-mcp, nicht Teil von app.hivegrid.de oder api.hivegrid.de.
  • OAuth-/Scope-Verwaltung nutzt die Public-API-Key-/Scope-Mechanik aus VR-P22b als Backend-Grundlage, aber der primäre Nutzerflow ist OAuth Connect statt API-Key-Copy. Die UI muss klar zwischen API-Verbindungen (api.hivegrid.de) und MCP-Verbindungen (mcp.hivegrid.de) unterscheiden.

Benötigte Screens (A6 Settings-Archetyp)

  • MCP-Verbindungen / Settings:
    • OAuth-Connect-Flow: Client auswählen (Claude/ChatGPT/Cursor/VS Code/manuell) → Berechtigungen wählen → HiveGrid-Consent → erfolgreich verbunden; API-Key-Copy nur als Advanced-/Fallback-Modus
    • Scope-Auswahl: Presets „Nur lesen", „Lesen + schreiben", „Erweitert" (read/write je Domäne: Leads/Kontakte/Projekte/Pipeline/Aktivitäten/Aufgaben)
    • Aktive Verbindungen: Liste (Client/Bezeichnung, vergebene Scopes, letzte Nutzung), einzeln trennbar
    • Setup-Anleitung: Connector-URL https://mcp.hivegrid.de, OAuth-fähige Client-Schritte, Copy-Buttons nur für Clients ohne automatische Discovery/Connect-Unterstützung
    • MCP-Audit: Verlauf der Tool-Aufrufe (wer/welcher Client, welches Tool, wann, Read/Write) — Lesezugriff auf den M001-Audit-Trail, gefiltert auf MCP-Actor
    • Hinweis zur Reihenfolge: Screens finalisieren erst nach funktionalem OAuth-Proof aus VR-MCP; bis dahin ist dieser Screen-Scope ein Design-Zielbild.

Backend-Vertrag seit 2026-07-12: 15 Tools; neue granulare Scopes sind mcp:activity:read, mcp:task:read und mcp:task:write. mcp:read/mcp:write bleiben die Preset-Bündel. Die erweiterte Auswahl muss diese Scopes benennen, ohne die technischen Scope-Strings als primäre UX-Texte zu zeigen.

Definition of Done

  • Connection-Settings-Screen (Subframe-Pflicht, A6) — Sidebar-Eintrag + Permission-Gate
  • OAuth-Connect-Flow (Client-Auswahl → Consent → Success/Error) + Scope-Auswahl; API-Key-Fallback als Advanced-Modus
  • Aktive-Verbindungen-Liste + MCP-Audit-Ansicht
  • Setup-Anleitung + Empty-State/Loading-State mit Klartext; i18n-Keys für alle Texte

Abhängigkeiten

  • blocked-by: D-D0a (App-Shell), D-D0b (Archetyp A6 Settings)
  • bedient (Dev): VR-MCP
  • Ersetzt: VD-P25 (zurückgestellt)

Quellen

  • AD-26 (KI→MCP-Pivot) · VR-MCP (Backend-Gegenstück)

Umsetzungs-Notiz

2026-07-28 — Topbar-Einstieg „Connect MCP" + Setup-Dialog (Interim-UI nach AD-28, ticketunabhängig gebaut). Nicht der volle A6-Settings-Screen, sondern der Einstiegspunkt davor: eine Box links neben der globalen Suche (Claude-, ChatGPT- und Copilot-Marke + Label), die einen Dialog nach dem Vorbild von Subframes „Connect to code" öffnet. Inhalt: Connector-URL mit Copy-Button, acht aufklappbare Anleitungen (Claude Code, Claude Desktop/claude.ai, ChatGPT, GitHub Copilot, Codex CLI, Gemini CLI, Cursor/Editoren, manuell) und die eigenen aktiven Verbindungen mit Trennen-Aktion.

  • Erledigt aus der DoD: Setup-Anleitung, Empty-/Loading-/Error-State mit Klartext, i18n-Keys (de+en), Aktive-Verbindungen-Liste inkl. Widerruf, Permission-/Entitlement-Gate (featureKeys.mcp, sonst kein Eintrag).
  • Offen: eigener Settings-Screen mit Sidebar-Eintrag, Scope-Auswahl-Presets, MCP-Audit-Ansicht. → 2/4 DoD-Punkte = ~50 % done.
  • Connector-URL und alle Befehle werden aus MCP_RESOURCE_URL abgeleitet, der Servername im Client-Befehl aus dem Produktnamen; Staging zeigt damit automatisch staging-mcp.….
  • Backend-Nachzug in VR-MCP: resolveAuthorizeTenant nimmt jetzt den aktiven Mandanten (User.defaultTenantId) statt der ersten Mitgliedschaft — Clients senden nie einen tenant-Parameter.
  • Vor dem Prod-Release beachten: der MCP-Prod-Promote auf mcp.hivegrid.de steht laut VR-MCP noch aus. featureKeys.mcp ist blueprint-default aktiv, der Einstieg wäre auf Prod also sichtbar, bevor der Host antwortet. Entweder Promote zuerst oder Launcher hinter einen M006-Feature-Flag hängen (nicht gebaut).
  • Proof: pnpm typecheck, pnpm lint, pnpm test grün; verify:i18n, verify:source-health grün; Interim-Baseline als Playwright-Component-Test tests/component/vd-mcp-connect-interim.ct.tsx.