---
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: `/mnt/nvme-storage/appdata/MCPHub/build/repo/platform/mcphub/Dockerfile`
- Single server and client registry: `/mnt/nvme-storage/appdata/MCPHub/build/repo/config/mcp-registry.json`
- Registry renderer: `/mnt/nvme-storage/appdata/MCPHub/build/repo/platform/mcphub/configure-settings.py` (normally unchanged)
- Versioned Unraid-template source: `/mnt/nvme-storage/appdata/MCPHub/build/repo/config/unraid-templates/my-MCPHub.xml`
- Live DockerMan template: `/boot/config/plugins/dockerMan/templates-user/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 versioned template and the live DockerMan template are different files.
Keep their image tag and required mounts aligned. If the versioned template is
missing, copy the live template to that exact versioned path once; do not search
for another template and do not infer a replacement from unrelated containers.

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 fixed Dockerfile, registry, renderer, and both template paths 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 `find` to rediscover a listed path. Never read unrelated Compose
stacks, repositories, documentation trees, container logs, container
environments, application configs, home directories, or secret stores.

### Credential boundary — mandatory stop

Credentials and account configuration are user-supplied inputs, not discovery
targets. This rule overrides the desire to complete a deployment or live test.

- Never inspect another container, service, environment, mount, config file,
  mailbox, shell history, password manager, or secret directory to obtain or
  infer credentials.
- Never reuse credentials found in an existing mail server or another app
  unless the user explicitly names that exact source and authorizes reuse.
- Check only whether the dedicated fixed secret file for this server exists;
  do not read its values during preflight.
- If the MCP needs credentials or account settings and the dedicated file is
  absent or incomplete, finish all credential-independent build work, install
  the server disabled, and stop before live authentication. Ask the user for
  the missing fields and state the exact secret-file path.
- Do not substitute inspection of an existing service for that question.
- A missing credential may reduce verification to build plus MCP handshake; it
  is never permission to investigate the user's infrastructure.

### 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.

For mail-related MCPs, repository inspection may determine which field names
are required, but the IMAP/SMTP host, user, password/token, sender identity, and
TLS choices must come from the user or the dedicated secret file. The presence
of a Docker mail server does not answer those questions.

### 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 both the versioned template source and the live DockerMan template to
  the exact new tag. Do not rebuild `template.xml` inside an upstream image.

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.

Do not use unrestricted host shell access during repository analysis,
classification, or credential preflight. Use it only after the exact file
changes, new image tag, verification steps, and rollback tag are known. Its
scope is then limited to those declared paths and the `MCPHub` container.

### 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.

If credentials are unavailable, steps 3 and 5 may be recorded as blocked.
Never weaken the credential boundary merely to make the live probe pass.

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.