diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5be377f --- /dev/null +++ b/AGENTS.md @@ -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://: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://: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. diff --git a/README.md b/README.md index a0f0576..e66bd50 100644 --- a/README.md +++ b/README.md @@ -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 ``` diff --git a/docs/HERMES.md b/docs/HERMES.md new file mode 100644 index 0000000..c886421 --- /dev/null +++ b/docs/HERMES.md @@ -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.