AI-Profile-Router/platform/mcp/README.md

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-athena-operator	http://mike-ai-mcp-athena-operator:8000/mcp	vollständiger Betrieb plus breites begrenztes Terminal	an
tinysearch	http://tinysearch:8000/mcp	allgemeine portable Websuche und Seitenabruf	an
mcp-web	http://mike-ai-mcp-web:8000/mcp	frühere spezialisierte Web-Fassade	nur Profil legacy-web
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 drei kleine Repository-Lesewerkzeuge begrenzt	Profil github
mcp-unraid-ssh	http://mike-ai-mcp-unraid-ssh:8000/mcp	erweiterte Diagnose über einen erzwungenen SSH-Befehl	optional (extended)

Unraid wird produktiv ausschließlich über das auf dem HomeServer laufende MUA-Plugin (http://192.168.1.2:3002/mcp) angebunden. Open WebUI führt davon zwei Ansichten: mua-readonly-local für automatische Diagnose und mua für bewusst aktivierte Verwaltungsaktionen. Ein GraphQL-basierter Unraid-MCP ist nicht Bestandteil des Stacks.

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.

Der Athena Operator MCP ist die einzige Bedienebene für Arbeiten an der lokalen KI-Plattform. Qwen kann damit Quellen lesen, strukturierte Änderungen vorbereiten, MCPs und Docker-Dienste bauen/deployen, Modelle laden, Benchmarks starten, Profile und OpenWebUI pflegen, Git veröffentlichen und Recovery erzeugen. Zusätzlich bietet er ein breites, ausgabebegrenztes Terminal für unvorhergesehene Docker-, Datei-, Git-, HTTP-, Modell- und Remote-SSH-Aufgaben. Die MCP-Fassade sieht nur einen lokalen Unix-Socket; Root-Rechte verbleiben im Executor. Strombefehle und Änderungen an Athenas SSH, LAN, WireGuard, Firewall, Boot, Kernel, Mounts und Partitionen werden serverseitig blockiert.

Für Git-Publishing besitzt Athena ein eigenes Schlüsselpaar unter /etc/mike-ai/athena-operator-git{,.pub}. Nur der öffentliche Schlüssel wird in Gitea als schreibberechtigter Deploy-Key für AI-Profile-Router hinterlegt. Der private Schlüssel verlässt Athena nicht und wird weder an den MCP-Container noch an das Modell ausgegeben. Der Gitea-Endpunkt ist als ssh://...:33/... konfiguriert; sein auf dem Administrator-Mac verifizierter Ed25519-Hostschlüssel ist in config/athena-operator-known-hosts fest gebunden. Ein unerwarteter Hostschlüsselwechsel stoppt Git-Zugriffe, statt ihn still zu akzeptieren.

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 ist der allgemeine portable Web-MCP. Auf VPN-Port 8203 können Hermes, Pi und andere Clients seine vier Upstream-Werkzeuge direkt nutzen. SearXNG ist der Such-Backenddienst. Die historische eigene Web-Fassade ist nur Rollback.

Die fünf Open-WebUI-Profile Fast, Medium, Large, Ultra und Uncensored halten für allgemeine öffentliche Recherche Open WebUIs native Werkzeuge search_web und fetch_url verfügbar. Neue Websites benötigen keine neue Selector-Regel.

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 voneinander ab. Das Modell beginnt mit den breitesten geeigneten Grundfähigkeiten und nutzt Fach-MCPs dort, wo strukturierte Daten oder Aktionen benötigt werden:

Aufgabe	Werkzeugserver	Nicht zusätzlich verwenden
Aktuelle öffentliche Informationen, Quellen, Hugging Face, Produkte	Web	HA, ARR, Unraid
GitHub-Repository finden, README/Quellcode/API-Routen gezielt 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	MUA · Unraid-Diagnose (read-only)	MUA-Verwaltung
Athena-KI-Plattform entwickeln, testen, deployen, Modelle/Git/Recovery pflegen	Athena Operator	Platform Context für reine Architekturauskunft
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 der physischen Universitätsadresse veröffentlicht. Über Athenas WireGuard-Adresse sind die Fach-MCPs direkt auf den in docs/VPN_SERVICE_PORTS.md dokumentierten Ports erreichbar.
• 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.
• Das allgemeine Terminal ist Bestandteil des Athena Operators auf Port 8202; ein zweiter Shell-MCP ist nicht erforderlich.

Start

sudo platform/mcp/install-tools.sh

Der Grundstart enthält Plattformwissen, den Athena Operator und das allgemeine TinySearch-Webwerkzeug. Bereits konfigurierte Fachbereiche werden explizit ergänzt:

Das Skript erkennt vorhandene Secret-Dateien und aktiviert dadurch automatisch homeassistant, arr, navidrome und github. Ohne Fach-Secrets bleiben die secretfreien Grunddienste aktiv.

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:

/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/mua-mcp.env

mua-mcp.env enthält ausschließlich MUA-Endpunkt und Bearer-Token. Der Installer legt daraus die vollständige MUA-Verbindung und eine strikt auf Lesewerkzeuge begrenzte automatische Ansicht an. Die Datei ist root-only (Modus 0600) und wird nur verschlüsselt im Recovery-Bundle gesichert.

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:

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.

Die Brücke wird mit --pass-environment gestartet. Ohne diese ausdrückliche Option sieht zwar der Proxy-Prozess den per Docker-Envfile injizierten PAT, der von ihm gestartete GitHub-stdio-Unterprozess jedoch nicht; der offizielle Server fällt dann irreführend auf die interaktive GitHub-Geräteanmeldung zurück. Der Token bleibt dabei eine Umgebungsvariable und erscheint weder in Kommandozeile noch Image, Log oder Open-WebUI-Konfiguration.

Dem Modell werden ausschließlich search_repositories, get_file_contents und search_code angeboten. Rekursive Komplettbäume wurden entfernt, nachdem ein einzelner Aufruf mehr als 100.000 Zeichen erzeugte und die Antwort verdrängte. 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:

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 drei 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 native OpenWebUI-Websuche und die drei 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:

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.