Containerize MCP tool services

platform/mcp/README.md

@@ -1,43 +1,74 @@
-# MCP-Architektur
+# Zentrale MCP-Werkzeugebene
 
-Die produktive MCP-Konfiguration ist absichtlich nicht Bestandteil des Git-
-Repositories, weil sie lokale Pfade und Zugangsdaten referenziert. Das Beispiel
-zeigt nur die Struktur.
+MCP-Werkzeuge sind **keine llama.cpp-Startparameter**. Sie laufen als kleine,
+voneinander getrennte Container und werden von OpenWebUI, Hermes oder einem
+anderen MCP-Client gezielt ausgewählt. Das hält Tool-Schemas aus normalen
+Prompts heraus, verhindert den früher beobachteten Kontextverbrauch von über
+200.000 Tokens und macht Werkzeuge unabhängig vom geladenen Modellprofil.
 
-## Empfohlene Server
+## Container
 
-- `web`: Websuche über lokales TinySearch/SearXNG
-- `homeassistant`: Administration mit eigenem, minimal berechtigtem Token
-- `arr`: Sonarr/Radarr über spezialisierte Aktionen
-- `unraid-readonly`: Diagnose ohne Schreiboperationen
+| Container | Endpunkt im Netz `mike-ai-tools` | Zweck | Standard |
+|---|---|---|---|
+| `mcp-web` | `http://mike-ai-mcp-web:8000/mcp` | kompakte Websuche und Quellenvergleich | an |
+| `mcp-homeassistant` | `http://mike-ai-mcp-homeassistant:8000/mcp` | Relay zum nativen HA-MCP; Token bleibt serverseitig | Profil `homeassistant` |
+| `mcp-arr` | `http://mike-ai-mcp-arr:8000/mcp` | Sonarr/Radarr/Prowlarr mit serverseitiger Policy | Profil `arr` |
+| `mcp-unraid-official` | `http://mike-ai-mcp-unraid-official:8000/mcp` | offizieller, read-only begrenzter Unraid-Zugang | Profil `unraid` |
+| `mcp-unraid-ssh` | `http://mike-ai-mcp-unraid-ssh:8000/mcp` | erweiterte Diagnose über einen erzwungenen SSH-Befehl | optional (`extended`) |
 
-## Getrennte Konfigurationen
+TinySearch und SearXNG sind interne Abhängigkeiten des Web-MCPs und werden
+nicht direkt als allgemeine Werkzeuge angeboten.
 
-Statt alle Werkzeuge ständig zu laden, werden mehrere Dateien empfohlen:
+## Sicherheitsmodell
 
-```text
-/etc/mike-ai/mcp-standard.json
-/etc/mike-ai/mcp-homeassistant.json
-/etc/mike-ai/mcp-arr.json
-/etc/mike-ai/mcp-unraid-readonly.json
-/etc/mike-ai/mcp-unraid-write.json
+- Kein MCP-Port wird auf eine Host-Adresse veröffentlicht.
+- Nur Clients im privaten Docker-Netz `mike-ai-tools` erreichen die Endpunkte.
+- Secrets bleiben in Dateien unter `/etc/mike-ai` und werden read-only
+  eingehängt. Sie gehören weder in Git noch in OpenWebUI-Tooldefinitionen.
+- Jeder Container ist read-only, verliert Linux-Capabilities und hat
+  `no-new-privileges`.
+- Der SSH-basierte Unraid-Container ist nicht Teil des Standardstarts.
+- Ein allgemeiner Host-Shell-MCP wird bewusst nicht angeboten.
+
+## Start
+
+```bash
+sudo platform/mcp/install-tools.sh
 ```
 
-Das jeweilige Profil verweist nur auf die benötigte Datei. Dadurch werden die
-Tool-Schemas kleiner, das Kontextfenster bleibt frei und kleine Modelle müssen
-weniger Werkzeuge unterscheiden.
+Der Grundstart enthält nur Websuche. Bereits konfigurierte Fachbereiche werden
+explizit ergänzt:
 
-Credentials werden von schmalen Wrapper-Programmen wie `run-arr-mcp` oder
-`runraid` aus geschützten Environment-Dateien geladen. Das JSON selbst enthält
-weder Werte noch Pfade zu einzelnen Tokens.
+Das Skript erkennt vorhandene Secret-Dateien und aktiviert dadurch automatisch
+`homeassistant`, `arr` und `unraid`. Ohne Fach-Secrets startet nur der sichere
+Webbereich.
 
-## Schreibzugriff
+Für den derzeit migrierten Container kann der Name `Open-WebUI` lauten. Der
+Netzwerkbefehl ist idempotent zu behandeln.
 
-Schreibende Server gehören nicht in `mcp-standard.json`. Sie benötigen eine
-Vorschau und ein an die exakte Änderung gebundenes Approval Ticket.
+Die lokale Installation benötigt die vorhandenen Secret-Dateien:
 
-## Shell
+```text
+/etc/mike-ai/homeassistant-admin-mcp.env
+/etc/mike-ai/arr-mcp.env
+/etc/mike-ai/runraid/.env
+```
 
-Ein allgemeiner Shell-MCP ist nicht Teil der Zielplattform. Insbesondere
-`python3`, `ssh`, `scp`, `curl` und `systemctl` dürfen nicht gemeinsam als
-scheinbar harmlose Allowlist angeboten werden.
+Die erweiterte Unraid-Diagnose benötigt zusätzlich die Konfigurationsdatei,
+den eingeschränkten Schlüssel und die bekannte Hostsignatur. Sie wird nur mit
+`--profile extended` gestartet.
+
+TinySearch speichert sein lokales Embedding-Modell in einem Docker-Volume.
+Nach einer Erstinstallation wird das Modell einmalig im Container mit
+`tinysearch setup` geladen. Das Volume bleibt bei Containerupdates erhalten.
+
+## Client-Auswahl
+
+Werkzeuge werden nicht pauschal an jedes Modell gehängt. Für Home-Assistant-
+Fragen wird HA ausgewählt, für Medien ARR, für Recherche Web und für die NAS
+Unraid. Mehrere Werkzeuge werden nur aktiviert, wenn die Aufgabe tatsächlich
+mehrere Bereiche verbindet.
+
+Schreibende Aktionen bleiben hinter der jeweiligen serverseitigen Policy und
+einem Vorschau-/Bestätigungsablauf. Ein Client-Schalter allein darf niemals
+eine read-only Policy aufheben.