191 lines
9.5 KiB
Markdown
191 lines
9.5 KiB
Markdown
# 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-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`) |
|
|
|
|
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.
|
|
|
|
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, GitHub/Hugging Face, Produkte | Web | HA, ARR, Unraid |
|
|
| Entitäten, Zustände, Historie, Automationen und Dashboards | Home Assistant | Web, Unraid |
|
|
| Serien, Filme, fehlende Episoden und Indexer-Releases | Sonarr und Radarr | Web |
|
|
| 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/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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
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.
|