# ARR-MCP auf Unraid

Dieser Ordner baut **einen eigenständigen Container nur für Sonarr und Radarr**.
Hermes, Pi Coding und andere MCP-Clients erreichen ihn anschließend über
`http://<UNRAID-IP>:8207/mcp`.

## Warum dieser Fork bleibt

Geprüft am 27. August 2026:

- [`Knuckles-Team/arr-mcp`](https://github.com/Knuckles-Team/arr-mcp) 2.1.0
  ist der moderne Upstream unseres Pakets, stellt
  in der kompakten Oberfläche aber weiterhin generische `*_action`-Werkzeuge
  mit frei wählbaren API-Methoden bereit. Das führte bei lokalen Modellen zu
  falschen Aktionen, unnötigen Schemaabfragen und großen Antworten.
- Andere öffentliche ARR-MCPs bieten teilweise mehr Dienste oder eine eigene
  Weboberfläche, ersetzen aber nicht unser kompaktes Radarr-Codec-Inventar und
  den an eine Vorschau gebundenen Sonarr-Freigabeablauf.

Wir bleiben deshalb vorläufig bei `arr-mcp` 1.0.1 plus zwei kleinen,
versionierten Patches. Ein späterer Wechsel ist sinnvoll, sobald ein Upstream
diese Eigenschaften ohne lokale Anpassungen anbietet.

## Besondere Werkzeuge

- `radarr_movie_codec_inventory`: kompakte, paginierte Liste mit Codec,
  Auflösung, Sprachen und Dateigröße; keine riesigen Radarr-Rohantworten.
- `sonarr_action`: begrenzte, kompakte Sonarr-Aktionen wie `find_series`,
  `get_season_summary` und `search_releases`.
- Sonarr-Schreibaktionen sind standardmäßig abgeschaltet. Im Schreibmodus
  benötigen `start_episode_search` und `grab_release` zuerst eine passende
  Vorschau, danach eine ausdrückliche Freigabe und ein kurzlebiges Ticket.

## Empfohlene Installation auf Unraid

Im vollständigen Checkout des Repositories als root:

```bash
./services/arr-mcp/install-on-unraid.sh
```

Beim ersten Aufruf entsteht:

```text
/mnt/nvme-storage/appdata/ARR-MCP/arr-mcp.env
```

Dort Sonarr- und Radarr-Schlüssel eintragen. Danach denselben Installationsbefehl
erneut ausführen. Das Skript:

1. baut das lokale Image `mike-ai/arr-mcp:1.0.0` aus `python:3.13-slim`,
2. startet ausschließlich den Container `ARR-MCP` im normalen Bridge-Netz,
3. wartet auf den Healthcheck und
4. installiert das DockerMan-Template für spätere Bedienung in der Unraid-GUI.

Es liest oder druckt keine Schlüssel. Eine vorhandene Konfiguration wird nie
überschrieben.

### Kurzer Auftrag für Hermes/Qwen

```text
Klone auf Unraid das Repository
ssh://git@192.168.1.2:33/michael/AI-Profile-Router.git, lies vollständig
services/arr-mcp/README.md und installiere ausschließlich nach dem dort
dokumentierten Weg. Verwende services/arr-mcp/install-on-unraid.sh. Zeige keine
API-Schlüssel an und überschreibe keine vorhandene arr-mcp.env. Stoppe, falls
Werte fehlen, und sage mir nur, welche Variablennamen ich eintragen muss.
Entferne den bisherigen ARR-Endpunkt erst nach einem erfolgreichen Healthcheck
und MCP-Handshake des neuen Containers.
```

## Installation in einem vorhandenen Debian-Slim-Container

Nur verwenden, wenn bereits bewusst ein nackter Debian-Slim-Container mit dem
kompletten Git-Checkout läuft:

```bash
./services/arr-mcp/install-in-debian-slim.sh
```

Danach startet `/usr/local/bin/run-arr-mcp` den Server. Dieser Weg funktioniert,
ist aber weniger reproduzierbar als der Dockerfile-Build: Eine Neuerstellung des
nackten Containers entfernt die Installation. Für den Produktivbetrieb deshalb
den ersten Weg verwenden.

## Hermes oder anderer MCP-Client

Direkte Registrierung:

```yaml
mcp_servers:
  arr:
    url: http://192.168.1.2:8207/mcp
    timeout: 600
```

Nach dem Eintragen die MCP-Liste des Clients neu laden beziehungsweise einen
neuen Chat öffnen. Sonarr und Radarr erscheinen als Werkzeuge desselben
Fach-MCPs; sie sind nicht Bestandteil des Hermes-Containers.

## Schreiben aktivieren

In `arr-mcp.env`:

```text
ARR_MCP_WRITE=1
```

Danach nur diesen Container neu starten. Selbst dann erlaubt der Sonarr-Patch
nur die dokumentierten, ticketgebundenen Aktionen. Radarr besitzt derzeit noch
keinen gleichwertigen Freigabeablauf; Änderungen dort nur auf einen eindeutigen
Benutzerauftrag ausführen.

## Update und Test

Nach einem Git-Update denselben Befehl erneut ausführen:

```bash
./services/arr-mcp/install-on-unraid.sh
```

Status und Logs:

```bash
docker inspect --format '{{.State.Health.Status}}' ARR-MCP
docker logs --tail 100 ARR-MCP
```

Die Offline-Tests des Forks:

```bash
python3 dev/test_radarr_patch.py
python3 -m unittest dev/test_sonarr_release_grab.py
```

## Deinstallation

```bash
./services/arr-mcp/install-on-unraid.sh uninstall
```

Der Container verschwindet, während die Appdata-Konfiguration als Rückfall
erhalten bleibt. Erst wenn sie wirklich nicht mehr benötigt wird, kann
`/mnt/nvme-storage/appdata/ARR-MCP` separat gelöscht werden.

## Regeln für Hermes/Qwen

1. Diese README vollständig lesen.
2. Keine eigene ARR-Implementierung und keinen zweiten Sonarr-/Radarr-Dienst
   erstellen.
3. Ausschließlich `install-on-unraid.sh` verwenden; keine Befehle improvisieren.
4. Vorhandene `arr-mcp.env` weder anzeigen noch überschreiben.
5. Nach Installation Healthcheck und MCP-Handshake prüfen.
6. Den alten MCPHub-/Athena-Endpunkt erst entfernen, wenn der neue Endpunkt
   nachweislich funktioniert.