# MUA mit Hermes Agent verwenden

Diese Anleitung ist für Menschen und KI-Agenten gedacht. MUA muss nicht erst
„zu einem MCP gebaut“ werden: Dieses Repository **ist bereits der fertige
MCP-Server**. MUA läuft als Unraid-Plugin auf dem NAS; Hermes wird lediglich als
Client direkt mit dem vorhandenen HTTP-Endpunkt verbunden.

```text
Hermes Agent  ── Streamable HTTP + Bearer-Token ──>  MUA auf Unraid
                                                      Port 3002, Pfad /mcp
```

MCPHub, ein SSH-Wrapper und Unraids GraphQL-API sind hierfür nicht nötig.

## Auftrag für einen Agenten

Ein geeigneter kurzer Auftrag lautet:

> Nutze das Repository `https://git.casaderoll.de/michael/MUA-Mikes-Unraid-Agent`.
> Lies zuerst `AGENTS.md` und `docs/HERMES.md`. Prüfe, ob MUA auf meinem Unraid
> bereits läuft. Wenn ja, installiere keinen zweiten Server, sondern binde den
> bestehenden MCP direkt und persistent in das zentrale Hermes-Gateway ein.
> Nimm keine Änderungen an Modellen, Router, Netzwerk oder MUA-Berechtigungen
> vor. Zeige keine Zugangsdaten. Teste anschließend Verbindung, Tool-Erkennung
> und genau einen harmlosen Nur-Lese-Aufruf. Falls eine Voraussetzung fehlt,
> stoppe mit einer konkreten Fehlermeldung statt eine Ersatzarchitektur zu bauen.

## 1. Vorhandenen Server erkennen

Der offene Health-Endpunkt benötigt keinen API-Key:

```bash
curl -fsS http://192.168.1.2:3002/health
```

Erwartet wird JSON mit `"status":"ok"` und `"auth":"required"`. Dann läuft
MUA bereits und darf für die Hermes-Anbindung weder neu gebaut noch neu
installiert werden.

Wenn der Health-Check fehlschlägt:

1. auf Unraid `/etc/rc.d/rc.mua status` prüfen;
2. einen vorhandenen, aber gestoppten Dienst nur auf ausdrücklichen Auftrag
   starten;
3. bei fehlender Installation den Benutzer informieren und vor der
   Plugin-Installation Zustimmung einholen.

## 2. API-Key beschaffen

In der Unraid-WebGUI:

1. **Settings → User Utilities → MUA** öffnen;
2. vorhandenen Schlüssel verwenden oder bewusst einen neuen erzeugen;
3. den Schlüssel ausschließlich in die geheime Hermes-Eingabe übernehmen.

Eine Rotation ersetzt den bisherigen Schlüssel sofort. Sie darf daher niemals
nebenbei oder nur zur Diagnose erfolgen.

## 3. MUA im zentralen Hermes-Gateway registrieren

Im Hermes-Container liegt die CLI in dieser Installation unter
`/opt/hermes/bin/hermes`. Mit einem korrekt gesetzten `PATH` genügt `hermes`.

```bash
hermes mcp add unraid \
  --url http://192.168.1.2:3002/mcp \
  --auth header \
  --connect-timeout 30
```

Hermes fragt interaktiv:

- ob der Server Authentifizierung benötigt: **Ja**;
- nach dem API-Key/Bearer-Token: nur den Schlüssel, ohne vorangestelltes
  `Bearer `, eingeben.

Hermes speichert den Schlüssel im geheimen `.env` des aktiven zentralen
Profils und hinterlegt in `config.yaml` lediglich eine Variablenreferenz. Der
Schlüssel gehört weder in dieses Repository noch in Chat-Ausgaben.

Alternativ kann die Verbindung in der Hermes-Weboberfläche unter **MCP** als
HTTP-Server angelegt werden:

| Feld | Wert |
|---|---|
| Name | `unraid` |
| URL | `http://192.168.1.2:3002/mcp` |
| Authentifizierung | Header/Bearer |
| Token | MUA-API-Key ohne `Bearer ` |
| Connect timeout | `30` Sekunden |

## 4. Prüfen

```bash
hermes mcp test unraid
hermes mcp list
```

In einer bereits laufenden Hermes-Sitzung danach:

```text
/reload-mcp
```

Abschließend genau einen unschädlichen Leseauftrag verwenden, beispielsweise:

> Liste über MUA nur die Namen und Zustände der Docker-Container auf Unraid.
> Verändere nichts.

Erst wenn Verbindungstest, Werkzeugerkennung und dieser Leseaufruf erfolgreich
sind, ist die Einbindung abgeschlossen.

Wenn der Benutzer MUA in der Unraid-WebGUI bewusst auf **Vollzugriff** gestellt
hat, darf Hermes das angebotene `unraid_system_shell` für ausdrücklich
beauftragte Änderungen direkt verwenden. Das ist bereits das Terminal des
Unraid-Hosts. Dafür weder MUA-Quellcode untersuchen noch das lokale
Hermes-Containerterminal als Zwischenstation verwenden. Normale Befehle und
mehrzeilige Skripte laufen synchron; nur Arbeiten über 30 Minuten verwenden
die asynchronen Job-Werkzeuge.

Wenn in der MUA-WebGUI der optionale Agent-Werkzeugcontainer aktiviert ist,
erscheinen `unraid_toolbox_status` und `unraid_toolbox_exec` direkt im nativen
Hermes-Werkzeugkatalog. Hermes prüft benötigte Programme zuerst mit dem
Statuswerkzeug und führt Medien- oder Downloadbefehle anschließend direkt im
Toolbox-Container aus. Im Hermes-Container selbst werden keine Hilfsprogramme
nachinstalliert. MUA setzt keinen festen Containernamen voraus.

## 5. Entfernen

Nur die Hermes-Verbindung entfernen, nicht das MUA-Plugin auf Unraid:

```bash
hermes mcp remove unraid
```

Danach `/reload-mcp` ausführen. MUA selbst läuft unverändert weiter und kann von
anderen MCP-Clients verwendet werden.

## Wenn MUA wirklich aus dem Quellcode gebaut werden soll

Das ist Entwicklungsarbeit und nicht für eine normale Hermes-Anbindung nötig.
Nur auf ausdrücklichen Auftrag:

```bash
bunx tsc --noEmit
bun test src/security.test.ts
bash scripts/package.sh
xmllint --noout plugin/mua.plg
```

Der Release-Prozess einschließlich Versionierung, SHA-256 und Plugin-Update ist
im Abschnitt **Entwicklung** der `README.md` beschrieben. Ein Build allein
installiert nichts auf Unraid und darf niemals als erfolgreiche Bereitstellung
gemeldet werden.