Containerize MCP tool services

2026-08-20 23:54:02 +02:00
parent 3ab9628088
commit f0d552ef58
28 changed files with 858 additions and 305 deletions
@@ -22,7 +22,11 @@ Heimnetz / VPN-Clients
        +-- llama-medium         > exakt einer aktiv
        +-- llama-long         --/
        +-- llama-experimental
-        +-- SearXNG + Web-MCP
+        +-- internes MCP-Netz
+             +-- Web-MCP + TinySearch + SearXNG
+             +-- Home-Assistant-MCP-Relay
+             +-- ARR-MCP
+             +-- Unraid-MCP
 ```

 ## Container und Vertrauensgrenzen
@@ -33,7 +37,8 @@ Heimnetz / VPN-Clients
 | Profile Router | nur WireGuard, Port 8081 | OpenAI-API und Profilwahl |
 | Profile Controller | nein | startet ausschließlich vier bekannte Profile |
 | llama.cpp Profile | nein | Inferenz, Tool Calling, integrierte Vision |
-| SearXNG | nein | Websuche für den lokalen Web-MCP |
+| MCP-Tool-Stack | nein | voneinander getrennte Werkzeugbereiche |
+| SearXNG/TinySearch | nein | Suchbackend des Web-MCP |

 Nur der Profile Controller erhält den Docker-Socket. Der Router erhält weder
 Socket noch Shell-Zugriff und kann dem Controller nur `fast`, `medium`, `long`
@@ -73,35 +78,36 @@ nicht automatisch in die Produktionsprofile aufgenommen.
  Internetzugang der KI über zuhause laufen, braucht der Heim-Peer zusätzlich
  IP-Forwarding und NAT ins Heim-WAN.

-## Nicht automatisch installiert
+## Optionale Erweiterungen

-Bildgenerierung, Whisper, TTS sowie Home-Assistant-, ARR- und Unraid-MCPs sind
-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.
+Bildgenerierung, Whisper und TTS benötigen eigene Modelle und bleiben im
+Basissystem deaktiviert. Home Assistant, ARR und Unraid sind vorbereitete
+MCP-Profile: Sie werden erst gestartet, wenn die jeweilige root-only
+Secret-Datei vorhanden ist. 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.
+Werkzeuge werden nicht in llama.cpp eingebaut. Sie laufen als eigene,
+zentrale MCP-Container. Open WebUI greift intern darauf zu. Für externe Clients
+wie Hermes wird später ein authentifizierter MCP-Gateway über WireGuard
+vorgeschaltet; die unauthentifizierten internen Ports werden niemals direkt
+veröffentlicht. So können alle Oberflächen dieselben geprüften Werkzeuge
+verwenden, ohne Secrets 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
+Open WebUI ── internes Netz ───────────┬── web-mcp
+                                       ├── home-assistant-mcp
+                                       ├── arr-mcp
+                                       └── unraid-mcp-read
+
+Hermes Agent ─ WireGuard ─┐
+weitere MCP-Clients ──────┴── mcp-gateway (später) ── dasselbe interne Netz
 ```

 | Container | Werkzeugbereich | Standardrecht |
@@ -5,17 +5,19 @@
 | AI Profile Router | `router/` | vollständig | Kern |
 | llama.cpp | ggml-org/llama.cpp, festgeschriebener Commit | Buildskript und Commit | Kern |
 | Qwen-Profile | `platform/profiles/` | vollständig, Modelle ausgenommen | Kern |
-| Websuche | TinySearch + SearXNG | Compose und sichere Grundkonfiguration | Kern |
-| Web-MCP-Fassade | `platform/web-search/web_search_mcp.py` | vollständig | Kern |
-| Home-Assistant-MCP | separates privates Repository | nur Integration dokumentiert | optional |
-| ARR-MCP | separates privates Repository | nur Integration dokumentiert | optional |
-| Unraid-MCP | separates Repository/Installation | read-only Integration dokumentiert | optional |
+| MCP-Tool-Stack | `platform/mcp/compose.yaml` | vollständig | Kern |
+| Websuche | TinySearch + SearXNG | intern, ohne veröffentlichten Port | Kern |
+| Web-MCP-Fassade | `platform/web-search/web_search_mcp.py` | eigener Container | Kern |
+| Home-Assistant-MCP | HA-Endpunkt plus lokaler Relay | eigener optionaler Container | optional |
+| ARR-MCP | `arr-mcp` 1.0.1 plus dokumentierter Sonarr-Patch | eigener optionaler Container | optional |
+| Unraid-MCP | lokales `runraid`-Binary | eigener optionaler Container | optional |
 | Whisper | ggml-org/whisper.cpp | Service im Router-Deploy | optional |
 | XTTS-v2 | Coqui | Worker, Service und Lockdatei | optional |
 | FLUX.2 klein | Black Forest Labs | Worker und Modellmanifest | optional |
 | LLama-GUI | separates Upstream-Projekt | nur Betriebsrolle dokumentiert | optional |
 | Glances | Distribution | nur Betriebsrolle dokumentiert | optional |

-Separate MCP-Repositories werden nicht in dieses Repository kopiert. Ihre
-Versionen sollen künftig in einem Release-Manifest referenziert werden. So
-bleiben Zuständigkeiten klar und Updates können unabhängig getestet werden.
+Upstream-Komponenten werden nicht ungeprüft einkopiert. Images, Python-Pakete
+und lokale Patches sind in Dockerfiles, Compose-Mounts und Dokumentation
+explizit benannt. So bleiben Zuständigkeiten klar und Updates können
+unabhängig getestet werden.
@@ -31,7 +31,7 @@ Zielplattform.
 | Hauptdienst | `mike-ai-llama-ui.service` |
 | llama.cpp-Port | 8080, auf dem alten Host noch im LAN gebunden |
 | Client-Port | 8081 über den Router |
