# Zentrale MCP-Werkzeugebene 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. ## Container | Container | Endpunkt im Netz `mike-ai-tools` | Zweck | Standard | |---|---|---|---| | `mcp-platform-context` | `http://mike-ai-mcp-platform-context:8000/mcp` | Athena-Wissen, begrenzter Snapshot und kontrollierte Docs-Pflege | an | | `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-navidrome` | `http://mike-ai-mcp-navidrome:3000/mcp` | Navidrome-Bibliothek, Suche, Playlists, Favoriten und Hörverlauf | Profil `navidrome` | | `mcp-github` | `http://mike-ai-mcp-github:8000/mcp` | offizieller GitHub-MCP, auf vier reine Repository-Lesewerkzeuge begrenzt | Profil `github` | | `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`) | Die drei Websuch-Container verwenden `AI_DNS` aus `/etc/mike-ai/stack.env`. Der Web-MCP hängt zusätzlich am getrennten `mike-ai-tools-egress`-Netz, weil er gefundene öffentliche Seiten nach der SSRF-Prüfung selbst abrufen muss. Ohne diese beiden Einstellungen kann die Werkzeugauswahl korrekt wirken, während alle Suchmaschinen und Seitenabrufe gleichzeitig fehlschlagen. Der Platform Context MCP hat keinen Docker-Socket, keine Shell, keinen Egress und keine Secrets. Sein aktueller Zustand stammt aus einem fest programmierten Host-Snapshot. Dokumentationspflege ist auf `docs/*.md` und einen zweistufigen Preview/Approval-Ablauf begrenzt. Vollständige Beschreibung: [`docs/PLATFORM_CONTEXT_MCP.md`](../../docs/PLATFORM_CONTEXT_MCP.md). TinySearch bleibt als Ganzes read-only. Nur das flüchtige tmpfs-Verzeichnis `/home/tinysearch/.crawl4ai` ist beschreibbar, weil Crawl4AI dort seinen temporären Browser- und Sitzungszustand erzeugt. Es wird bei jedem Container-Neustart vollständig verworfen. TinySearch und SearXNG sind interne Abhängigkeiten des Web-MCPs und werden nicht direkt als allgemeine Werkzeuge angeboten. Die fünf Open-WebUI-Profile Fast, Medium, Large, Ultra und Uncensored binden den Server als `server:mcp:web-local` standardmäßig ein. Damit steht die begrenzte lokale Websuche in jedem neuen Chat zur Verfügung, ohne zusätzlich Open WebUIs separate eingebaute Websuche zu aktivieren. Das Modell entscheidet weiterhin, ob eine aktuelle Frage tatsächlich einen Werkzeugaufruf benötigt. Ein gemeinsamer Systemhinweis der fünf Profile verlangt Webprüfung bei aktuellen, veränderlichen oder wesentlich unsicheren Tatsachen. Stabiles Allgemeinwissen soll ohne unnötige Suche beantwortet werden. Die Anweisung fordert gezielte statt wiederholter Synonymsuchen, Quellenlinks, transparente Unsicherheit und behandelt Webseiteninhalte grundsätzlich als nicht vertrauenswürdige Daten statt als Anweisungen. ## Entscheidungshilfe für das Modell Die Server- und Werkzeugbeschreibungen grenzen die Zuständigkeiten absichtlich deutlich voneinander ab. Das Modell soll pro Aufgabe zunächst genau **einen** passenden Server wählen: | Aufgabe | Werkzeugserver | Nicht zusätzlich verwenden | |---|---|---| | Aktuelle öffentliche Informationen, Quellen, Hugging Face, Produkte | Web | HA, ARR, Unraid | | GitHub-Repository finden, Baum/README/Quellcode/API-Routen lesen | GitHub Repository | Web, HA, ARR | | Entitäten, Zustände, Historie, Automationen und Dashboards | Home Assistant | Web, Unraid | | Serien, Filme, fehlende Episoden und Indexer-Releases | Sonarr und Radarr | Web | | Persönliche Musikbibliothek, Titel, Alben, Künstler und Playlists | Navidrome | Web, ARR | | Lesende NAS-, Docker-, Array-, Netzwerk- und Logdiagnose | Unraid (Systemdiagnose) | MUA | | Ausdrücklich benötigte MUA-Verwaltungsaktion | MUA | Unraid-Diagnose nicht parallel | Ein leeres Ergebnis ist kein Grund, dieselbe Frage über mehrere unpassende Werkzeuge oder leicht veränderte Suchbegriffe erneut auszuführen. Das Modell soll die Grenze transparent nennen und gezielt nachfragen, wenn eine Freigabe oder ein anderes Werkzeug benötigt wird. ## Sicherheitsmodell - 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 ``` Der Grundstart enthält nur Websuche. Bereits konfigurierte Fachbereiche werden explizit ergänzt: Das Skript erkennt vorhandene Secret-Dateien und aktiviert dadurch automatisch `homeassistant`, `arr` und `unraid`. Ohne Fach-Secrets startet nur der sichere Webbereich. Für den derzeit migrierten Container kann der Name `Open-WebUI` lauten. Der Netzwerkbefehl ist idempotent zu behandeln. Die lokale Installation benötigt die vorhandenen Secret-Dateien: ```text /etc/mike-ai/homeassistant-admin-mcp.env /etc/mike-ai/arr-mcp.env /etc/mike-ai/navidrome-mcp.env /etc/mike-ai/github-mcp.env /etc/mike-ai/runraid/.env ``` 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. ## Navidrome Der Navidrome-MCP basiert auf `Blakeem/Navidrome-MCP` 2.2.0; das amd64-Image ist per OCI-Digest festgeschrieben. Ein kleiner Build-Patch ergänzt bei zwei Internetradio-URL-Schemas das von llama.cpp verlangte abschließende `$`; Verhalten und API-Aufrufe bleiben unverändert. Der Container veröffentlicht keinen Host-Port, besitzt keinen Dateizugriff auf die Musikbibliothek und enthält bewusst kein `mpv`. Er kann daher nicht auf Athena selbst Musik wiedergeben. Navidrome sollte einen eigenen normalen Benutzer `mcp` erhalten. Dessen Zugangsdaten liegen ausschließlich in der root-only Datei `/etc/mike-ai/navidrome-mcp.env`; die Vorlage steht unter `config/navidrome-mcp.env.example`. Anschließend genügt: ```bash sudo install -m 0600 config/navidrome-mcp.env.example /etc/mike-ai/navidrome-mcp.env sudoedit /etc/mike-ai/navidrome-mcp.env sudo platform/mcp/install-tools.sh sudo platform/openwebui/install-filters.sh ``` Der Upstream-Server stellt ohne Playback noch immer über 40 Werkzeuge bereit. Darum wird Navidrome **nicht** als Standardwerkzeug an jedes Modellprofil gehängt. Es wird in OpenWebUI nur für konkrete Musikaufgaben ausgewählt und danach wieder ausgeschaltet. Schreibende Funktionen wie Playlist-Änderungen, Favoriten und Bewertungen wirken unmittelbar im Konto des MCP-Benutzers. Optional aktiviert `LASTFM_API_KEY` in derselben Secret-Datei sieben öffentliche Empfehlungswerkzeuge für ähnliche Künstler/Titel, Trends und ergänzende Metadaten. Das Last.fm Shared Secret ist dafür nicht erforderlich und wird nicht gespeichert. Die Integration greift damit weder auf das persönliche Last.fm-Profil noch auf dessen Hörverlauf zu. ## GitHub Der GitHub-Container verwendet unverändert den offiziellen `github/github-mcp-server` 1.10.1. Da dessen lokaler Container stdio spricht, wandelt `mcp-proxy` 0.12.0 ausschließlich den Transport in Streamable HTTP für Open WebUI und weitere interne Clients um. Basisimage und GitHub-Image sind per OCI-Digest festgeschrieben; die Brücke implementiert keine GitHub-Operationen. `mcp-proxy` läuft bewusst **stateless**. Die zuerst getestete Supergateway- Brücke war mit Open WebUIs Python-MCP-Client nicht zuverlässig kompatibel: Im stateful Betrieb konnten Sitzungen ablaufen; im stateless Betrieb beantwortete sie die reguläre `notifications/initialized`-Nachricht mit HTTP 400. Beides führte trotz gesundem GitHub-Server und gültigem Token zu `Failed to connect to MCP server 'github-local'`. Der jetzt verwendete Proxy ist derselbe Transport, der sich bereits beim Athena Platform Context MCP bewährt hat. Dem Modell werden ausschließlich `search_repositories`, `get_repository_tree`, `get_file_contents` und `search_code` angeboten. Der offizielle Server wird zusätzlich explizit mit `--read-only` gestartet; die Umgebungsvariablen im Compose-Stack bleiben als zweite, deklarative Sicherung erhalten. Damit sind Schreiboperationen auch serverseitig ausgeschlossen. Der Container veröffentlicht keinen Host-Port und speichert den Token nicht in Open WebUI. Einrichtung: ```bash sudo install -m 0600 config/github-mcp.env.example /etc/mike-ai/github-mcp.env sudoedit /etc/mike-ai/github-mcp.env sudo platform/mcp/install-tools.sh sudo platform/openwebui/install-filters.sh ``` Der Token muss eigens für Athena erzeugt werden und ausschließlich lesenden Zugriff auf die tatsächlich benötigten Repositories erhalten. Die vier begrenzten Werkzeuge werden bei vorhandener Secret-Datei an die fünf MikeAI-Profile geheftet. Dadurch kann das Modell Repositoryfragen selbständig prüfen, ohne den großen GitHub-Standardwerkzeugkatalog in den Kontext zu laden. ## Client-Auswahl Große Fachwerkzeuge werden nicht pauschal an jedes Modell gehängt. Nur die kompakte Websuche und die vier GitHub-Lesewerkzeuge sind allgemein verfügbar. Für Home-Assistant-Fragen wird HA ausgewählt, für Medien ARR und für die NAS Unraid. Weitere 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. ## Home Assistant: abgesicherter YAML-Zugang Die Referenzinstallation überlagert im nativen `czechbol/hass-mcp` das Werkzeug `ha_yaml_config` mit `patches/hass_mcp/yaml_config.py`. Es erlaubt strukturierte Zugriffe nur auf `automations.yaml`, `scripts.yaml` und `scenes.yaml`. Für auskommentierte Blöcke stehen begrenztes `read_source` und `find_source` zur Verfügung; `configuration.yaml` darf dabei ebenfalls gelesen werden. Beliebige Pfade und `secrets.yaml` sind konstruktiv ausgeschlossen. Verdächtige Inline-Zugangsdaten und selbst Namen von `!secret`-Referenzen werden in Rohtextantworten maskiert. Jede Änderung arbeitet zweistufig: Vorschau mit einmaligem Ticket, anschließend derselbe unveränderte Aufruf mit `confirm=true` nach ausdrücklicher Zustimmung. Vor dem atomaren Schreiben wird eine lokale Sicherung erzeugt. Danach läuft die vollständige Home-Assistant-Konfigurationsprüfung; bei Fehlern oder gescheitertem Reload wird automatisch zurückgerollt. `configuration.yaml` wird nicht live neu geladen und meldet deshalb nach einer erfolgreichen Änderung `restart_required=true`. Installation auf dem Host, der das Home-Assistant-Konfigurationsverzeichnis besitzt: ```bash sudo platform/mcp/install-hass-mcp-yaml-guard.sh \ /mnt/user/appdata/HomeAssistant/config ``` Danach Home Assistant kontrolliert neu starten und den Werkzeugkatalog prüfen. Der Installer aktiviert **nicht** pauschal Schreibrechte: In Home Assistant unter **Einstellungen → Geräte & Dienste → Native MCP for Home Assistant → Konfigurieren** muss `Allow write tools` bewusst eingeschaltet werden. Das gibt auch anderen nicht-destruktiven Schreibwerkzeugen dieser Integration Zugriff und sollte daher nur zusammen mit sichtbarer Tool-Freigabe im Client aktiviert werden. ## Sonarr: sichere Episodensuche Der lokale Sonarr-Patch stellt bewusst keine freie Sonarr-Command-API bereit. Der erlaubte Schreibablauf ist eng auf fehlende Episoden begrenzt: 1. `preview_episode_search` bekommt Serien-ID, Staffel und die exakten Episodennummern. Es liest Sonarr-Metadaten, entfernt bereits vorhandene Episoden und erzeugt eine konkrete Vorschau samt kurzlebigem Ticket. 2. Der Client zeigt diese Vorschau unverändert an. Ohne ausdrückliche Benutzerfreigabe endet der Ablauf hier. 3. `start_episode_search` akzeptiert nur denselben Umfang, `confirm=true` und das passende Ticket. Erst dann startet Sonarr eine `EpisodeSearch` über die dort konfigurierten Indexer. `EpisodeSearch` ist keine bloße Ergebnisvorschau: Sonarr kann dabei sofort das beste akzeptierte Release pro Episode an den Download-Client übergeben. Das gilt auch für explizit ausgewählte, momentan nicht überwachte Episoden; Monitoring steuert vor allem die spätere automatische/RSS-Verarbeitung. Der Ablauf ändert weder Serien- noch Staffel-Monitoring und erlaubt weder beliebige Commands noch direkte URL-Downloads. Tickets gelten zehn Minuten, sind einmalig und an genau die angezeigte Auswahl gebunden. ### Sonarr: ein konkretes Release oder Staffelpaket laden Eine automatische Episodensuche ist **kein Ersatz** für die Auswahl eines bestimmten Releases. Wenn ein Benutzer etwa ausdrücklich ein FuN-Staffelpaket verlangt, gilt stattdessen dieser Ablauf: 1. `search_releases` sucht ausschließlich über Sonarrs konfigurierte Indexer. Für Gruppen- oder Staffelpaketfragen werden `release_group` und `season_pack_only=true` direkt gesetzt; vorhandene Bibliotheksdateien sind kein Beleg dafür, was aktuell auf den Indexern verfügbar ist. 2. `preview_release_grab` bekommt Serien-ID, Staffel und die **exakte GUID** des ausgewählten Suchergebnisses. Sonarr wird erneut abgefragt; Titel, Größe, Indexer, Ablehnungsgründe und vorhandene Episodendateien werden angezeigt. 3. Erst nach ausdrücklicher Freigabe darf `grab_release` mit demselben Umfang, `confirm=true` und dem kurzlebigen Ticket aufgerufen werden. Es übergibt exakt dieses Release an Sonarrs konfigurierten Download-Client. Hat Sonarr das Release abgelehnt oder `downloadAllowed=false` gemeldet, muss bereits die Vorschau nach gesonderter Zustimmung `force=true` enthalten. Das Ticket ist auch daran gebunden. Der MCP löscht keine vorhandenen Dateien und verspricht keine Überschreibung: Ob eine vorhandene Episode nach dem Download ersetzt wird, entscheiden Sonarrs Qualitätsprofil-, Upgrade- und Importregeln.