AI-Profile-Router/platform/hermes/skills/mcphub-deployer/SKILL.md

---
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/repo`
- Dockerfile: `platform/mcphub/Dockerfile` below that tree
- Single server and client registry: `config/mcp-registry.json`
- Registry renderer: `platform/mcphub/configure-settings.py` (normally unchanged)
- Unraid template: `config/unraid-templates/my-MCPHub.xml`
- Persistent state: `/mnt/nvme-storage/appdata/MCPHub`
- Secrets: `/mnt/nvme-storage/appdata/MCPHub/secrets/<server>.env`, mode `0600`
- Client bearer token: `/mnt/nvme-storage/appdata/MCPHub/client-token`
- Individual route: `http://192.168.1.2:8787/mcp/<server>`

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 only in `config/mcp-registry.json`; do not hard-code a server
  in `configure-settings.py` and do not edit `mcp_settings.json` manually.
- 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/repo`, 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/<server>` 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/<server>.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 directly from

`/opt/data/skills/platform/mcphub-deployer/SKILL.md`

inside the Hermes container plus that checkpoint, then continue at the pending
phase. Do not rely on a deduplicated/pruned earlier skill result and 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.