---
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:<version>`, 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/<name>`.
- 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 <package>@<version>` or `uvx --from <package>==<version>` 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/<name>` 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.