--- name: mcphub-deployer description: Install, update, disable, test, publish, or remove portable MCP servers in CasaDeRoll MCPHub on Unraid. Use for MCP catalog, GitHub, npm, PyPI, Go-binary, existing HTTP-MCP, client-registration, MCPHub repair, or moving an MCP out of Athena or Hermes. --- # MCPHub Deployer Install portable MCPs in the existing `MCPHub` container on Unraid. Never create one Docker container per portable MCP and never install one inside Hermes. Hermes, OpenWebUI, Pi, and other agents are clients of MCPHub. ## Fixed production map Use these paths directly. Do not search the filesystem for alternatives. - Host: Unraid `192.168.1.2` - Container: `MCPHub` - UI/base URL: `http://192.168.1.2:8787` - Operational source/build tree: `/mnt/nvme-storage/appdata/MCPHub/build` - Dockerfile: `platform/mcphub/Dockerfile` below that tree - Server declaration: `platform/mcphub/configure-settings.py` - Client registry: `config/mcp-registry.json` - Unraid template: `config/unraid-templates/my-MCPHub.xml` - Persistent state: `/mnt/nvme-storage/appdata/MCPHub` - Secrets: `/mnt/nvme-storage/appdata/MCPHub/secrets/.env`, mode `0600` - Client bearer token: `/mnt/nvme-storage/appdata/MCPHub/client-token` - Individual route: `http://192.168.1.2:8787/mcp/` The operational build tree is persistent and covered by the normal Unraid Appdata backup. The checkout below is legacy and MUST NOT be used or inspected for MCPHub work: `/mnt/nvme-storage/Eigene Dateien/Michael/Entwicklung/AI-Profile-Router` The normal Git repository remains the durable documentation/history. Publish the same focused files there when an authorized Git write path is available. Lack of Git access is a warning to report, not permission to search for other checkouts and not a reason to abandon an otherwise requested local install. ## Mandatory fast path For a normal installation, perform these phases once and in order. Do not restart discovery after a phase has completed. ### 1. Preflight — at most six checks Check only: 1. `MCPHub` container state, image tag, mounts, and network. 2. The four fixed production files listed above. 3. Existing MCPHub server names to avoid duplication. 4. Target service reachability or the upstream release. 5. Required secret-file presence; never print its values. 6. Current Git availability, if any. Never run a filesystem-wide `find`. Never read unrelated Compose stacks, repositories, documentation trees, or all container logs. ### 2. Classify once Choose exactly one integration: - Existing HTTP MCP: declare its URL and authentication; do not copy it. - Packaged stdio MCP: pin and install the exact npm/Python package in MCPHub. - Released binary: pin version and checksum; download and verify it during the Docker image build. Do not commit a downloaded binary. - Custom MCP: keep source in the build tree and copy it into the image. - Host-bound MCP: leave it on its required host and proxy its authenticated HTTP endpoint through MCPHub. Do not reconsider this classification unless a real build or handshake result contradicts it. ### 3. Interpret the user's intent - “Prüfe/plane/zeige den Ablauf”: inspect and return a short plan; change nothing. - “Installiere/baue ein/los/Abfahrt”: continue through deployment and tests. - “Zunächst deaktiviert”: install the runtime and declaration with `enabled: false`; do not add it to client registries yet. - “Nur lesen”: disable or omit mutating tools before client publication. Ask only for information that cannot be derived safely: credentials, a material license decision, or an ambiguous destructive permission. ### 4. Implement the smallest change Modify only the necessary fixed production files. Rules: - Pin image, package, release, and checksum versions. - Put credentials only in the matching secret file with mode `0600`. - Never print, log, commit, summarize, or return a secret. - Use `/usr/local/bin/run-with-env` for secret-backed stdio servers. - Declare servers in `configure-settings.py`; do not manually treat `mcp_settings.json` as the source of truth. - Preserve existing users, bearer keys, prompts, resources, enabled states, and per-tool toggles. - Build a new image tag. Never overwrite the tag currently running. - Update the Unraid template to the exact new tag. For servers exposing many tools, install disabled first. After a successful local test, enable only the required tool groups in MCPHub. Do not publish an unfiltered large server to clients. ### 5. Deploy without collateral changes Build from `/mnt/nvme-storage/appdata/MCPHub/build`, then recreate only `MCPHub` through Unraid DockerMan so it stays a managed Unraid container. Preserve all Appdata and mounts. Never restart Athena, Router, Qwen, Hermes, OpenWebUI, WireGuard, Unraid, or unrelated containers for an MCPHub deployment. ### 6. Prove the result Verify, in this order: 1. New container uses the intended image and remains healthy. 2. Existing MCP routes still handshake. 3. New server starts when enabled. 4. MCP handshake and `list_tools` succeed with valid schemas. 5. One bounded read-only function returns plausible live data. 6. No test download, queue item, write, or second backend remains. 7. If installed disabled, return it to disabled after the temporary test. A running container alone is not success. Never claim install, test, registration, Git push, or backup without observing its result. ### 7. Publish to clients only after filtering Add `http://192.168.1.2:8787/mcp/` to `config/mcp-registry.json` only after the server and selected tools have passed verification. Generate intended Hermes/OpenWebUI registrations from that one registry. Reload only the affected client gateway if required. New MCPHub servers are not automatically advertised by the model router. ### 8. Finish compactly Report exactly: - installed version and image tag; - enabled/disabled state and exposed tool count; - secret-file path without values; - handshake and read-only probe result; - client registrations changed or intentionally omitted; - Git status/push result; - rollback image tag. Do not narrate repeated planning or internal reconsideration. ## Context-compaction checkpoint Before a long build or whenever context use approaches compression, write a small checkpoint to: `/mnt/nvme-storage/appdata/MCPHub/work/.json` Store only: requested outcome, integration type, completed phases, modified paths, old/new image tags, pending action, verification results, and rollback. Never store credentials. After compression, reread this SKILL.md from the fixed Hermes skill path plus that checkpoint, then continue at the pending phase. Never rediscover completed phases. Delete the checkpoint after a successful final report. Keep it on failure so a new session can resume safely. ## Hard limits and stop rules - Maximum two attempts for the same command, endpoint, or hypothesis. - Maximum one corrected build after the first failed build. - Never repeat “I now understand the mechanism” and continue researching. - If upstream command, transport, license, or credentials remain unknown after two focused checks, stop and state that exact blocker. - If deployment fails, keep the previous container/image running and report the failing phase. Do not improvise a second container or unversioned binary. - Ask before destructive queue actions, downloads, service mutations, or credential rotation that the user did not explicitly authorize. ## Rollback Restore the previous image tag and declarative server entry, recreate only `MCPHub`, and repeat existing-route handshakes plus one read-only probe. Never delete Appdata or shared secret files during rollback.