superclaude mcp --servers airis-mcp-gateway fails: stale compose URL (404) + missing config-file provisioning

superclaude mcp --servers airis-mcp-gateway fails: stale compose URL (404) + missing config-file provisioning

Summary

Installing the AIRIS MCP Gateway via superclaude mcp --servers airis-mcp-gateway fails out of the box. There are two independent bugs in superclaude/cli/install_mcp.py; the first masks the second.

• Version: SuperClaude 4.3.0 (pipx)
• OS: Linux (Manjaro, kernel 6.18), Docker available, non-root user
• Command: superclaude mcp --servers airis-mcp-gateway

Bug 1 — Stale docker_compose_url returns 404

The hardcoded compose URL points at a filename the upstream gateway repo has since renamed:

# superclaude/cli/install_mcp.py
"docker_compose_url": "https://raw.githubusercontent.com/agiletec-inc/airis-mcp-gateway/main/docker-compose.dist.yml",

agiletec-inc/airis-mcp-gateway renamed docker-compose.dist.yml → compose.yaml (still on the main branch). The old path now 404s:

docker-compose.dist.yml  -> 404
compose.yaml             -> 200

Observed output

 Downloading docker-compose configuration...
❌ Failed to download docker-compose file: curl: (22) The requested URL returned error: 404
Failed to install AIRIS MCP Gateway

Fix

- "docker_compose_url": "https://raw.githubusercontent.com/agiletec-inc/airis-mcp-gateway/main/docker-compose.dist.yml",
+ "docker_compose_url": "https://raw.githubusercontent.com/agiletec-inc/airis-mcp-gateway/main/compose.yaml",

(The companion mcp_config_url → config/mcp-config.template.json is still valid and needs no change.)

Bug 2 — Installer does not provision the config files the compose file bind-mounts

After fixing Bug 1, the download succeeds but docker compose up fails at container start:

❌ Failed to start containers:
Error response from daemon: failed to create task for container: ... OCI runtime create failed:
... error mounting ".../config/gateway-config.yaml" to rootfs at "/app/config/gateway-config.yaml":
... not a directory: Are you trying to mount a directory onto a file (or vice-versa)?

Root cause

The installer only writes three files into the install dir: compose.yaml (saved as docker-compose.yml), mcp-config.json, and .env. But the current compose.yaml bind-mounts several additional host files that the installer never creates:

# api service
volumes:
  - ./routing-table.json:/app/routing-table.json:ro
  - ./config/gateway-config.yaml:/app/config/gateway-config.yaml:ro
  - ./profiles:/app/profiles:rw
# docker-mcp-gateway service
command:
  - --additional-catalog=/catalogs/airis-catalog.yaml   # needs ./catalogs/airis-catalog.yaml

When a bind-mount source path does not exist on the host, the Docker daemon (running as root) auto-creates it — and creates it as a directory. So config/gateway-config.yaml and routing-table.json get created as empty, root-owned directories, and mounting a directory onto the container's expected file path fails. (This also leaves root-owned junk in ~/.superclaude/airis-mcp-gateway/ that a non-root user cannot clean up without sudo or a root container.)

Files the compose requires but the installer never provisions:

All of these exist in the upstream repo at main:

• config/gateway-config.yaml
• routing-table.json
• catalogs/airis-catalog.yaml
• config/profiles/{minimal,recommended}.json

Suggested fix

Download the required config files alongside compose.yaml/mcp-config.json before running docker compose up (same pattern already used for mcp-config.json). At minimum:

• config/gateway-config.yaml → <install_dir>/config/gateway-config.yaml
• routing-table.json → <install_dir>/routing-table.json
• catalogs/airis-catalog.yaml → <install_dir>/catalogs/airis-catalog.yaml
• config/profiles/*.json → <install_dir>/profiles/

Alternatively, run the gateway repo's own bootstrap (scripts/airis_bootstrap.py) rather than hand-rolling a partial subset of its install in SuperClaude — that keeps SuperClaude from drifting every time the gateway changes its file layout (as happened with Bug 1).

Also consider creating the known directories (config/, catalogs/, profiles/, workflows/) explicitly before docker compose up, so Docker never silently creates root-owned paths.

Manual workaround (for anyone hitting this now)

1. Edit install_mcp.py to change docker-compose.dist.yml → compose.yaml.
2. Fetch the missing files from the gateway repo (config/gateway-config.yaml, routing-table.json, catalogs/airis-catalog.yaml, config/profiles/*.json).
3. Remove the root-owned placeholder dirs Docker created and drop the real files in their place (a one-off docker run --rm -v <install_dir>:/d alpine ... does this without sudo and can chown -R back to your uid).
4. Re-run superclaude mcp --servers airis-mcp-gateway.

After this, all four containers (airis-mcp-gateway, airis-serena, mindbase-postgres-dev, airis-docker-mcp-gateway) come up healthy and /ready returns {"ready":true,...}.