docs: add autonomous Hermes setup guide
This commit is contained in:
Mikei386
@@ -0,0 +1,51 @@
|
||||
# Agent instructions for MUA
|
||||
|
||||
This repository already contains a complete, production-ready MCP server for
|
||||
Unraid. Do not design a second Unraid MCP, do not deploy another Deemix-style
|
||||
sidecar and do not enable Unraid GraphQL. The normal task is to install or
|
||||
verify MUA on Unraid and connect an MCP client such as Hermes directly to it.
|
||||
|
||||
## Canonical paths
|
||||
|
||||
- MCP implementation: `src/`
|
||||
- Unraid plugin manifest: `plugin/mua.plg`
|
||||
- packaged releases: `dist/*.txz`
|
||||
- package builder: `scripts/package.sh`
|
||||
- operator documentation: `README.md`
|
||||
- Hermes procedure: `docs/HERMES.md`
|
||||
|
||||
## Required workflow
|
||||
|
||||
1. Read `README.md` and `docs/HERMES.md` before changing anything.
|
||||
2. Check `http://<unraid-ip>:3002/health`.
|
||||
3. If health is successful, MUA is already installed. Do not rebuild or
|
||||
reinstall it. Register its `/mcp` URL in Hermes and test the connection.
|
||||
4. If health fails, determine whether MUA is stopped or absent. Report that
|
||||
distinction before changing Unraid. Installation, upgrade, API-key rotation
|
||||
and tool-permission changes require an explicit user request.
|
||||
5. Use direct Streamable HTTP with Bearer authentication. Do not insert an SSH
|
||||
stdio wrapper and do not route through MCPHub unless the user explicitly
|
||||
requests that architecture.
|
||||
6. Verify with `hermes mcp test unraid`, reload MCP discovery, and confirm that
|
||||
at least one harmless read-only MUA tool is visible.
|
||||
|
||||
## Safety and scope
|
||||
|
||||
- Never print, commit or paste the MUA API key into reports or source files.
|
||||
- Never silently enable `all`, the unrestricted root shell, shutdown, reboot,
|
||||
network reconfiguration or destructive storage operations.
|
||||
- Do not change model, provider, router, WireGuard or Hermes session settings
|
||||
as part of an MUA connection task.
|
||||
- Do not claim success from a health check alone. The authenticated MCP
|
||||
handshake and Hermes tool discovery must also succeed.
|
||||
- Prefer the existing packaged release. Build from source only when the user
|
||||
explicitly asks for development or a new MUA release.
|
||||
|
||||
## Definition of done
|
||||
|
||||
- exactly one MUA service is running on Unraid;
|
||||
- `/health` reports OK;
|
||||
- Hermes reaches `http://<unraid-ip>:3002/mcp` with Bearer authentication;
|
||||
- `hermes mcp test unraid` succeeds;
|
||||
- no secret appears in logs, commits or the final response;
|
||||
- no unrelated service was restarted or reconfigured.
|
||||
@@ -11,6 +11,29 @@ Kompiliertes Bun-Binary (TypeScript), läuft als SysVinit-Service auf Unraid.
|
||||
|
||||
---
|
||||
|
||||
## Für Hermes und andere KI-Agenten
|
||||
|
||||
Dieses Repository enthält bereits den fertigen MUA-MCP. Ein Agent soll keinen
|
||||
zweiten Unraid-MCP entwickeln, sondern zuerst [`AGENTS.md`](AGENTS.md) und die
|
||||
kompakte [`Hermes-Anleitung`](docs/HERMES.md) lesen. Darin stehen Erkennung,
|
||||
direkte Registrierung, Secret-Behandlung, Tests und Rückbau vollständig.
|
||||
|
||||
Kurzform für Hermes:
|
||||
|
||||
```bash
|
||||
hermes mcp add unraid \
|
||||
--url http://192.168.1.2:3002/mcp \
|
||||
--auth header \
|
||||
--connect-timeout 30
|
||||
hermes mcp test unraid
|
||||
```
|
||||
|
||||
Hermes fragt den MUA-API-Key verdeckt ab und speichert ihn außerhalb des
|
||||
Repositories. Läuft `/health` bereits erfolgreich, ist kein Build und keine
|
||||
erneute MUA-Installation nötig.
|
||||
|
||||
---
|
||||
|
||||
## Architektur
|
||||
|
||||
```
|
||||
|
||||
+139
@@ -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.
|
||||
Reference in New Issue
Block a user