108 lines
4.7 KiB
Markdown
108 lines
4.7 KiB
Markdown
---
|
|
name: mcphub-deployer
|
|
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`; never create a separate
|
|
container and never install them inside Hermes.
|
|
|
|
## Fixed map
|
|
|
|
- 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>`
|
|
|
|
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.
|
|
|
|
## Hard credential boundary
|
|
|
|
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.
|
|
|
|
## One-pass workflow
|
|
|
|
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`:
|
|
|
|
```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"}
|
|
]
|
|
}
|
|
```
|
|
|
|
Use paths as seen inside MCPHub (`/app/data/...`) in the manifest.
|
|
6. Stage with exactly:
|
|
|
|
```sh
|
|
docker exec MCPHub python3 /opt/casaderoll/deploy-extension.py stage \
|
|
--manifest /app/data/work/<id>/manifest.json
|
|
```
|
|
|
|
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.
|
|
|
|
## Limits
|
|
|
|
- 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.
|
|
|
|
## Resume
|
|
|
|
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.
|