|
|
|
@@ -1,229 +1,107 @@
|
|
|
|
|
---
|
|
|
|
|
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.
|
|
|
|
|
description: Install, update, disable, test, publish, or inspect portable MCP servers in CasaDeRoll MCPHub on Unraid. Use for MCP repositories, packages, binaries, HTTP MCPs, 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.
|
|
|
|
|
Install portable MCPs in the existing `MCPHub`; never create a separate
|
|
|
|
|
container and never install them inside Hermes.
|
|
|
|
|
|
|
|
|
|
## Fixed production map
|
|
|
|
|
## Fixed map
|
|
|
|
|
|
|
|
|
|
Use these paths directly. Do not search the filesystem for alternatives.
|
|
|
|
|
- Unraid: `192.168.1.2`; container: `MCPHub`; base URL: `http://192.168.1.2:8787`
|
|
|
|
|
- Appdata: `/mnt/nvme-storage/appdata/MCPHub`
|
|
|
|
|
- Work: `/mnt/nvme-storage/appdata/MCPHub/work/<id>`
|
|
|
|
|
- Extensions: `/mnt/nvme-storage/appdata/MCPHub/extensions/<id>`
|
|
|
|
|
- Registry: `/mnt/nvme-storage/appdata/MCPHub/config/mcp-registry.json`
|
|
|
|
|
- Secret: `/mnt/nvme-storage/appdata/MCPHub/secrets/<id>.env` (0600)
|
|
|
|
|
- Helper in container: `/opt/casaderoll/deploy-extension.py`
|
|
|
|
|
- Route: `http://192.168.1.2:8787/mcp/<id>`
|
|
|
|
|
|
|
|
|
|
- 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>`
|
|
|
|
|
Do not search for other checkouts, registries, templates, or secret stores.
|
|
|
|
|
Normal extensions do not modify Dockerfile, image tag, Unraid template, MCPHub
|
|
|
|
|
source, or Hermes config manually.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
## Hard credential boundary
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
Credentials are user input. Check only whether the dedicated secret file and
|
|
|
|
|
required keys exist; never print values. Never inspect other containers,
|
|
|
|
|
environments, mail servers, configs, histories, or passwords to find or infer
|
|
|
|
|
credentials. If credentials are missing, complete credential-independent build
|
|
|
|
|
work, stage the MCP disabled, report the exact secret path and missing key
|
|
|
|
|
names, then stop. Never publish or authenticate it.
|
|
|
|
|
|
|
|
|
|
`/mnt/nvme-storage/Eigene Dateien/Michael/Entwicklung/AI-Profile-Router`
|
|
|
|
|
## One-pass workflow
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
1. Read this skill once. Inspect only MCPHub state, the fixed registry, the
|
|
|
|
|
dedicated secret-file presence, and the target upstream release/source.
|
|
|
|
|
2. Classify once: existing HTTP MCP, packaged stdio MCP, released binary,
|
|
|
|
|
custom MCP, or host-bound HTTP proxy. Do not reconsider without a concrete
|
|
|
|
|
failed build or handshake.
|
|
|
|
|
3. Interpret intent: “prüfen/planen” changes nothing; “installieren/einbauen”
|
|
|
|
|
continues; “deaktiviert” never activates; “read-only” omits mutating tools.
|
|
|
|
|
4. Build only in `/tmp` or the fixed work directory. Pin versions and verify
|
|
|
|
|
checksums. Put runtime files in the work directory, not in the repository.
|
|
|
|
|
5. Write one compact manifest at `<work>/manifest.json`:
|
|
|
|
|
|
|
|
|
|
## Mandatory fast path
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"server": {
|
|
|
|
|
"id": "example", "hermes_id": "example", "name": "Example",
|
|
|
|
|
"description": "Short tool-selection description",
|
|
|
|
|
"url": "http://192.168.1.2:8787/mcp/example",
|
|
|
|
|
"clients": ["hermes"],
|
|
|
|
|
"deployment": {"required_env": ["EXAMPLE_TOKEN"]},
|
|
|
|
|
"hub": {
|
|
|
|
|
"type": "stdio", "secret_file": "example.env",
|
|
|
|
|
"command": "/usr/local/bin/run-with-env",
|
|
|
|
|
"args": ["/run/secrets/mcphub/example.env", "--", "node", "/app/data/extensions/example/index.js"],
|
|
|
|
|
"enabled": false
|
|
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
"artifacts": [
|
|
|
|
|
{"source": "/app/data/work/example/index.js", "path": "index.js", "sha256": "HEX", "mode": "0644"}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For a normal installation, perform these phases once and in order. Do not
|
|
|
|
|
restart discovery after a phase has completed.
|
|
|
|
|
Use paths as seen inside MCPHub (`/app/data/...`) in the manifest.
|
|
|
|
|
6. Stage with exactly:
|
|
|
|
|
|
|
|
|
|
### 1. Preflight — at most six checks
|
|
|
|
|
```sh
|
|
|
|
|
docker exec MCPHub python3 /opt/casaderoll/deploy-extension.py stage \
|
|
|
|
|
--manifest /app/data/work/<id>/manifest.json
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Check only:
|
|
|
|
|
The helper copies verified files, updates the registry atomically, and always
|
|
|
|
|
stages disabled. It technically blocks activation when the dedicated secret
|
|
|
|
|
or a required key is missing.
|
|
|
|
|
7. Recreate only `MCPHub` once so it reconciles the external registry. Do not
|
|
|
|
|
restart Hermes, Athena, Router, Qwen, WireGuard, Unraid, or other services.
|
|
|
|
|
8. If credentials are ready, activate with the helper, recreate only MCPHub,
|
|
|
|
|
then verify: health; all old routes; new handshake; `list_tools` schemas;
|
|
|
|
|
one bounded read-only call; no test writes or residue. Otherwise stop while
|
|
|
|
|
disabled.
|
|
|
|
|
9. Run the existing client-sync script only after successful activation. Do
|
|
|
|
|
not edit client YAML by hand. New routes are not advertised automatically.
|
|
|
|
|
10. Report version, state, tool count, secret path (never values), tests,
|
|
|
|
|
client sync, durable source status, and rollback.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
## Limits
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
- At most six preflight reads and two attempts per hypothesis.
|
|
|
|
|
- At most one corrected build.
|
|
|
|
|
- Never dump full registries, repository trees, logs, or configs; use bounded
|
|
|
|
|
queries and compact JSON.
|
|
|
|
|
- Never use one giant shell call to write several files.
|
|
|
|
|
- Never claim success without observed handshake and probe results.
|
|
|
|
|
- On failure leave the previous MCPHub running and the new extension disabled.
|
|
|
|
|
- Ask before destructive actions or credential rotation not explicitly asked.
|
|
|
|
|
|
|
|
|
|
### Credential boundary — mandatory stop
|
|
|
|
|
## Resume
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
Before compression write `<work>/checkpoint.json` containing only phase,
|
|
|
|
|
version, completed checks, pending action, modified paths, and rollback. After
|
|
|
|
|
compression reload this skill and that checkpoint before continuing. Delete
|
|
|
|
|
the checkpoint only after success.
|
|
|
|
|
Mikei386