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,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.