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.

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:

curl -fsS http://UNRAID-IP: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:

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

2. API-Key beschaffen

In der Unraid-WebGUI:

Settings → User Utilities → MUA öffnen;
vorhandenen Schlüssel verwenden oder bewusst einen neuen erzeugen;
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.

hermes mcp add unraid \
  --url http://UNRAID-IP: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://UNRAID-IP:3002/mcp`
Authentifizierung	Header/Bearer
Token	MUA-API-Key ohne `Bearer`
Connect timeout	`30` Sekunden

4. Prüfen

hermes mcp test unraid
hermes mcp list

In einer bereits laufenden Hermes-Sitzung danach:

/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:

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:

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.

5.3 KiB Raw Blame History