Add Hermes MCPHub deployment skill

2026-08-26 00:06:29 +02:00
parent 3ab7c57043
commit c0c1c6db66
2 changed files with 106 additions and 0 deletions
@@ -0,0 +1,102 @@
+---
+name: mcphub-deployer
+description: Install, update, publish, test, and remove MCP servers through the CasaDeRoll MCPHub on Unraid. Use for requests to add an MCP from a catalog, GitHub, npm, PyPI, or local source; move a portable MCP into MCPHub; expose a new /mcp/NAME route; register it in Hermes or OpenWebUI; or repair an MCPHub deployment.
+---
+
+# MCPHub Deployer
+
+Treat MCPHub on Unraid as the production home for portable MCP servers. Do not
+create another MCP container on Athena merely because an upstream project ships
+a Docker image. Do not install or launch a portable stdio MCP inside Hermes;
+Hermes is a client of the separately managed MCPHub routes.
+
+## Production facts
+
+- Container: `MCPHub` on Unraid (`192.168.1.2`).
+- Image: `casaderoll/mcphub:<version>`, based on `samanhappy/mcphub`.
+- Appdata: `/mnt/nvme-storage/appdata/MCPHub`.
+- Secrets: `/mnt/nvme-storage/appdata/MCPHub/secrets/*.env`, mode `0600`.
+- Client token: `/mnt/nvme-storage/appdata/MCPHub/client-token`.
+- UI and MCP base: `http://192.168.1.2:8787`.
+- Each server stays separately addressable as `/mcp/<name>`.
+- Versioned sources live in the `AI-Profile-Router` repository.
+
+Use the `unraid` MCP for live inspection and deployment. Use Git tools or the
+documented repository workflow for durable source changes. If no authorized
+write path to the repository exists, stop after preparing a patch and report
+that exact blocker; never make an unversioned production-only implementation.
+
+## Choose the integration type
+
+1. **Existing HTTP MCP:** Register its URL and optional auth header. Do not copy
+   its code or create a duplicate backend.
+2. **Packaged stdio MCP:** Run a pinned npm or Python package inside MCPHub.
+   Prefer `npx <package>@<version>` or `uvx --from <package>==<version>` only
+   after verifying the real executable and transport.
+3. **Custom MCP:** Keep its source in the repository, copy it into the MCPHub
+   image, pin its dependencies, and register its stdio command.
+4. **Host-bound administration:** Keep it outside MCPHub only when it truly
+   requires a host-local socket, filesystem, or hardware device. Prefer SSH or
+   an authenticated HTTP endpoint from MCPHub over another permanent manager.
+
+## Durable source of truth
+
+Change only the files required for the selected integration:
+
+- `platform/mcphub/Dockerfile` for packages, binaries, or copied custom code.
+- `platform/mcphub/configure-settings.py` for the declared MCPHub server entry.
+- The MCP source under its existing versioned directory.
+- `config/mcp-registry.json` for client-visible metadata and routing.
+- `config/unraid-templates/my-MCPHub.xml` when the image tag, mounts, or
+  environment must change.
+- A focused test or probe when the existing verifier cannot cover the server.
+
+Do not treat a manual edit of `mcp_settings.json` as the final change:
+`configure-settings.py` regenerates `mcpServers` when the container starts.
+Preserve existing users, bearer keys, prompts, resources, and tool toggles.
+
+## Workflow
+
+1. Inspect the current MCPHub container, declared servers, target backend, and
+   existing service catalog. Reuse an existing service instead of installing a
+   second copy.
+2. Inspect the upstream repository and release. Verify license, maintained
+   version, actual command, transport, tool schemas, required credentials, and
+   whether it needs outbound network access. Do not infer an API from a README
+   alone when source routes or a live probe are available.
+3. State a short plan and rollback. If the user asked only for a plan, stop
+   before changing production. Otherwise continue under the granted change.
+4. Implement the smallest versioned change. Pin package and base-image versions;
+   never introduce an unpinned production `latest`, `npx -y`, or floating Git
+   branch merely for convenience.
+5. Place real credentials only in the matching Unraid secret env file. Never
+   commit, print, or return them in tool output.
+6. Build a new local MCPHub image tag and update the Unraid template to that
+   exact tag. Do not overwrite the running tag before the image builds cleanly.
+7. Recreate only `MCPHub` through DockerMan so it remains a managed Unraid
+   container. Preserve `/mnt/nvme-storage/appdata/MCPHub`. Do not restart
+   Athena, Router, Qwen, Hermes, OpenWebUI, WireGuard, or unrelated containers.
+8. Verify container health, an MCP handshake, `list_tools`, schema compatibility,
+   and one bounded read-only call. A running container alone is not success.
+9. Register `http://192.168.1.2:8787/mcp/<name>` in every intended Hermes
+   profile and in OpenWebUI through the declared client registry. New downstream
+   MCPs are not automatically advertised to clients. Reload only the affected
+   profile gateway if discovery requires it, then test from the real client.
+10. Commit and push only the intended files. Confirm the normal Unraid Appdata
+    backup includes MCPHub; do not build a separate recovery bundle.
+
+## Rollback
+
+Restore the previous image tag and declarative server list, recreate only
+`MCPHub`, and repeat handshake plus one read-only probe. Do not delete Appdata
+or secret files during rollback. Remove a secret only after confirming no
+remaining server uses it.
+
+## Stop conditions
+
+- Stop after one corrected attempt when the upstream command, API, transport,
+  or repository write path remains unknown.
+- Never fake tool results or claim a deploy, client registration, commit, push,
+  or backup succeeded without its actual result.
+- Ask before any destructive queue action, download, service mutation, or
+  credential rotation that was not explicitly requested.
@@ -0,0 +1,4 @@
+interface:
+  display_name: "MCPHub Deployer"
+  short_description: "Install and publish MCP servers through MCPHub"
+  default_prompt: "Use $mcphub-deployer to install and publish this MCP through the CasaDeRoll MCPHub."