docs: add autonomous Hermes setup guide

2026-08-26 13:43:40 +02:00
parent 2744cc5478
commit b0070861d2
3 changed files with 213 additions and 0 deletions
@@ -0,0 +1,139 @@
+# 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.
+
+## 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.