-| MCP-Konfiguration | `/etc/mike-ai/mcp-servers.json` |
+| MCP-Konfiguration | getrennte Container unter `/opt/mike-ai/mcp-containers` |

 ### Aktives Fast-Profil

@@ -74,6 +74,33 @@ Zusätzlich prüfen: Uni-LAN sieht keine KI-Ports; Heimnetz erreicht beide;
 gestopptes WireGuard lässt KI-Container nicht ins Internet; jeder Profilwechsel
 startet exakt einen llama-Container; Text, Tool Call und Bild funktionieren.

+## Werkzeug-Container
+
+Der Installer startet Websuche automatisch in einem privaten Docker-Netz.
+Weitere Bereiche werden nur aktiviert, wenn ihre root-only Konfiguration schon
+vorhanden ist:
+
+```text
+/etc/mike-ai/homeassistant-admin-mcp.env
+/etc/mike-ai/arr-mcp.env
+/etc/mike-ai/runraid/.env
+/usr/local/bin/runraid                  Version 0.4.2
+```
+
+Nach dem Nachreichen einer Datei genügt:
+
+```bash
+sudo /opt/mike-ai/stack/platform/mcp/install-tools.sh
+```
+
+Auf einer frischen Open-WebUI-Datenbank werden die internen MCP-Adressen über
+`TOOL_SERVER_CONNECTIONS` vorbelegt. Bei einer übernommenen Datenbank müssen
+die Einträge einmal unter **Admin-Einstellungen → Externe Werkzeuge** geprüft
+oder importiert werden. Die Endpunkte stehen in `platform/mcp/README.md`.
+Kein MCP-Port wird auf dem Host veröffentlicht. Externe Clients wie Hermes
+benötigen später den authentifizierten WireGuard-Gateway und dürfen nicht
+direkt auf das interne Werkzeugnetz zugreifen.
+
 Die öffentliche Standardkonfiguration nutzt `UD-IQ4_XS`. Das bislang schnellste
 Referenzprofil nutzt dagegen die lokal vorhandene `IQ4-MIX`-Datei. Für eine
 bitgenaue Migration diese Datei anhand der in `CURRENT_REFERENCE.md`
@@ -36,17 +36,24 @@ Pflichtrollen:
 - FLUX.2 klein
 - XTTS-v2 und verwendete Stimme

-## 2. Externe Komponenten und Commits – offen
+## 2. Externe Komponenten und Commits – teilweise gesichert

-Für jedes separate Projekt benötigen wir Repository und Commit:
+Im Repository gesichert sind inzwischen:
+
+- getrennte MCP-Container und internes Netz
+- Web-MCP-Fassade sowie gepinnte TinySearch-/SearXNG-Images
+- ARR-MCP 1.0.1 und der aktuell eingesetzte kompakte Sonarr-Patch
+- Home-Assistant-Relay ohne eingebettetes Token
+- Startlogik und Health-Checks
+
+Noch extern zu beschaffen und exakt festzuhalten sind:

 - Home-Assistant-MCP
- ARR-MCP
- Unraid read-only MCP
+- `runraid` 0.4.2 für den read-only Unraid-MCP
 - gegebenenfalls eigener Unraid-Administrations-MCP
 - LLama-GUI, falls sie erhalten bleibt

-Jede Komponente bekommt zusätzlich:
+Jede noch externe Komponente bekommt zusätzlich:

 - Installationsbefehl
 - Systembenutzer
@@ -156,7 +163,7 @@ Festlegen, welche Daten persistent sein sollen:
 - Benchmarkresultate: eigenes Repository
 - Logs: ohne Prompt- und Tool-Antwortinhalte

-## 9. Ende-zu-Ende-Installer – implementiert, Hardware-Abnahme offen
+## 9. Ende-zu-Ende-Installer – weitgehend implementiert, Praxistest offen

 Der Ablauf ist jetzt in `install.sh` zusammengeführt:

@@ -170,6 +177,11 @@ enable-selected-mcp-profiles
 run-acceptance-tests
 ```

+`platform/mcp/install-tools.sh` installiert den Webbereich automatisch und
+aktiviert HA, ARR und Unraid nur bei vorhandenen Secret-/Programmdateien. Offen
+bleiben ein kompletter Leerhost-Probelauf und der automatisierte Import einer
+bereits bestehenden Open-WebUI-Datenbank.
+
 Jeder Schritt muss wiederholbar, einzeln prüfbar und bei Fehlern abbrechbar
 sein. Ein fehlgeschlagener Schritt darf keinen halb aktivierten Dienst
 hinterlassen.
@@ -21,7 +21,13 @@ verlässt sich nicht allein auf UFW.
 - Profile Controller: einzige Socket-Ausnahme; feste Profile und nur
  List/Start/Stop, keine frei wählbaren Images, Befehle oder Mounts.
 - Open WebUI: einziges persistentes Chat-Volume.
- SearXNG: intern, Suchanfragen ohne Chatverlauf.
+- MCP-Fachcontainer: intern, getrennte Secrets und keine Host-Ports.
+- TinySearch/SearXNG: intern, Suchanfragen ohne Chatverlauf.
+
+llama.cpp bekommt weder MCP-Konfiguration noch HA-, ARR- oder Unraid-Secrets.
+Open WebUI kennt nur interne MCP-URLs; Authentisierung zu den Zielsystemen
+findet im jeweiligen Fachcontainer statt. Externe MCP-Clients werden erst über
+einen authentifizierten WireGuard-Gateway zugelassen.

 Ein Docker-Socket bleibt grundsätzlich privilegiert. Der Controller reduziert
 die erreichbare Funktion stark, ersetzt aber keine zusätzliche Socket-Proxy-