154 lines
5.2 KiB
Markdown
154 lines
5.2 KiB
Markdown
# 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,
|
|
liefert MUA dessen dynamisch per Label erkannten Namen bereits in den
|
|
MCP-Anweisungen. Hermes verwendet ihn dann über `unraid_system_shell` und
|
|
`docker exec`; 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.
|