From 5ed1f571a1d3c2239a6b12d381b0622c8f34dd80 Mon Sep 17 00:00:00 2001 From: Mikei386 <44135113+Mikei386@users.noreply.github.com> Date: Wed, 26 Aug 2026 06:43:18 +0200 Subject: [PATCH] Make MCPHub deployments deterministic --- .../hermes/skills/mcphub-deployer/SKILL.md | 246 ++++++++++++------ 1 file changed, 164 insertions(+), 82 deletions(-) diff --git a/platform/hermes/skills/mcphub-deployer/SKILL.md b/platform/hermes/skills/mcphub-deployer/SKILL.md index 1e7b87e..e414451 100644 --- a/platform/hermes/skills/mcphub-deployer/SKILL.md +++ b/platform/hermes/skills/mcphub-deployer/SKILL.md @@ -1,102 +1,184 @@ --- 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. +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 -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. +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. -## Production facts +## Fixed production map -- 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 these paths directly. Do not search the filesystem for alternatives. -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. +- 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/` -## Choose the integration type +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: -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. +`/mnt/nvme-storage/Eigene Dateien/Michael/Entwicklung/AI-Profile-Router` -## Durable source of truth +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. -Change only the files required for the selected integration: +## Mandatory fast path -- `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. +For a normal installation, perform these phases once and in order. Do not +restart discovery after a phase has completed. -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. +### 1. Preflight — at most six checks -## Workflow +Check only: -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. +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 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. +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.