diff --git a/README.md b/README.md index 04fd9ba..0316b12 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ WireGuard-Isolation. - `/fast`, `/medium`, `/long` und `/experimental` über den Profile Router - Open WebUI als einzige normale Oberfläche - SearXNG/Web-MCP ohne externen API-Schlüssel +- zentrale MCP-Werkzeugebene: getrennte Container für Web, HA, ARR, Unraid + und Sandbox, gemeinsam nutzbar durch Open WebUI und andere Clients - KI-Dienste ausschließlich über die WireGuard-Adresse erreichbar - KI-Ausgangsverkehr über das Heimnetz, bei Tunnelausfall fail-closed - keine Secrets, Chats, Logs oder Modelldateien im Repository diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6054030..45de60d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -80,3 +80,51 @@ Erweiterungen. Sie benötigen eigene Modelle, Rechte oder Secrets und bleiben im sauberen Basissystem deaktiviert. Multimodale Bildanalyse erfolgt direkt über Qwen plus Projektor. Nicht installierte Worker-Endpunkte antworten klar mit `feature_disabled`, statt alte systemd-Pfade aufzurufen. + +## Zentrale MCP-Werkzeugebene + +Werkzeuge werden nicht fest in Open WebUI, Hermes oder einen anderen Client +eingebaut. Sie laufen als zentrale, über WireGuard erreichbare MCP-Server. Alle +MCP-fähigen Oberflächen verwenden dadurch dieselben geprüften Werkzeuge, ohne +Secrets oder Installationen zu duplizieren. + +Die Trenneinheit ist **ein Container pro Fachbereich und Vertrauensstufe** – +nicht ein Container pro einzelner Funktion und nicht ein gemeinsamer +Allzweck-MCP mit sämtlichen Zugangsdaten. + +```text +Open WebUI ──┐ +Hermes Agent ├── mcp-gateway ──┬── web-mcp +weitere MCP- ┘ ├── home-assistant-mcp-read +Clients ├── home-assistant-mcp-write + ├── arr-mcp-read + ├── arr-mcp-write + ├── unraid-mcp-read + ├── unraid-mcp-admin + └── sandbox-mcp +``` + +| Container | Werkzeugbereich | Standardrecht | +|---|---|---| +| `web-mcp` | Websuche, Seitenabruf, GitHub/Hugging Face | nur lesen | +| `home-assistant-mcp-read` | Entities, Bereiche, Historie, Diagnose | nur lesen | +| `home-assistant-mcp-write` | kontrollierte HA-Änderungen | Preview/Approval | +| `arr-mcp-read` | Sonarr/Radarr-Status und Releasesuche | nur lesen | +| `arr-mcp-write` | Suche, Monitoring und Downloadtrigger | Preview/Approval | +| `unraid-mcp-read` | System-, Container- und begrenzte Logdiagnose | nur lesen | +| `unraid-mcp-admin` | eng definierte Verwaltungsaktionen | bewusst aktivieren | +| `sandbox-mcp` | temporäre Code- und Dateiarbeit | isolierter Arbeitsraum | +| `mcp-gateway` | Auth, Routing, Limits und Werkzeugauswahl | keine Fach-Secrets | + +Read- und Write-Instanzen dürfen dasselbe Image verwenden, laufen aber mit +unterschiedlichen Tokens, Netzwerkzugriffen und Werkzeug-Allowlisten. Der +Gateway besitzt keine HA-, ARR- oder Unraid-Secrets. Er authentifiziert Clients, +routet zum zuständigen MCP und begrenzt Antwortgröße, Laufzeit und Aufrufrate. + +Eine allgemeine Host-Shell ist ausdrücklich ausgeschlossen. `sandbox-mcp` +läuft ohne Docker-Socket, ohne Infrastruktur-Secrets und nur mit einem +begrenzten Arbeitsverzeichnis. Administrative Aktionen werden als feste, +prüfbare Werkzeuge mit Vorschau und Freigabe modelliert. + +Clients aktivieren nur die für den aktuellen Chat benötigte Werkzeuggruppe. +Das reduziert Tool-Schemas, Kontextverbrauch und Fehlaufrufe kleiner Modelle. diff --git a/docs/NEW_HOST_ROADMAP.md b/docs/NEW_HOST_ROADMAP.md index c0632ae..9dc5237 100644 --- a/docs/NEW_HOST_ROADMAP.md +++ b/docs/NEW_HOST_ROADMAP.md @@ -29,9 +29,15 @@ ## Phase 4 – optionale Fähigkeiten -- Home-Assistant-MCP mit kleinsten Rechten. -- ARR-MCP zunächst read-only, Schreibaktionen mit Preview/Approval. -- Unraid-/Docker-Zugriff über begrenzte Broker statt Shell-MCP. +- Zentrale MCP-Werkzeugebene gemäß `ARCHITECTURE.md` aufbauen. +- Schlanken `mcp-gateway` nur über WireGuard veröffentlichen. +- `web-mcp` als unabhängigen Standard-Werkzeugcontainer betreiben. +- Home Assistant als getrennte Read-/Write-Instanzen desselben Images. +- ARR als getrennte Read-/Write-Instanzen mit Preview/Approval. +- Unraid-Diagnose und bewusst aktivierbare Administration trennen. +- Terminal ausschließlich als isolierten `sandbox-mcp`, nie als Host-Shell. +- Open WebUI, Hermes und weitere Clients mit denselben zentralen Endpunkten + verbinden und pro Chat nur benötigte Werkzeuggruppen aktivieren. - Whisper, TTS oder Bildgenerierung jeweils als eigener Container. ## Phase 5 – Betrieb