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

77 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.