@xns-cloud/relayer-mcp 0.3.0 → 0.5.0

package/README.md

@@ -1,10 +1,30 @@
 # @xns-cloud/relayer-mcp
 
-MCP server for XNS Relayer onboarding. Provides 10 tools that let an AI agent drive the complete Relayer setup conversationally over stdio transport.
+MCP server for XNS Relayer onboarding. Provides 11 tools that let an AI agent drive the complete Relayer setup conversationally over stdio transport.
 
-## Claude Desktop Configuration
+## Requirements
 
-Add to your Claude Desktop `claude_desktop_config.json`:
+- **Node.js 20+** — see [Installing Node.js 20](#installing-nodejs-20) if your distro ships an older version.
+- **Docker Engine** — on the same machine, or on a remote host via a Docker context (see [Remote Docker hosts](#remote-docker-hosts)).
+
+### Installing Node.js 20
+
+Ubuntu's default apt repository only ships Node 18, which is too old. Two ways to get Node 20:
+
+**nvm** (recommended — no root required):
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+\. "$HOME/.nvm/nvm.sh" && nvm install 20
+```
+
+**NodeSource** (system-wide): follow <https://github.com/nodesource/distributions#installation-instructions>.
+
+If you start the MCP on an older Node, it exits immediately with this same guidance instead of a dependency stack trace.
+
+## Claude Desktop / Claude Code Configuration
+
+Add to your `claude_desktop_config.json` (or `claude mcp add relayer -- npx @xns-cloud/relayer-mcp@latest` for Claude Code):
 
 ```json
 {
@@ -23,16 +43,17 @@ No separate install step required.
 
 | # | Tool | Purpose |
 |---|------|---------|
-| 1 | `check_prerequisites` | Verify Docker, ports (8888, 9000), disk, and network connectivity. |
+| 1 | `check_prerequisites` | Verify Docker (local or remote), ports (8888, 9000), an existing installation, disk, and network connectivity. |
 | 2 | `register_account` | Register an XNS account (email + password) via Console2. |
 | 3 | `check_email_verified` | Poll email verification status (15s interval, 30-min timeout). |
-| 4 | `install_relayer` | Write the bundled `docker-compose.yml` + `.env` (Docker Hub `scprime/xns-relayer`, pre-release `:beta` channel) and start the containers. The user authors nothing; `compose_url` is an optional override. |
-| 5 | `check_relayer_health` | Poll UI, S3, and HostIO health (10s interval, 300s timeout). |
+| 4 | `install_relayer` | Fetch the canonical beta channel bundle — relayer + Prometheus/Grafana monitoring stack (`https://releases.scpri.me/relayer/beta/docker-compose.yml`, anonymous pull, no `docker login`) — write the `.env`, and start the containers. Falls back to a bundled service-parity copy if the fetch fails. **Fresh installs only** — see [Fresh installs vs. existing deployments](#fresh-installs-vs-existing-deployments). The user authors nothing; `compose_url` is an optional override for custom installs. |
+| 5 | `check_relayer_health` | Poll UI, S3, HostIO, and the monitoring sidecars (10s interval, 300s timeout). A missing monitoring stack reports as degraded without blocking the flow. Targets the Docker host automatically. |
 | 6 | `start_claim` | Initiate a claim session — returns a URL for browser confirmation. |
 | 7 | `check_claim_status` | Poll claim state (STATE_1 / STATE_2 / STATE_3). |
 | 8 | `get_host_tags` | Retrieve available host tags for VPD configuration. |
 | 9 | `configure_vpd` | Set data/parity host selection via CEL expressions. |
-| 10 | `verify_storage` | Round-trip S3 test (create bucket, put object, get object) at localhost:9000. |
+| 10 | `verify_storage` | Round-trip S3 test (create bucket, put object, get object) against the S3 gateway on port 9000. |
+| 11 | `setup_cli_credentials` | Provision S3 IAM credentials and write `~/.xns/credentials` so the XNS CLI works without further configuration. |
 
 ## Onboarding Flow
 
@@ -45,9 +66,50 @@ No separate install step required.
 6. Agent initiates claim; user opens claim URL in browser (Tools 6 + 7).
 7. Agent signs in via OIDC to configure host preferences (Tools 8 + 9).
 8. Agent verifies S3 storage is working (Tool 10).
+9. Optionally, agent provisions CLI credentials (Tool 11).
 
 The operator's only required actions are: clicking one email link, completing one browser sign-in, and confirming one claim.
 
+## Fresh installs vs. existing deployments
+
+`install_relayer` performs **fresh installs only** — it does not upgrade an existing deployment in place. Docker container names are unique per daemon, so any existing `xns-relayer` container (running **or stopped**, any channel — including an alpha-channel install from `releases.scpri.me`) blocks the install. Both `check_prerequisites` and `install_relayer` detect this and tell you before anything breaks.
+
+To replace an existing deployment:
+
+```bash
+docker stop xns-relayer && docker rm xns-relayer   # does NOT delete the data directory
+```
+
+then run `install_relayer` again. To keep the existing deployment, skip `install_relayer` and continue onboarding against it (`check_relayer_health` onwards).
+
+## Remote Docker hosts
+
+Claude Code doesn't have to run on the Docker machine. If you run it on a management node or jump host, point the Docker CLI at the remote server with an SSH context:
+
+```bash
+docker context create relayer --docker "host=ssh://user@docker-box"
+docker context use relayer
+```
+
+(Requires the `docker` CLI on the management node — the [static binary](https://docs.docker.com/engine/install/binaries/) is enough — and SSH key access to the Docker host.)
+
+The MCP detects this automatically (it honors `DOCKER_HOST` and the active Docker context):
+
+- `install_relayer` runs `docker compose` against the remote daemon.
+- `check_relayer_health` and `verify_storage` probe the **remote host's** ports 8888/9000 instead of localhost — make sure those are reachable from the management node.
+- `check_prerequisites` skips the local port-availability probes (the containers bind ports on the remote host) and reports them as skipped with instructions.
+
+`check_relayer_health` accepts a `host` override, and `verify_storage` an `endpoint` override, for setups the auto-detection can't see (port forwards, NAT).
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| MCP exits with "requires Node.js 20 or newer" | Distro Node is too old (Ubuntu apt ships Node 18) | [Installing Node.js 20](#installing-nodejs-20) |
+| `install_relayer` reports an existing `xns-relayer` container | A previous deployment (any channel) owns the container name | [Fresh installs vs. existing deployments](#fresh-installs-vs-existing-deployments) |
+| Port 8888/9000 already in use | Another service on the Docker host (another S3-compatible service squatting 9000) | Stop it, or install with custom ports: `install_relayer` `ui_port` / `s3_port` (health checks accept the same) |
+| Health checks fail but containers run on a remote Docker host | Ports 8888/9000 not reachable from the management node | Open them, or pass `host` / `endpoint` overrides |
+
 ## Authentication
 
 Tools 8 and 9 require an OIDC token to access the HostIO proxy. The MCP acquires one automatically using Authorization Code + PKCE (S256) flow against the `scprime` Keycloak realm with the `relayer-native` public client. The user completes a browser sign-in; the MCP captures the code on a local `127.0.0.1` loopback listener and exchanges it for a token.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xns-cloud/relayer-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "MCP server for XNS Relayer onboarding — drives a complete Relayer setup conversationally over stdio, npx-ready",
   "author": "SCP Corp",
   "license": "Apache-2.0",
@@ -17,7 +17,8 @@
   },
   "scripts": {
     "test": "jest --verbose",
-    "start": "node src/index.js"
+    "start": "node src/index.js",
+    "prepublishOnly": "npm test"
   },
   "keywords": [
     "mcp",
@@ -46,7 +47,9 @@
     "jest": "^30.4.2"
   },
   "jest": {
-    "testMatch": ["**/src/__tests__/**/*.test.js"],
+    "testMatch": [
+      "**/src/__tests__/**/*.test.js"
+    ],
     "testEnvironment": "node",
     "forceExit": true
   }

package/src/index.js

@@ -1,12 +1,21 @@
 #!/usr/bin/env node
 'use strict';
 
+// Node 20+ guard — runs BEFORE the SDK loads so users on older runtimes get a
+// remediation message instead of a SyntaxError from a dependency.
+const { checkNodeVersion } = require('./lib/nodeVersion');
+const nodeCheck = checkNodeVersion(process.versions.node);
+if (!nodeCheck.ok) {
+    process.stderr.write(nodeCheck.message);
+    process.exit(1);
+}
+
 const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 
 const server = new McpServer({
     name: 'relayer-mcp',
-    version: '0.1.0',
+    version: require('../package.json').version,
 });
 
 // Register all 11 tools

package/src/lib/dockerUtil.js

@@ -2,6 +2,30 @@
 
 const { execFile: nodeExecFile } = require('child_process');
 
+/**
+ * Parse a Docker endpoint URL into { remote, host }.
+ *
+ * unix:// and npipe:// sockets are local by definition. ssh:// and tcp://
+ * point at another machine — unless the hostname is loopback. Anything
+ * unparseable falls back to local, matching pre-context behaviour.
+ *
+ * @param {string} endpoint - e.g. 'unix:///var/run/docker.sock', 'ssh://user@host'
+ * @returns {{remote: boolean, host: string}}
+ */
+function parseDockerEndpoint(endpoint) {
+    const local = { remote: false, host: 'localhost' };
+    if (!endpoint) return local;
+    if (endpoint.startsWith('unix://') || endpoint.startsWith('npipe://')) return local;
+    try {
+        const { hostname } = new URL(endpoint);
+        // URL.hostname keeps IPv6 brackets: 'tcp://[::1]:2375' → '[::1]'
+        if (!hostname || ['localhost', '127.0.0.1', '[::1]'].includes(hostname)) return local;
+        return { remote: true, host: hostname };
+    } catch {
+        return local;
+    }
+}
+
 /**
  * Docker utility — runs Docker CLI commands using execFile (no shell).
  * Security non-negotiable: NEVER use exec() or spawn({ shell: true }).
@@ -9,9 +33,11 @@ const { execFile: nodeExecFile } = require('child_process');
  *
  * @param {object} [options]
  * @param {function} [options.execFile] - Injected execFile (testing)
+ * @param {object} [options.env] - Injected environment (testing); defaults to process.env
  */
 function createDockerUtil(options = {}) {
     const _execFile = options.execFile || nodeExecFile;
+    const _env = options.env || process.env;
 
     /**
      * Run a docker command with args.
@@ -62,7 +88,62 @@ function createDockerUtil(options = {}) {
         }
     }
 
-    return { docker, composeUp, isContainerRunning };
+    /**
+     * Find a container by EXACT name — running or stopped. A stopped container
+     * still owns its name and still breaks `docker compose up`, so callers
+     * doing install preflight must use this, not isContainerRunning.
+     *
+     * Best-effort: if docker itself is unreachable, returns null and lets the
+     * caller's real docker command surface the error.
+     *
+     * @param {string} name - Exact container name
+     * @returns {Promise<{name: string, status: string, image: string, running: boolean}|null>}
+     */
+    async function findContainer(name) {
+        try {
+            // docker ps --filter name= treats the value as a regex — escape
+            // metacharacters (names may contain '.') so the anchor stays exact.
+            const escaped = String(name).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const { stdout } = await docker([
+                'ps', '-a',
+                '--filter', `name=^${escaped}$`,
+                '--format', '{{.Names}}\t{{.Status}}\t{{.Image}}',
+            ]);
+            const line = stdout.trim().split('\n').filter(Boolean)[0];
+            if (!line) return null;
+            const [foundName, status = '', image = ''] = line.split('\t');
+            return { name: foundName, status, image, running: status.toLowerCase().startsWith('up') };
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Resolve which machine the Docker daemon actually runs on.
+     *
+     * Claude Code may run on a management node with the Docker CLI pointed at a
+     * separate server (DOCKER_HOST or an ssh:// docker context). Tools that
+     * probe ports or hit http://localhost must target THIS host instead.
+     *
+     * Precedence mirrors the Docker CLI: DOCKER_HOST env var wins, then the
+     * active context's endpoint. Unparseable/missing → local.
+     *
+     * @returns {Promise<{remote: boolean, host: string, endpoint: string|null}>}
+     */
+    async function getDockerHost() {
+        if (_env.DOCKER_HOST) {
+            return { ...parseDockerEndpoint(_env.DOCKER_HOST), endpoint: _env.DOCKER_HOST };
+        }
+        try {
+            const { stdout } = await docker(['context', 'inspect', '--format', '{{.Endpoints.docker.Host}}']);
+            const endpoint = stdout.trim();
+            return { ...parseDockerEndpoint(endpoint), endpoint: endpoint || null };
+        } catch {
+            return { remote: false, host: 'localhost', endpoint: null };
+        }
+    }
+
+    return { docker, composeUp, isContainerRunning, findContainer, getDockerHost };
 }
 
-module.exports = { createDockerUtil };
+module.exports = { createDockerUtil, parseDockerEndpoint };

package/src/lib/nodeVersion.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// Keep this file's syntax conservative — it must PARSE on old Node versions
+// (Ubuntu's default apt repo ships Node 18) so the friendly message below is
+// what the user sees, not a SyntaxError from a dependency.
+
+const MIN_MAJOR = 20;
+
+/**
+ * Check a Node.js version string against the package's engines floor.
+ *
+ * @param {string} version - e.g. process.versions.node ('18.19.1')
+ * @returns {{ok: boolean, major: number, message: string|null}}
+ */
+function checkNodeVersion(version) {
+    const major = parseInt(String(version).split('.')[0], 10) || 0;
+    if (major >= MIN_MAJOR) {
+        return { ok: true, major, message: null };
+    }
+    const message = [
+        `relayer-mcp requires Node.js ${MIN_MAJOR} or newer — you are running v${version}.`,
+        '',
+        "Ubuntu's default apt repository only ships Node 18. Install Node 20 with nvm:",
+        '',
+        '  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash',
+        '  \\. "$HOME/.nvm/nvm.sh" && nvm install 20',
+        '',
+        'Or via NodeSource: https://github.com/nodesource/distributions#installation-instructions',
+        '',
+    ].join('\n');
+    return { ok: false, major, message };
+}
+
+module.exports = { checkNodeVersion, MIN_MAJOR };

package/src/templates/docker-compose.yml

@@ -1,27 +1,77 @@
-# Bundled by @xns-cloud/relayer-mcp — the documented released XNS Relayer install.
-# Source of truth: https://xns.tech/docs/windows-ui/ (Docker Hub scprime/xns-relayer).
+# Bundled by @xns-cloud/relayer-mcp — OFFLINE FALLBACK for the released install.
+# Source of truth: the beta channel bundle on the XNS releases registry —
+# https://releases.scpri.me/relayer/beta/docker-compose.yml (versioned in the
+# deploy repo, shipped by `deploy.py promote`). install_relayer fetches that URL
+# by default and only writes this copy when the fetch fails, so this file MUST
+# keep service parity with the channel bundle: relayer + the monitoring stack
+# (Prometheus + Grafana + node-exporter) that powers the dashboards under
+# Monitoring in the web UI. The jest contract tests enforce the parity.
 #
-# Pre-release: pinned to the :beta channel so alpha/beta testers exercise the
-# current Relayer agentically. Flip this one tag to :stable at general release.
+# NEVER point an image at Docker Hub scprime/* — those are production fleet
+# tags, not a release channel. The one allowed upstream image is
+# prom/node-exporter (public, multi-arch, version-pinned — matches the channel
+# bundle; nothing to rebuild).
 #
-# A first-time user no longer hand-writes this file or the .env — install_relayer
-# writes both. Differences from the hand-written docs compose, by design:
-#   - data lives in ./data (relative to this file) instead of a Windows-only
-#     C:\XNS-Relayer bind, so the same file works on Windows, macOS, and Linux.
+# Pre-release: pinned to :beta-latest so beta testers exercise the current
+# Relayer agentically. Flip these tags to :stable-latest at general release.
+#
+# A first-time user never hand-writes this file or the .env — install_relayer
+# writes both. Differences from the channel compose, by design:
+#   - relayer data lives in ./data (relative to this file) instead of a named
+#     volume, so the same file works on Windows, macOS, and Linux and the data
+#     is easy to find next to the compose.
 #   - SMB ports 139/445 are intentionally NOT exposed: 445 is held by Windows
 #     SMB on consumer hosts and would fail the install. S3 onboarding uses :9000.
-#   - pull_policy: always so `docker compose up -d` fetches the current :beta
-#     image without a separate `docker compose pull` step.
+#   - pull_policy: always so `docker compose up -d` fetches the current beta
+#     images without a separate `docker compose pull` step.
 services:
   xns:
+    # container_name is load-bearing: the baked-in prometheus.yml scrapes the
+    # relayer by this name, and the install preflight keys on it.
     container_name: xns-relayer
-    image: scprime/xns-relayer:beta
+    image: releases.scpri.me/xns-relayer:beta-latest
     pull_policy: always
     restart: unless-stopped
+    privileged: true            # samba / fuse / disk management (matches channel compose)
     volumes:
       - ./data:/relayer
     ports:
       - ${UI_PORT:-8888}:8888
-      - ${MINIO_PORT:-9000}:9000
+      - ${S3_PORT:-9000}:9000
     env_file:
       - .env
+
+  # Monitoring stack — powers the dashboards under Monitoring in the web UI.
+  # Not host-exposed: Grafana is reached only through the relayer's /grafana
+  # reverse proxy and the in-network Prometheus scrape.
+  prometheus:
+    image: releases.scpri.me/relayer-prometheus:beta-latest
+    pull_policy: always
+    restart: unless-stopped
+    volumes:
+      - prometheus_data:/prometheus
+
+  grafana:
+    image: releases.scpri.me/relayer-grafana:beta-latest
+    pull_policy: always
+    restart: unless-stopped
+    environment:
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+      - GF_SERVER_SERVE_FROM_SUB_PATH=true
+      - GF_SERVER_ROOT_URL=%(protocol)s://%(domain)s/grafana
+      - GF_SECURITY_ALLOW_EMBEDDING=true
+    volumes:
+      - grafana_data:/var/lib/grafana
+
+  node-exporter:
+    image: prom/node-exporter:v1.11.1
+    restart: unless-stopped
+    command:
+      - --path.rootfs=/host
+    volumes:
+      - /:/host:ro            # read-only host metrics for the Node Health page
+
+volumes:
+  prometheus_data:
+  grafana_data:

package/src/tools/checkPrerequisites.js

@@ -35,7 +35,7 @@ module.exports = function registerCheckPrerequisites(server, options = {}) {
 
     server.tool(
         'check_prerequisites',
-        'Check system prerequisites for XNS Relayer installation: Docker availability, required ports (8888, 9000), disk space, and network connectivity to console.xns.tech and auth.xns.tech. Run this first before any other relayer tool.',
+        'Check system prerequisites for XNS Relayer installation: Docker availability (local or remote via DOCKER_HOST / ssh:// context), required ports (8888, 9000), an existing xns-relayer installation, disk space, and network connectivity to console.xns.tech and auth.xns.tech. Run this first before any other relayer tool.',
         {
             /* no parameters */
         },
@@ -43,26 +43,48 @@ module.exports = function registerCheckPrerequisites(server, options = {}) {
             const checks = [];
             let allPassed = true;
 
-            // 1. Docker available
+            // 1. Docker available — and WHERE it runs. With DOCKER_HOST or an
+            // ssh:// context (e.g. Claude Code on a jump host), the daemon is
+            // on another machine and the local checks below must adapt.
+            let dockerHost = { remote: false, host: 'localhost', endpoint: null };
             try {
                 await docker.docker(['info', '--format', '{{.ServerVersion}}']);
-                checks.push({ name: 'docker', passed: true, detail: 'Docker is running' });
+                dockerHost = await docker.getDockerHost();
+                checks.push({
+                    name: 'docker',
+                    passed: true,
+                    detail: dockerHost.remote
+                        ? `Docker is running on a remote host (${dockerHost.host}, via ${dockerHost.endpoint})`
+                        : 'Docker is running',
+                });
             } catch (err) {
                 allPassed = false;
                 checks.push({
                     name: 'docker',
                     passed: false,
                     detail: 'Docker is not available or not running',
-                    remediation: 'Install Docker Engine (https://docs.docker.com/engine/install/) and ensure the Docker daemon is running. On Linux: sudo systemctl start docker',
+                    remediation: 'Install Docker Engine (https://docs.docker.com/engine/install/) and ensure the Docker daemon is running. On Linux: sudo systemctl start docker. Remote daemon: create an SSH context — docker context create relayer --docker "host=ssh://user@host" && docker context use relayer',
                 });
             }
 
-            // 2-3. Required ports
+            // 2-3. Required ports. The bind-probe runs on THIS machine — when
+            // the Docker daemon is remote, the containers (and their port
+            // bindings) live on the remote host, so a local probe would test
+            // the wrong machine. Report skipped instead of a false answer.
             const requiredPorts = [
-                { port: 8888, name: 'port_8888', service: 'the Relayer UI', inUseRemediation: 'Port 8888 is required for the Relayer UI. Stop the service using this port or choose a different host.' },
-                { port: 9000, name: 'port_9000', service: 'the S3 gateway', inUseRemediation: 'Port 9000 is required for the S3 gateway. Stop the service using this port (common conflict: MinIO or another S3-compatible service).' },
+                { port: 8888, name: 'port_8888', service: 'the Relayer UI', inUseRemediation: 'Port 8888 is required for the Relayer UI. Stop the service using this port, or install with a different port via install_relayer ui_port.' },
+                { port: 9000, name: 'port_9000', service: 'the S3 gateway', inUseRemediation: 'Port 9000 is required for the S3 gateway. Stop the service using this port (common conflict: another S3-compatible service), or install with a different port via install_relayer s3_port.' },
             ];
             for (const { port, name, inUseRemediation } of requiredPorts) {
+                if (dockerHost.remote) {
+                    checks.push({
+                        name,
+                        passed: true,
+                        skipped: true,
+                        detail: `Port ${port} check skipped — the Docker daemon runs on ${dockerHost.host}, so port availability must be checked there (e.g. ss -tlnp | grep ${port} on that host).`,
+                    });
+                    continue;
+                }
                 try {
                     const available = await _checkPort(port);
                     if (available) {
@@ -77,6 +99,26 @@ module.exports = function registerCheckPrerequisites(server, options = {}) {
                 }
             }
 
+            // 3b. Existing installation. install_relayer is fresh-install only;
+            // an existing xns-relayer container (running or stopped, any
+            // channel) would fail it with a name conflict. Warn early, here.
+            try {
+                const existing = await docker.findContainer('xns-relayer');
+                if (existing) {
+                    checks.push({
+                        name: 'existing_install',
+                        passed: true,
+                        warning: true,
+                        detail: `An existing 'xns-relayer' container was found (status: ${existing.status}; image: ${existing.image}).`,
+                        remediation: 'install_relayer performs fresh installs only. To replace the existing deployment: docker stop xns-relayer && docker rm xns-relayer (data directory is preserved), then install. To keep it, skip install_relayer and continue onboarding against the running deployment.',
+                    });
+                } else {
+                    checks.push({ name: 'existing_install', passed: true, detail: 'No existing xns-relayer container — ready for a fresh install' });
+                }
+            } catch {
+                checks.push({ name: 'existing_install', passed: true, detail: 'Existing-install check skipped (Docker not reachable)' });
+            }
+
             // 4. Disk space (need at least 10 GB free — basic docker images + data)
             try {
                 await docker.docker(['system', 'df', '--format', '{{.TotalCount}}']);
@@ -91,6 +133,9 @@ module.exports = function registerCheckPrerequisites(server, options = {}) {
             const connectivityChecks = [
                 { url: 'https://console.xns.tech/health', name: 'connectivity_console', host: 'console.xns.tech' },
                 { url: 'https://auth.xns.tech/auth/realms/scprime/.well-known/openid-configuration', name: 'connectivity_auth', host: 'auth.xns.tech' },
+                // The registry install_relayer pulls from (beta channel, anonymous).
+                // /v2/ is the registry version probe — 200 without credentials.
+                { url: 'https://releases.scpri.me/v2/', name: 'connectivity_registry', host: 'releases.scpri.me' },
             ];
             for (const { url, name, host } of connectivityChecks) {
                 try {

package/src/tools/checkRelayerHealth.js

@@ -2,45 +2,89 @@
 
 const { z } = require('zod');
 const { createHttpClient } = require('../lib/httpClient');
+const { createDockerUtil } = require('../lib/dockerUtil');
 const { pollUntil } = require('../lib/pollUntil');
 
 const POLL_INTERVAL_MS = 10000;   // 10s
 const POLL_TIMEOUT_MS = 300000;   // 300s (AC-13, QA-1)
 
+// Loopback aliases — all classify as "local", not a remote Docker host.
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+/**
+ * Normalize a user-supplied or detected host for URL composition: trim, strip
+ * ANY accidental scheme prefix (http://, tcp://, ssh://…), bracket bare IPv6.
+ * Prevents invalid probe URLs (and false unhealthy reports) from inputs like
+ * 'http://docker-box.lan' or a pasted Docker endpoint 'tcp://10.0.0.5:2376'.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeHost(value) {
+    const trimmed = String(value).trim();
+    let hostname = trimmed;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+        try {
+            hostname = new URL(trimmed).hostname || trimmed; // keeps IPv6 brackets
+        } catch {
+            hostname = trimmed;
+        }
+    }
+    // Bare IPv6 → bracket it so http://${host}:${port} stays a valid URL.
+    return hostname.includes(':') && !hostname.startsWith('[') ? `[${hostname}]` : hostname;
+}
+
 /**
  * Tool 5: check_relayer_health
  * AC-13: report healthy only when ui+s3+hostio healthy; name unhealthy component; 300s timeout.
  * TP-31: hostio = null (not false) before auth — hostio health requires an authenticated
  * proxy call, so before OIDC sign-in we report hostio as null (unknown), not false (down).
+ *
+ * Remote Docker: when the Docker CLI points at another machine (DOCKER_HOST or
+ * an ssh:// context — e.g. Claude Code on a jump host), the containers run
+ * THERE, so health probes default to that host instead of localhost.
  */
 module.exports = function registerCheckRelayerHealth(server, options = {}) {
     const http = options.httpClient || createHttpClient(options);
+    const docker = options.dockerUtil || createDockerUtil(options);
     const pollInterval = options.pollIntervalMs ?? POLL_INTERVAL_MS;
     const pollTimeout = options.pollTimeoutMs ?? POLL_TIMEOUT_MS;
     const sleep = options.sleep;
 
     server.tool(
         'check_relayer_health',
-        'Check the health of all Relayer services: UI (port 8888), S3 gateway (port 9000), and HostIO. Polls every 10 seconds for up to 300 seconds. Reports each component status individually and names any unhealthy component. Note: HostIO health status is unknown until OIDC authentication is completed.',
+        'Check the health of all Relayer services: UI (port 8888), S3 gateway (port 9000), HostIO, and the monitoring sidecars (Prometheus + Grafana containers). Polls every 10 seconds for up to 300 seconds. Reports each component status individually and names any unhealthy component; a missing monitoring stack reports as degraded (dashboards empty) without blocking the install flow. Targets the machine the Docker daemon runs on (auto-detected from the Docker context — supports remote ssh:// Docker hosts); pass host to override. Note: HostIO health status is unknown until OIDC authentication is completed.',
         {
             poll: z.boolean().optional().default(true).describe('If true (default), poll until healthy or timeout. If false, check once.'),
+            host: z.string().trim().min(1).optional().describe('Hostname/IP where the Relayer containers run. Default: auto-detected from the Docker context (localhost, or the remote host for ssh:// / tcp:// contexts).'),
+            ui_port: z.number().int().positive().optional().default(8888).describe('Host port for the Relayer UI (matches install_relayer ui_port)'),
+            s3_port: z.number().int().positive().optional().default(9000).describe('Host port for the S3 API (matches install_relayer s3_port)'),
         },
-        async ({ poll }) => {
+        async ({ poll, host, ui_port, s3_port }) => {
             try {
+                // R1: zod fills defaults in production; ?? guards direct calls.
+                const uiPort = ui_port ?? 8888;
+                const s3Port = s3_port ?? 9000;
+                // Resolve where the containers actually run — once per call.
+                const dockerHost = host ? { host, remote: !LOCAL_HOSTS.has(normalizeHost(host)) } : await docker.getDockerHost();
+                const target = normalizeHost(dockerHost.host);
+                const uiBase = `http://${target}:${uiPort}`;
+                const s3Base = `http://${target}:${s3Port}`;
+
                 const checkOnce = async () => {
                     const components = {};
 
-                    // UI health (port 8888)
+                    // UI health
                     try {
-                        const { status } = await http.get('http://localhost:8888/health', { timeout: 5000 });
+                        const { status } = await http.get(`${uiBase}/health`, { timeout: 5000 });
                         components.ui = { healthy: status >= 200 && status < 500, status };
                     } catch {
                         components.ui = { healthy: false, status: null };
                     }
 
-                    // S3 gateway (port 9000)
+                    // S3 gateway
                     try {
-                        const { status } = await http.get('http://localhost:9000/', { timeout: 5000 });
+                        const { status } = await http.get(`${s3Base}/`, { timeout: 5000 });
                         components.s3 = { healthy: status >= 200 && status < 500, status };
                     } catch {
                         components.s3 = { healthy: false, status: null };
@@ -49,7 +93,7 @@ module.exports = function registerCheckRelayerHealth(server, options = {}) {
                     // HostIO — requires auth. Report null (unknown) not false (down).
                     // TP-31: hostio = null before auth
                     try {
-                        const { status } = await http.get('http://localhost:8888/api/v1/proxy/hostio/health', { timeout: 5000 });
+                        const { status } = await http.get(`${uiBase}/api/v1/proxy/hostio/health`, { timeout: 5000 });
                         if (status === 401) {
                             // Auth required — hostio status is unknown (not unhealthy)
                             components.hostio = { healthy: null, status: 401, note: 'Authentication required — HostIO health unknown until OIDC sign-in' };
@@ -60,26 +104,55 @@ module.exports = function registerCheckRelayerHealth(server, options = {}) {
                         components.hostio = { healthy: null, status: null, note: 'HostIO health unknown — authentication not yet completed' };
                     }
 
+                    // Monitoring sidecars (Prometheus + Grafana) — the channel
+                    // bundle ships them; without them the dashboards under
+                    // Monitoring in the web UI are dead. Absence DEGRADES the
+                    // install (surfaced + named) but never blocks the core flow
+                    // — claim/onboarding doesn't depend on monitoring.
+                    const [prometheus, grafana] = await Promise.all([
+                        docker.isContainerRunning('prometheus'),
+                        docker.isContainerRunning('grafana'),
+                    ]);
+                    const monitoringHealthy = prometheus === true && grafana === true;
+                    components.monitoring = {
+                        healthy: monitoringHealthy,
+                        prometheus,
+                        grafana,
+                        ...(monitoringHealthy ? {} : {
+                            note: 'Monitoring stack (Prometheus/Grafana) is not running — the dashboards under Monitoring in the web UI will be empty. The channel bundle compose includes both; re-run docker compose up -d with the channel bundle to add them.',
+                        }),
+                    };
+
                     // Healthy if UI and S3 are up. HostIO null (unknown) does NOT block.
                     const coreHealthy = components.ui.healthy === true && components.s3.healthy === true;
                     const allKnownHealthy = coreHealthy && components.hostio.healthy === true;
 
                     const unhealthy = [];
-                    if (!components.ui.healthy) unhealthy.push('UI (port 8888)');
-                    if (!components.s3.healthy) unhealthy.push('S3 gateway (port 9000)');
+                    if (!components.ui.healthy) unhealthy.push(`UI (${target}:${uiPort})`);
+                    if (!components.s3.healthy) unhealthy.push(`S3 gateway (${target}:${s3Port})`);
 
                     return {
                         components,
                         healthy: coreHealthy,
                         all_healthy: allKnownHealthy,
+                        // JSON.stringify drops undefined — degraded only appears when true.
+                        degraded: monitoringHealthy ? undefined : true,
                         unhealthy: unhealthy.length > 0 ? unhealthy : undefined,
+                        target_host: target,
+                        remote_docker: dockerHost.remote === true || undefined,
                     };
                 };
 
+                // Degraded (monitoring down) is appended to ANY healthy message —
+                // success stays true, the gap is named instead of swallowed.
+                const degradedSuffix = (r) => (r.degraded
+                    ? ' DEGRADED: monitoring stack (Prometheus/Grafana) is not running — Monitoring dashboards will be empty.'
+                    : '');
+
                 if (!poll) {
                     const result = await checkOnce();
                     const message = result.healthy
-                        ? 'Relayer core services (UI + S3) are healthy.' + (result.all_healthy ? ' HostIO is also healthy.' : ' HostIO status is pending authentication.')
+                        ? 'Relayer core services (UI + S3) are healthy.' + (result.all_healthy ? ' HostIO is also healthy.' : ' HostIO status is pending authentication.') + degradedSuffix(result)
                         : `Relayer is not yet healthy. Unhealthy: ${result.unhealthy.join(', ')}.`;
 
                     return {
@@ -117,9 +190,9 @@ module.exports = function registerCheckRelayerHealth(server, options = {}) {
                     };
                 }
 
-                const message = result.all_healthy
+                const message = (result.all_healthy
                     ? 'All Relayer services are healthy (UI, S3, HostIO). Ready for claim.'
-                    : 'Relayer core services (UI + S3) are healthy. HostIO status pending authentication. Proceed to start_claim.';
+                    : 'Relayer core services (UI + S3) are healthy. HostIO status pending authentication. Proceed to start_claim.') + degradedSuffix(result);
 
                 return {
                     content: [{

package/src/tools/installRelayer.js

@@ -4,19 +4,33 @@ const { z } = require('zod');
 const path = require('path');
 const { createDockerUtil } = require('../lib/dockerUtil');
 
-// Bundled released-install template (ships in the npm package; package.json
-// `files: ["src/"]` covers it). This is the documented xns.tech install.
+// Canonical released install — the full beta channel bundle (relayer +
+// monitoring stack). Versioned in the deploy repo, shipped to web01 by
+// `deploy.py promote`, served login-free. THE default install source.
+const CHANNEL_COMPOSE_URL = 'https://releases.scpri.me/relayer/beta/docker-compose.yml';
+
+// Bundled OFFLINE FALLBACK template (ships in the npm package; package.json
+// `files: ["src/"]` covers it). Written only when the channel fetch fails;
+// kept service-parity with the channel bundle by the jest contract tests.
 const TEMPLATE_PATH = path.join(__dirname, '..', 'templates', 'docker-compose.yml');
 
+// container_name in the bundled compose. Docker container names are unique
+// per daemon, so ANY existing container with this name — running or stopped,
+// alpha channel or beta — makes `docker compose up` fail with a name conflict.
+const CONTAINER_NAME = 'xns-relayer';
+
 /**
  * Tool 4: install_relayer
  * AC-12: confirms "containers starting"; no manual shell.
  * TP-30: uses execFile, no shell (security non-negotiable).
  *
  * A first-time user has never heard of a Relayer and cannot supply a compose
- * file or a .env. So by default this tool WRITES both for them — the bundled
- * released compose (Docker Hub scprime/xns-relayer, pre-release :beta channel,
- * per https://xns.tech/docs/windows-ui/) plus a .env carrying the two ports.
+ * file or a .env. So by default this tool authors both for them: it fetches
+ * the CANONICAL channel bundle (relayer + Prometheus + Grafana + node-exporter
+ * — the monitoring stack powers the dashboards under Monitoring in the web UI)
+ * and writes a .env carrying the two ports. If the fetch fails (offline,
+ * registry hiccup), the bundled service-parity template is the fallback — the
+ * install still completes and the response says it fell back.
  *
  * `compose_url` stays as an optional override for internal/custom installs;
  * when given, the old download-a-URL behaviour is preserved.
@@ -28,20 +42,40 @@ module.exports = function registerInstallRelayer(server, options = {}) {
 
     server.tool(
         'install_relayer',
-        'Install and start the XNS Relayer. By default writes the bundled docker-compose.yml (Docker Hub scprime/xns-relayer, pre-release :beta channel) and a .env, then runs docker compose up -d — the user does NOT need to author any file. Pass compose_url only to override with a custom compose.',
+        'Install and start the XNS Relayer. By default fetches the canonical beta channel bundle — relayer + the Prometheus/Grafana monitoring stack — from releases.scpri.me (anonymous pull) and writes a .env, then runs docker compose up -d — the user does NOT need to author any file. Falls back to a bundled copy of the bundle if the fetch fails. Pass compose_url only to override with a custom compose.',
         {
             install_path: z.string().optional().default('/opt/xns-relayer').describe('Directory to install the compose file into'),
             ui_port: z.number().int().positive().optional().default(8888).describe('Host port for the Relayer admin/customer UI (container 8888)'),
-            minio_port: z.number().int().positive().optional().default(9000).describe('Host port for the S3 API (container 9000)'),
+            s3_port: z.number().int().positive().optional().default(9000).describe('Host port for the S3 API (container 9000)'),
             compose_url: z.string().url().optional().describe('OPTIONAL override: URL to a custom docker-compose.yml. Omit for the normal released install.'),
         },
-        async ({ install_path, ui_port, minio_port, compose_url }) => {
+        async ({ install_path, ui_port, s3_port, compose_url }) => {
             try {
                 const { execFile: nodeExecFile } = require('child_process');
                 const execFileFn = _execFile || nodeExecFile;
                 const composePath = path.join(install_path, 'docker-compose.yml');
                 const envPath = path.join(install_path, '.env');
 
+                // Preflight: install_relayer is for FRESH installs only — it does
+                // not upgrade an existing deployment in place. An existing
+                // container (running or stopped, any channel) owns the name and
+                // would make compose up fail with a confusing name conflict.
+                const existing = await docker.findContainer(CONTAINER_NAME);
+                if (existing) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `An existing '${CONTAINER_NAME}' container was found (status: ${existing.status}; image: ${existing.image}). install_relayer performs fresh installs only — it does not upgrade an existing deployment in place.`,
+                                existing_container: existing,
+                                remediation: `To replace it with this install: 1) stop and remove the existing container — docker stop ${CONTAINER_NAME} && docker rm ${CONTAINER_NAME} (this does NOT delete its data directory); 2) run install_relayer again. To keep the existing deployment instead, skip install_relayer and continue with check_relayer_health against it.`,
+                            }, null, 2),
+                        }],
+                        isError: true,
+                    };
+                }
+
                 // Create install directory (execFile, no shell)
                 await new Promise((resolve, reject) => {
                     execFileFn('mkdir', ['-p', install_path], {}, (err) => {
@@ -50,27 +84,42 @@ module.exports = function registerInstallRelayer(server, options = {}) {
                     });
                 });
 
+                const fetchCompose = (url) => new Promise((resolve, reject) => {
+                    execFileFn('curl', ['-fsSL', '-o', composePath, url], { timeout: 60000 }, (err) => {
+                        if (err) return reject(new Error(`Failed to download compose file: ${err.message}`));
+                        resolve();
+                    });
+                });
+
+                let source;
+                let note;
                 if (compose_url) {
                     // Override path: download a custom compose (execFile, no shell).
-                    await new Promise((resolve, reject) => {
-                        execFileFn('curl', ['-fsSL', '-o', composePath, compose_url], { timeout: 60000 }, (err) => {
-                            if (err) return reject(new Error(`Failed to download compose file: ${err.message}`));
-                            resolve();
-                        });
-                    });
+                    await fetchCompose(compose_url);
+                    source = 'compose_url';
                 } else {
-                    // Default path: write the bundled released compose + .env for the user.
-                    const template = await fsp.readFile(TEMPLATE_PATH, 'utf8');
-                    await fsp.writeFile(composePath, template);
-                    await fsp.writeFile(envPath, `UI_PORT=${ui_port}\nMINIO_PORT=${minio_port}\n`);
+                    // Default path: fetch the canonical channel bundle (relayer +
+                    // monitoring stack); fall back to the bundled service-parity
+                    // template only when the fetch fails. Either way, author the
+                    // .env so the user never writes a file.
+                    try {
+                        await fetchCompose(CHANNEL_COMPOSE_URL);
+                        source = 'channel';
+                    } catch (fetchErr) {
+                        const template = await fsp.readFile(TEMPLATE_PATH, 'utf8');
+                        await fsp.writeFile(composePath, template);
+                        source = 'bundled-fallback';
+                        note = `Channel bundle fetch failed (${fetchErr.message}) — fell back to the bundled compose. Same services; re-running install later is not required.`;
+                    }
+                    await fsp.writeFile(envPath, `UI_PORT=${ui_port}\nS3_PORT=${s3_port}\n`);
                 }
 
-                // Run docker compose up -d. cwd + env so ${UI_PORT}/${MINIO_PORT}
+                // Run docker compose up -d. cwd + env so ${UI_PORT}/${S3_PORT}
                 // interpolation and the ./data bind resolve in the install dir,
                 // regardless of where the MCP process was launched.
                 await docker.composeUp(composePath, {
                     cwd: install_path,
-                    env: { ...process.env, UI_PORT: String(ui_port), MINIO_PORT: String(minio_port) },
+                    env: { ...process.env, UI_PORT: String(ui_port), S3_PORT: String(s3_port) },
                 });
 
                 return {
@@ -81,7 +130,8 @@ module.exports = function registerInstallRelayer(server, options = {}) {
                             message: 'XNS Relayer containers are starting. Use check_relayer_health to monitor when all services are ready.',
                             compose_path: composePath,
                             install_path,
-                            source: compose_url ? 'compose_url' : 'bundled',
+                            source,
+                            ...(note ? { note } : {}),
                         }, null, 2),
                     }],
                 };

package/src/tools/verifyStorage.js

@@ -2,25 +2,29 @@
 
 const { z } = require('zod');
 const { createS3Client } = require('../lib/s3Client');
+const { createDockerUtil } = require('../lib/dockerUtil');
 
 /**
  * Tool 10: verify_storage
- * AC-20: targets localhost:9000 plain HTTP; reports endpoint.
+ * AC-20: targets the S3 gateway on port 9000 plain HTTP; reports endpoint.
  * AC-21: verify fail → names the failing step (CreateBucket/PutObject/GetObject).
  * R6: S3 credentials must be provided (from relayer-ui IAM key-mgmt flow).
  *
  * Performs a round-trip verification: CreateBucket → PutObject → GetObject → compare.
+ * Remote Docker: when endpoint is omitted, it defaults to port 9000 on the
+ * machine the Docker daemon runs on (auto-detected), not blindly localhost.
  */
 module.exports = function registerVerifyStorage(server, options = {}) {
     const _createS3Client = options.createS3Client || createS3Client;
+    const docker = options.dockerUtil || createDockerUtil(options);
 
     server.tool(
         'verify_storage',
-        'Verify the S3-compatible storage gateway is working by performing a round-trip test: create a test bucket, upload a small object, download it, and compare. Targets http://localhost:9000 (the local S3 gateway). You must provide S3 access credentials — these can be found in the Relayer configuration or generated via the Relayer UI.',
+        'Verify the S3-compatible storage gateway is working by performing a round-trip test: create a test bucket, upload a small object, download it, and compare. By default targets port 9000 on the machine the Docker daemon runs on (auto-detected from the Docker context — supports remote ssh:// Docker hosts); pass endpoint to override. You must provide S3 access credentials — these can be found in the Relayer configuration or generated via the Relayer UI.',
         {
             access_key_id: z.string().describe('S3 access key ID'),
             secret_access_key: z.string().describe('S3 secret access key'),
-            endpoint: z.string().optional().default('http://localhost:9000').describe('S3 endpoint URL (default: http://localhost:9000)'),
+            endpoint: z.string().trim().url().optional().describe('S3 endpoint URL. Default: http://{docker-host}:9000, where {docker-host} is auto-detected from the Docker context.'),
         },
         async ({ access_key_id, secret_access_key, endpoint }) => {
             const testBucket = `mcp-verify-${Date.now()}`;
@@ -29,6 +33,10 @@ module.exports = function registerVerifyStorage(server, options = {}) {
             let currentStep = 'init';
 
             try {
+                if (!endpoint) {
+                    const { host } = await docker.getDockerHost();
+                    endpoint = `http://${host}:9000`;
+                }
                 const s3 = _createS3Client({
                     endpoint,
                     accessKeyId: access_key_id,