Document centralized isolated MCP tool plane

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

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.

docs/NEW_HOST_ROADMAP.md

@@ -29,9 +29,15 @@
 
 ## Phase 4 – optionale Fähigkeiten
 
-- Home-Assistant-MCP mit kleinsten Rechten.
+- Zentrale MCP-Werkzeugebene gemäß `ARCHITECTURE.md` aufbauen.
-- ARR-MCP zunächst read-only, Schreibaktionen mit Preview/Approval.
+- Schlanken `mcp-gateway` nur über WireGuard veröffentlichen.
-- Unraid-/Docker-Zugriff über begrenzte Broker statt Shell-MCP.
+- `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