# 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`) |

TinySearch und SearXNG sind interne Abhängigkeiten des Web-MCPs und werden
nicht direkt als allgemeine Werkzeuge angeboten.

## 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.

## 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-/Release-Downloads. Tickets gelten zehn
Minuten, sind einmalig und an genau die angezeigte Auswahl gebunden.