@xns-cloud/relayer-mcp 0.3.0 → 0.4.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` | Write the bundled `docker-compose.yml` + `.env` (`releases.scpri.me/xns-relayer:beta-latest` — the pre-release beta channel, anonymous pull, no `docker login`) and start the containers. **Fresh installs only** — see [Fresh installs vs. existing deployments](#fresh-installs-vs-existing-deployments). The user authors nothing; `compose_url` is an optional override (e.g. the full channel bundle with monitoring: `https://releases.scpri.me/relayer/beta/docker-compose.yml`). |
+| 5 | `check_relayer_health` | Poll UI, S3, and HostIO health (10s interval, 300s timeout). 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.4.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",

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,33 @@
-# 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 — the released XNS Relayer install.
+# Source of truth: the beta release channel on the XNS releases registry
+# (releases.scpri.me — anonymous pull, no docker login). The full channel bundle
+# (relayer + monitoring stack) lives at
+# https://releases.scpri.me/relayer/beta/docker-compose.yml; this bundled file is
+# the minimal relayer-only install. NEVER point this at Docker Hub scprime/* —
+# those are production fleet tags and are not a release channel.
 #
-# 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.
+# Pre-release: pinned to :beta-latest so beta testers exercise the current
+# Relayer agentically. Flip this one tag to :stable-latest at general release.
 #
 # 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.
+# writes both. Differences from the channel compose, by design:
+#   - 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
+#   - pull_policy: always so `docker compose up -d` fetches the current beta
 #     image without a separate `docker compose pull` step.
 services:
   xns:
     container_name: xns-relayer
-    image: scprime/xns-relayer:beta
+    image: releases.scpri.me/xns-relayer:beta-latest
     pull_policy: always
     restart: unless-stopped
     volumes:
       - ./data:/relayer
     ports:
       - ${UI_PORT:-8888}:8888
-      - ${MINIO_PORT:-9000}:9000
+      - ${S3_PORT:-9000}:9000
     env_file:
       - .env

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), and HostIO. Polls every 10 seconds for up to 300 seconds. Reports each component status individually and names any unhealthy component. 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' };
@@ -65,14 +109,16 @@ module.exports = function registerCheckRelayerHealth(server, options = {}) {
                     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,
                         unhealthy: unhealthy.length > 0 ? unhealthy : undefined,
+                        target_host: target,
+                        remote_docker: dockerHost.remote === true || undefined,
                     };
                 };
 

package/src/tools/installRelayer.js

@@ -8,6 +8,11 @@ const { createDockerUtil } = require('../lib/dockerUtil');
 // `files: ["src/"]` covers it). This is the documented xns.tech install.
 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.
@@ -15,8 +20,10 @@ const TEMPLATE_PATH = path.join(__dirname, '..', 'templates', 'docker-compose.ym
  *
  * 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.
+ * released compose (releases.scpri.me/xns-relayer:beta-latest, the pre-release
+ * beta channel; anonymous pull, no docker login) plus a .env carrying the two
+ * ports. The full channel bundle (relayer + monitoring stack) is published at
+ * https://releases.scpri.me/relayer/beta/docker-compose.yml for compose_url.
  *
  * `compose_url` stays as an optional override for internal/custom installs;
  * when given, the old download-a-URL behaviour is preserved.
@@ -28,20 +35,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 writes the bundled docker-compose.yml (releases.scpri.me/xns-relayer:beta-latest — the pre-release beta channel, anonymous pull) 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 (e.g. the full channel bundle with monitoring at https://releases.scpri.me/relayer/beta/docker-compose.yml).',
         {
             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) => {
@@ -62,15 +89,15 @@ module.exports = function registerInstallRelayer(server, options = {}) {
                     // 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`);
+                    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 {

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,