feat(mcp): restore full Hermes MCP roster (codebase-memory, comfyui, n8n, orchestration)

The V1->V2 migration silently dropped Hermes' gateway MCP set from V1's 8
servers to 3 (memory-vault, qdrant-rag, searxng). This restores the four whose
backing service exists in V2, as kind=mcp plugins ported from V1's
registry-custom.yaml (the per-server source of truth):

- codebase-memory: code knowledge graph over /c/dev (read-only), longLived +
  disableNetwork, named cache volume. Index-per-session (in-memory graph).
- comfyui: ComfyUI media tools. Plugin id `comfyui-mcp`, but mcp.server_id pins
  the gateway registry key to `comfyui` to preserve Hermes' `comfyui__*` tool
  namespace (the comfyui SERVICE plugin already owns the bare id).
- n8n: full czlonkowski catalog + n8n_* instance verbs. Banner/telemetry
  suppression (LOG_LEVEL=error, N8N_DIAGNOSTICS_ENABLED=false, DISABLE_TELEMETRY
  =true) keeps the stdio JSON-RPC clean -> full 42 tools, not docs-only 23.
  Image digest-pinned. N8N_API_KEY declared as a plugin secret.
- orchestration: stable verbs delegating to the dashboard /api/orchestration
  control plane (verified live in V2).

Render/compose changes:
- render._render_mcp: optional mcp.server_id decouples the gateway registry key
  (Hermes tool-namespace prefix) from the plugin id, with collision detection.
