MUA-Mikes-Unraid-Agent/AGENTS.md

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.