From c0c1c6db6642937f9aba4c4bbff8ba22febdec21 Mon Sep 17 00:00:00 2001 From: Mikei386 <44135113+Mikei386@users.noreply.github.com> Date: Wed, 26 Aug 2026 00:06:29 +0200 Subject: [PATCH] Add Hermes MCPHub deployment skill --- .../hermes/skills/mcphub-deployer/SKILL.md | 102 ++++++++++++++++++ .../skills/mcphub-deployer/agents/openai.yaml | 4 + 2 files changed, 106 insertions(+) create mode 100644 platform/hermes/skills/mcphub-deployer/SKILL.md create mode 100644 platform/hermes/skills/mcphub-deployer/agents/openai.yaml diff --git a/platform/hermes/skills/mcphub-deployer/SKILL.md b/platform/hermes/skills/mcphub-deployer/SKILL.md new file mode 100644 index 0000000..1e7b87e --- /dev/null +++ b/platform/hermes/skills/mcphub-deployer/SKILL.md @@ -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:`, 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/`. +- 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 @` or `uvx --from ==` 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/` 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. diff --git a/platform/hermes/skills/mcphub-deployer/agents/openai.yaml b/platform/hermes/skills/mcphub-deployer/agents/openai.yaml new file mode 100644 index 0000000..360a925 --- /dev/null +++ b/platform/hermes/skills/mcphub-deployer/agents/openai.yaml @@ -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."