- compose._mcp_gateway: add MCP_GATEWAY_DOCKER_BIND_ALLOWED_PATHS=${CODE_ROOT}
  (codebase-memory's read-only /c/dev bind is rejected without it) and the
  COMFY_MCP_DEFAULT_MODEL default. The secrets the spawned servers need
  (OPS_CONTROLLER_TOKEN, DASHBOARD_AUTH_TOKEN, N8N_API_KEY) deliberately arrive
  via the secrets.env env_file, NOT the environment block -- a ${VAR:-} there
  interpolates from .env/host (empty) and would SHADOW the env_file value.

V2 build contexts (v2/docker/{codebase-memory,comfyui,orchestration}-mcp) follow
the qdrant-rag-mcp convention: a README pointing at the operator's authoritative
V1 source context (not duplicated, to avoid drift). Images built as ordo-v2/*.

Deferred (backing not in this stack): blog-mcp (separate min-max blog stack),
playwright (generic browser tool, RCE-equivalent, no stack-service backing;
operator's browser-validation uses a dedicated image).

Tests: +12 (compose gateway env, server_id decoupling + collision, per-server
wiring, n8n digest+banner, codebase-memory volumes/longLived, secrets.env.example
N8N_API_KEY, servers.txt/registry-custom.yaml assertions). Parity matrix updated
3->7 MCP. 221 passed / 6 skipped, ruff clean.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Author: Hermes Bot

v2/docker/codebase-memory-mcp/README.md

@@ -0,0 +1,24 @@
+# codebase-memory-mcp (Code knowledge-graph MCP server)
+
+V2's Codebase-Memory MCP image, referenced by the `codebase-memory` plugin as
+`ordo-v2/codebase-memory-mcp:latest`. V1 builds it locally
+(`ordo-ai-stack-codebase-memory-mcp:latest`) from `C:\dev\ordo-ai-stack\codebase-memory-mcp` — a
+self-contained Dockerfile that downloads + sha256-verifies the pinned upstream
+`DeusData/codebase-memory-mcp` portable (statically-linked) release binary and bundles the offline
+`nomic-embed-code` embeddings, so it runs 100% offline (`disableNetwork: true` in the gateway
+catalog). There is no public registry to digest-pin against, so it's a **project buildable image**
+(pinned by build context: the Dockerfile's `CBM_VERSION` + `CBM_SHA256` args); `ordo preflight`
+reports a missing one as "build first".
+
+## Build
+Build from the operator's authoritative source context (kept as the single source of truth — not
+duplicated here to avoid drift), tagging the V2 image:
+```
+docker build -t ordo-v2/codebase-memory-mcp:latest C:/dev/ordo-ai-stack/codebase-memory-mcp
+```
+
+This image is gateway-spawned (stdio) and kept warm (`longLived: true`) so its in-memory graph
+survives across calls within a session. It appears in the rendered `mcp-registry.yaml`, not as a
+long-lived compose service. A fresh spawn starts with an EMPTY graph — call `index_repository`
+once per session (against `/c/dev/<repo>`) before structural queries; the index also persists in
+the `codebase-memory-cache` named volume.

v2/docker/comfyui-mcp/README.md

@@ -0,0 +1,22 @@
+# comfyui-mcp (ComfyUI MCP server)
+
+V2's ComfyUI MCP image, referenced by the `comfyui` plugin as `ordo-v2/comfyui-mcp:latest`.
+V1 builds it locally (`ordo-ai-stack-comfyui-mcp:latest`) from `C:\dev\ordo-ai-stack\comfyui-mcp`
+— the upstream `joenorton/comfyui-mcp-server` (pinned to commit `e0101b2312f3`) plus the stack's
+overrides (stdio-clean `print()` redirect, flat `run_workflow` args + default workflow, custom-node
+pip + comfyui-restart tools via ops-controller, and system-state tools: GPU / queue / models /
+nodes / extensions). It talks to `http://comfyui:8188` and `http://ops-controller:9000`. There is
+no public registry to digest-pin against, so it's a **project buildable image** (pinned by its
+build context); `ordo preflight` reports a missing one as "build first".
+
+## Build
+Build from the operator's authoritative source context (kept as the single source of truth — not
+duplicated here to avoid drift), tagging the V2 image:
+```
+docker build -t ordo-v2/comfyui-mcp:latest C:/dev/ordo-ai-stack/comfyui-mcp
+```
+
+This image is gateway-spawned (stdio), so it appears in the rendered `mcp-registry.yaml`, not as a
+long-lived compose service. It needs network access to reach `comfyui:8188` (`disableNetwork`
+unset). `COMFY_MCP_DEFAULT_MODEL` + `OPS_CONTROLLER_TOKEN` are substituted from the gateway env
+into its catalog entry at gateway startup.

v2/docker/orchestration-mcp/README.md

@@ -0,0 +1,26 @@
+# orchestration-mcp (Stable orchestration adapter)
+
+V2's Orchestration MCP image, referenced by the `orchestration` plugin as
+`ordo-v2/orchestration-mcp:latest`. V1 builds it locally
+(`ordo-ai-stack-orchestration-mcp:latest`) from `C:\dev\ordo-ai-stack\orchestration-mcp` — a thin
+adapter exposing STABLE tool names (list_templates / create_from_template / run_workflow /
+await_run / list_jobs / publish_enqueue / schedules / registry parity verbs / comfyui ops …) that
+delegate over HTTP to the dashboard control plane at `http://dashboard:8080/api/orchestration/*`
+(Bearer `DASHBOARD_AUTH_TOKEN`). It insulates the agent from shifting raw gateway tool names.
+There is no public registry to digest-pin against, so it's a **project buildable image** (pinned by
+its build context); `ordo preflight` reports a missing one as "build first".
+
+Backing verified in V2: the `ordo-v2/dashboard-v1` image serves `/api/orchestration/*`
+(readiness probe returns `ok`), so this adapter's target exists in the V2 stack.
+
+## Build
+Build from the operator's authoritative source context (kept as the single source of truth — not
+duplicated here to avoid drift), tagging the V2 image:
+```
+docker build -t ordo-v2/orchestration-mcp:latest C:/dev/ordo-ai-stack/orchestration-mcp
+```
+
+This image is gateway-spawned (stdio), so it appears in the rendered `mcp-registry.yaml`, not as a
+long-lived compose service. It needs network access to reach `dashboard:8080` (`disableNetwork`
+unset). `DASHBOARD_AUTH_TOKEN` is substituted from the gateway env into its catalog entry at
+gateway startup.

v2/ordo/compose.py

@@ -235,6 +235,20 @@ def _mcp_gateway(project: str, net: str, env_file: str) -> dict[str, Any]:
         "COMFYUI_URL": "http://comfyui:8188",
         "N8N_API_URL": "http://n8n:5678",
         "CODE_ROOT": "${CODE_ROOT:-/c/dev}",
+        # Bind-mount allowlist for the SPAWNED sibling MCP servers. The gateway's hardened bind logic
+        # only accepts host binds whose source is on this list (and read-only). codebase-memory mounts
+        # $CODE_ROOT read-only at /c/dev, so the allowlist must contain CODE_ROOT — else the gateway
+        # rejects the mount and the codebase-memory server fails to spawn. Mirrors V1's gateway env.
+        "MCP_GATEWAY_DOCKER_BIND_ALLOWED_PATHS": "${CODE_ROOT:-/c/dev}",
+        # ComfyUI MCP's default checkpoint (a non-secret default, safe to interpolate from .env-space).
+        # The other secrets the spawned MCP servers need — OPS_CONTROLLER_TOKEN (comfyui),
+        # DASHBOARD_AUTH_TOKEN (orchestration), N8N_API_KEY (n8n) — are NOT declared here on purpose:
+        # they arrive via the `secrets.env` env_file (already layered on this service). Re-declaring
+        # them in `environment:` with `${VAR:-}` would interpolate from .env/host (where they're
+        # absent → empty) and SHADOW the env_file value to empty. gateway-wrapper.sh reads them from
+        # the process env (env_file) to substitute the PLACEHOLDER_* tokens + build the --secrets
+        # dotenv, so env_file delivery is sufficient and correct.
+        "COMFY_MCP_DEFAULT_MODEL": "${COMFY_MCP_DEFAULT_MODEL:-flux1-schnell-fp8.safetensors}",
         # HOST path of the shared markdown memory vault. The wrapper substitutes it into the
         # memory-vault MCP's catalog volume (PLACEHOLDER_MEMORY_VAULT_PATH) so the SPAWNED sibling
         # container binds the same host dir native Obsidian (opened at this path) + host seeding

v2/ordo/render.py

@@ -393,6 +393,7 @@ def _render_mcp(mcps: list, project: str = "ordo-v2") -> tuple[list[dict[str, An
     project images (ordo-v2/*) are exempt: they're pinned by build context, not registry digest."""
     servers: list[dict[str, Any]] = []
     notes: list[str] = []
+    seen_ids: dict[str, str] = {}
     for p in mcps:
         image = str(p.mcp.get("image", ""))
         digest = image.split("@sha256:")[-1] if "@sha256:" in image else ""
@@ -402,8 +403,17 @@ def _render_mcp(mcps: list, project: str = "ordo-v2") -> tuple[list[dict[str, An
             notes.append(f"mcp '{p.id}': image is not digest-pinned — refuse in production")
         elif len(set(digest)) <= 1:  # placeholder like 000.../111...
             notes.append(f"mcp '{p.id}': image digest is a placeholder — set the real sha256")
+        # The gateway registry key (servers.txt id + tool-namespace prefix Hermes sees, e.g.
+        # `comfyui__system_stats`) defaults to the plugin id. A plugin may set mcp.server_id to
+        # DECOUPLE that key from its plugin id — needed when a kind=service plugin already owns the
+        # bare name (the comfyui SERVICE plugin owns `comfyui`, so its MCP plugin is id `comfyui-mcp`
+        # but keeps server_id `comfyui` to preserve V1's `comfyui__*` tool namespace).
+        server_id = str(p.mcp.get("server_id") or p.id)
+        if server_id in seen_ids:
+            notes.append(f"mcp '{p.id}': server_id '{server_id}' collides with plugin '{seen_ids[server_id]}'")
+        seen_ids[server_id] = p.id
         servers.append({
-            "id": p.id, "name": p.name, "image": image,
+            "id": server_id, "name": p.name, "image": image,
             "env": dict(p.mcp.get("env", {}) or {}),
             "tools": list(p.mcp.get("tools", []) or []),
             # Optional gateway-catalog passthrough (file-based MCP servers): a host bind for the data

v2/plugins/codebase-memory/plugin.yaml

@@ -0,0 +1,57 @@
+# Plugin manifest — data-only. Registers the codebase-memory MCP server (agent tool), not a compose
+# service. Gives Hermes a code KNOWLEDGE GRAPH over the repos under the code root (mounted read-only
+# at /c/dev): structural queries grep can't do cheaply — call graphs, trace paths between symbols,
+# architecture overviews, symbol/snippet lookup. Ports V1's registry-custom.yaml `codebase-memory`
+# entry (the source of truth for its wiring). Companion to the codebase-memory-UI (3D graph) service,
+# but a SEPARATE process: this gateway-spawned MCP builds its own IN-MEMORY graph per spawn, so a
+# fresh session starts empty until index_repository is called (see the codebase-memory Hermes skill).
+id: codebase-memory
+name: Codebase Memory (MCP tools)
+description: Code knowledge-graph navigation (call graphs, trace paths, architecture, snippets) over the repos under the code root, via MCP.
+kind: mcp                  # registers an MCP server (agent tool), not a compose service
+requires:
+  nvidia: false            # bundled offline embeddings run on CPU — no GPU
+  ram_gb: 2
+provides: [tools]
+mcp:
+  # V1 builds this locally (ordo-ai-stack-codebase-memory-mcp:latest) from a self-contained Dockerfile
+  # that downloads + sha256-verifies the pinned DeusData/codebase-memory-mcp portable binary and bundles
+  # the offline nomic-embed-code embeddings. V2 mirrors it as a project buildable image (build context
+  # doc under v2/docker/codebase-memory-mcp): pinned by its build context (the Dockerfile's CBM_VERSION
+  # + CBM_SHA256), so preflight reports 'build first', not a placeholder-digest warning.
+  image: ordo-v2/codebase-memory-mcp:latest
+  # Keep the indexer container WARM across calls within a session — the graph is in-memory per spawn,
+  # so this preserves an index built via index_repository until the session ends (avoids re-index).
+  longLived: true
+  # The indexer is 100% local (bundled embeddings) — no egress needed. Blocks exfiltration of indexed
+  # code from the spawned container.
+  disableNetwork: true
+  volumes:
+    # Code root (HOST path from $CODE_ROOT) mounted READ-ONLY. Under the gateway's bind-mount hardening
+    # host binds must be read-only AND allow-listed via MCP_GATEWAY_DOCKER_BIND_ALLOWED_PATHS (the
+    # gateway sets it to $CODE_ROOT). PLACEHOLDER_CODE_ROOT is substituted from the gateway's CODE_ROOT
+    # env by gateway-wrapper.sh (the gateway spawns this as a sibling via docker.sock, so the source
+    # must be a HOST path, not a gateway-container path).
+    - "PLACEHOLDER_CODE_ROOT:/c/dev:ro"
+    # Persistent SQLite index — a NAMED volume (exempt from the host-path read-only restriction, so it
+    # can be read-write). Survives container respawns.
+    - "codebase-memory-cache:/cache"
+  env:
+    CBM_CACHE_DIR: /cache
+    # Keep logs off stdout so they can't corrupt the stdio JSON-RPC channel.
+    CBM_LOG_LEVEL: error
+  tools:
+    - index_repository
+    - list_projects
+    - index_status
+    - search_graph
+    - trace_path
+    - query_graph
+    - get_graph_schema
+    - get_code_snippet
+    - get_architecture
+    - search_code
+    - detect_changes
+    - manage_adr
+    - ingest_traces
+    - delete_project

v2/plugins/comfyui-mcp/plugin.yaml

@@ -0,0 +1,42 @@
+# Plugin manifest — data-only. Registers the ComfyUI MCP server (agent tool), not a compose service.
+# The comfyui compose SERVICE is provided by the separate `comfyui` (kind=service) plugin; THIS plugin
+# only exposes ComfyUI's media tools (workflows, images, video, model pull, system stats, queue,
+# history, installed models/nodes/extensions) to Hermes via the gateway. Ports V1's registry-custom.yaml
+# `comfyui` entry (the source of truth for its wiring).
+#
+# Plugin id is `comfyui-mcp` (the service plugin already owns `comfyui`), but mcp.server_id pins the
+# GATEWAY registry key back to `comfyui` so Hermes keeps the V1 `comfyui__*` tool namespace.
+id: comfyui-mcp
+name: ComfyUI (MCP tools)
+description: ComfyUI media tools (workflows, images, video, model pull, system stats, queue, history, installed models/nodes/extensions) exposed to the agent via MCP.
+kind: mcp                  # registers an MCP server (agent tool), not a compose service
+requires:
+  nvidia: false            # the MCP is a thin HTTP client of comfyui:8188; the GPU work is comfyui's
+  ram_gb: 1
+provides: [tools]
+depends_on: [comfyui]      # queries the comfyui service (kind=service plugin) + ops-controller
+mcp:
+  # Gateway registry key + Hermes tool-namespace prefix (comfyui__*). Decoupled from the plugin id so
+  # it stays `comfyui` even though the plugin is `comfyui-mcp` (the comfyui SERVICE plugin owns the id).
+  server_id: comfyui
+  # V1 builds this locally (ordo-ai-stack-comfyui-mcp:latest). V2 mirrors it as a project buildable
+  # image (build context doc under v2/docker/comfyui-mcp): pinned by its build context (upstream commit
+  # e0101b2312f3 + stack overrides), so preflight reports 'build first' rather than a digest warning.
+  image: ordo-v2/comfyui-mcp:latest
+  # Needs network access to reach comfyui:8188 + ops-controller:9000 on ordo-v2-net — NOT offline.
+  disableNetwork: false
+  env:
+    COMFYUI_URL: http://comfyui:8188
+    OPS_CONTROLLER_URL: http://ops-controller:9000
+    # Substituted from the gateway env by gateway-wrapper.sh at startup (secrets stay out of the
+    # committed catalog; the gateway holds the real value from secrets.env).
+    OPS_CONTROLLER_TOKEN: PLACEHOLDER_OPS_CONTROLLER_TOKEN
+    COMFY_MCP_DEFAULT_MODEL: PLACEHOLDER_COMFY_MCP_DEFAULT_MODEL
+  # Representative read-only tools (the image registers the full set via register_system_tools /
+  # register_management_tools / register_workflow_tools); the gateway advertises everything at runtime.
+  tools:
+    - get_system_stats
+    - get_queue
+    - get_installed_models
+    - list_workflows
+    - run_workflow

v2/plugins/n8n/plugin.yaml

@@ -0,0 +1,45 @@
+# Plugin manifest — data-only. Registers the n8n MCP server (agent tool), not a compose service.
+# The n8n compose SERVICE is provided by the separate `automation` (kind=service) plugin; THIS plugin
+# only bridges the local n8n instance + the czlonkowski/n8n-mcp node & template catalog to Hermes via
+# the gateway. Ports V1's registry-custom.yaml `n8n` entry (the source of truth for its wiring).
+id: n8n
+name: n8n workflow automation (MCP tools)
+description: n8n workflow automation exposed to the agent via MCP — bridges the local n8n instance plus the full czlonkowski/n8n-mcp node and template catalog.
+kind: mcp                  # registers an MCP server (agent tool), not a compose service
+requires:
+  nvidia: false
+  ram_gb: 1
+provides: [tools]
+depends_on: [automation]   # queries the n8n service (automation kind=service plugin)
+# N8N_API_KEY is an operator secret (n8n personal API token). Declaring it here emits the key into
+# secrets.env.example; the rendered compose reads secrets.env as a second env_file, so the gateway
+# has $N8N_API_KEY in its env and gateway-wrapper.sh (1) substitutes PLACEHOLDER_N8N_API_KEY into this
+# catalog entry AND (2) writes n8n.api_key into the gateway's --secrets dotenv so the n8n_* instance
+# tools register (not just the docs-only subset).
+secrets:
+  - N8N_API_KEY
+mcp:
+  # Upstream czlonkowski/n8n-mcp image (mcp/n8n). Digest-pinned so the gateway resolves it from THIS
+  # catalog, never Docker's unpinned online catalog (the orphan-container/drift source V1 suffered).
+  image: mcp/n8n@sha256:061cdb8fbaa78f5a09787338715b180a0759057759f402c473b5f6ee13a8709e
+  # Needs network access to reach n8n:5678 — NOT offline.
+  disableNetwork: false
+  env:
+    N8N_API_URL: http://n8n:5678
+    # Substituted from the gateway's $N8N_API_KEY (sourced from secrets.env) by gateway-wrapper.sh.
+    N8N_API_KEY: PLACEHOLDER_N8N_API_KEY
+    # CRITICAL: silence the image's box-drawing startup banner + INFO logs. With stdio transport ANY
+    # non-JSON-RPC byte before the response makes the gateway crash ('invalid character') OR collapses
+    # the tool set to the docs-only ~23 instead of the full ~42. See project memory
+    # [project_ordo_n8n_mcp_image_docs_only].
+    LOG_LEVEL: error
+    N8N_DIAGNOSTICS_ENABLED: "false"
+    DISABLE_TELEMETRY: "true"
+  # Representative tools (the image registers the full czlonkowski catalog + n8n_* instance verbs when
+  # the API key is present); the gateway advertises the full set at runtime.
+  tools:
+    - list_nodes
+    - get_node_info
+    - search_templates
+    - n8n_list_workflows
+    - n8n_create_workflow

v2/plugins/orchestration/plugin.yaml

@@ -0,0 +1,38 @@
+# Plugin manifest — data-only. Registers the orchestration MCP server (agent tool), not a compose
+# service. A STABLE adapter: exposes fixed verb names (list_templates / create_from_template /
+# run_workflow / await_run / list_jobs / publish_enqueue / schedules / registry parity verbs /
+# comfyui ops …) that delegate over HTTP to the dashboard control plane, insulating Hermes from
+# shifting raw gateway tool names. Ports V1's registry-custom.yaml `orchestration` entry (the source
+# of truth for its wiring). Backing verified in V2: ordo-v2/dashboard-v1 serves /api/orchestration/*.
+id: orchestration
+name: Orchestration (MCP tools)
+description: Stable orchestration adapter (fixed verbs; delegates to the dashboard /api/orchestration control plane, not shifting gateway tool names).
+kind: mcp                  # registers an MCP server (agent tool), not a compose service
+requires:
+  nvidia: false
+  ram_gb: 1
+provides: [tools]
+# No plugin-level depends_on: the target is the CORE `dashboard` service (always present, not a
+# plugin), so there's no plugin dependency to gate on. (A plugin `depends_on` must name an enabled
+# PLUGIN or the plugin is dropped; `dashboard` is core, so listing it would wrongly drop this MCP.)
+mcp:
+  # V1 builds this locally (ordo-ai-stack-orchestration-mcp:latest). V2 mirrors it as a project
+  # buildable image (build context doc under v2/docker/orchestration-mcp): pinned by its build context,
+  # so preflight reports 'build first' rather than a digest warning.
+  image: ordo-v2/orchestration-mcp:latest
+  # Needs network access to reach dashboard:8080 — NOT offline.
+  disableNetwork: false
+  env:
+    ORCHESTRATION_DASHBOARD_URL: http://dashboard:8080
+    # Bearer for the dashboard control plane. Substituted from the gateway's $DASHBOARD_AUTH_TOKEN
+    # (sourced from secrets.env) by gateway-wrapper.sh at startup.
+    DASHBOARD_AUTH_TOKEN: PLACEHOLDER_DASHBOARD_AUTH_TOKEN
+  tools:
+    - orchestration_readiness
+    - list_templates
+    - run_workflow
+    - await_run
+    - list_jobs
+    - comfyui_status
+    - list_models
+    - gpu_status