@xns-cloud/relayer-mcp 0.4.0 → 0.5.1

package/README.md

@@ -46,13 +46,13 @@ No separate install step required.
 | 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` (`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. |
+| 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) against the S3 gateway on port 9000. |
+| 10 | `verify_storage` | Round-trip S3 test (create bucket, put object, get object) against the S3 gateway on port 9000. **Requires fullaccess credentials** (admin key pair from the Relayer UI IAM page — not a read-only or bucket-scoped key). Test bucket is cleaned up automatically. If auto-detection cannot reach the host, pass `endpoint` with an explicit IP (e.g. `http://192.168.1.100:9000`). |
 | 11 | `setup_cli_credentials` | Provision S3 IAM credentials and write `~/.xns/credentials` so the XNS CLI works without further configuration. |
 
 ## Onboarding Flow

package/package.json

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

package/src/lib/s3Client.js

@@ -5,6 +5,8 @@ const {
     CreateBucketCommand,
     PutObjectCommand,
     GetObjectCommand,
+    DeleteObjectCommand,
+    DeleteBucketCommand,
 } = require('@aws-sdk/client-s3');
 
 /**
@@ -65,6 +67,23 @@ function createS3Client(options = {}) {
             return resp.Body.transformToString();
         },
 
+        /**
+         * @param {string} bucket
+         * @param {string} key
+         * @returns {Promise<void>}
+         */
+        async deleteObject(bucket, key) {
+            await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+        },
+
+        /**
+         * @param {string} bucket
+         * @returns {Promise<void>}
+         */
+        async deleteBucket(bucket) {
+            await client.send(new DeleteBucketCommand({ Bucket: bucket }));
+        },
+
         /** Expose the raw client for advanced use */
         client,
     };

package/src/templates/docker-compose.yml

@@ -1,29 +1,38 @@
-# 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.
+# 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.
+#
+# 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).
 #
 # Pre-release: pinned to :beta-latest so beta testers exercise the current
-# Relayer agentically. Flip this one tag to :stable-latest at general release.
+# Relayer agentically. Flip these tags to :stable-latest at general release.
 #
-# A first-time user no longer hand-writes this file or the .env — install_relayer
+# A first-time user never hand-writes this file or the .env — install_relayer
 # 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.
+#   - 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.
+#     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: 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:
@@ -31,3 +40,38 @@ services:
       - ${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/checkRelayerHealth.js

@@ -53,7 +53,7 @@ module.exports = function registerCheckRelayerHealth(server, options = {}) {
 
     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. 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.',
+        '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).'),
@@ -104,6 +104,25 @@ 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;
@@ -116,16 +135,24 @@ module.exports = function registerCheckRelayerHealth(server, options = {}) {
                         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 {
@@ -163,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,8 +4,14 @@ 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
@@ -19,11 +25,12 @@ const CONTAINER_NAME = 'xns-relayer';
  * 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 (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.
+ * 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.
@@ -32,10 +39,11 @@ module.exports = function registerInstallRelayer(server, options = {}) {
     const docker = options.dockerUtil || createDockerUtil(options);
     const _execFile = options.execFile;
     const fsp = options.fs || require('fs').promises;
+    const channelComposeUrl = options.channelComposeUrl || CHANNEL_COMPOSE_URL;
 
     server.tool(
         'install_relayer',
-        '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 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)'),
@@ -77,18 +85,33 @@ 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);
+                    // 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(channelComposeUrl);
+                        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`);
                 }
 
@@ -108,7 +131,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

@@ -8,6 +8,10 @@ const { createDockerUtil } = require('../lib/dockerUtil');
  * Tool 10: verify_storage
  * AC-20: targets the S3 gateway on port 9000 plain HTTP; reports endpoint.
  * AC-21: verify fail → names the failing step (CreateBucket/PutObject/GetObject).
+ * W3-AC1: cleanup in finally — always removes mcp-verify-* bucket/object; failure
+ *         is non-fatal (noted in response, never flips pass→fail).
+ * W3-AC2: fullaccess credential requirement stated in description and error output.
+ * W3-AC3: explicit-IP hint when endpoint was auto-detected.
  * R6: S3 credentials must be provided (from relayer-ui IAM key-mgmt flow).
  *
  * Performs a round-trip verification: CreateBucket → PutObject → GetObject → compare.
@@ -20,22 +24,26 @@ module.exports = function registerVerifyStorage(server, 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. 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.',
+        '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. IMPORTANT: you must supply fullaccess credentials — the admin key pair created via the Relayer UI IAM page (not a read-only or bucket-scoped key). 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 with an explicit IP when auto-detection cannot reach the host.',
         {
-            access_key_id: z.string().describe('S3 access key ID'),
-            secret_access_key: z.string().describe('S3 secret access key'),
-            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.'),
+            access_key_id: z.string().describe('S3 access key ID (fullaccess credentials from the Relayer UI IAM page)'),
+            secret_access_key: z.string().describe('S3 secret access key (fullaccess credentials from the Relayer UI IAM page)'),
+            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. Pass an explicit IP (e.g. http://192.168.1.100:9000) when auto-detection cannot reach the host.'),
         },
         async ({ access_key_id, secret_access_key, endpoint }) => {
             const testBucket = `mcp-verify-${Date.now()}`;
             const testKey = 'verify-test.txt';
             const testContent = `relayer-mcp verification ${Date.now()}`;
             let currentStep = 'init';
+            let endpointAutoDetected = false;
+
+            let verifyResult = null;
 
             try {
                 if (!endpoint) {
                     const { host } = await docker.getDockerHost();
                     endpoint = `http://${host}:9000`;
+                    endpointAutoDetected = true;
                 }
                 const s3 = _createS3Client({
                     endpoint,
@@ -58,42 +66,83 @@ module.exports = function registerVerifyStorage(server, options = {}) {
                 // Step 4: Compare
                 currentStep = 'Compare';
                 if (retrieved !== testContent) {
-                    return {
-                        content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                success: false,
-                                error: 'Storage verification failed at Compare: uploaded content does not match downloaded content. The S3 gateway may have data integrity issues.',
-                                endpoint,
-                                failing_step: 'Compare',
-                            }),
-                        }],
-                        isError: true,
+                    verifyResult = {
+                        success: false,
+                        error: 'Storage verification failed at Compare: uploaded content does not match downloaded content. The S3 gateway may have data integrity issues.',
+                        endpoint,
+                        failing_step: 'Compare',
+                    };
+                } else {
+                    const explicitIpHint = endpointAutoDetected
+                        ? `If auto-detection cannot reach the host, pass an explicit endpoint: endpoint option (e.g. "http://<ip>:9000").`
+                        : null;
+
+                    verifyResult = {
+                        success: true,
+                        message: `S3 storage verification passed. Successfully created bucket, uploaded object, and verified download at ${endpoint}.`,
+                        endpoint,
+                        test_bucket: testBucket,
+                        ...(explicitIpHint ? { note: explicitIpHint } : {}),
                     };
                 }
 
+                // Cleanup: remove test object and bucket (W3-AC1)
+                try {
+                    await s3.deleteObject(testBucket, testKey);
+                    await s3.deleteBucket(testBucket);
+                } catch (cleanupErr) {
+                    // Non-fatal: note it but never flip the result
+                    verifyResult.cleanup_warning = `Test bucket cleanup failed (${cleanupErr.message}). The bucket "${testBucket}" may remain — remove it manually via the Relayer UI.`;
+                }
+
                 return {
                     content: [{
                         type: 'text',
-                        text: JSON.stringify({
-                            success: true,
-                            message: `S3 storage verification passed. Successfully created bucket, uploaded object, and verified download at ${endpoint}.`,
-                            endpoint,
-                            test_bucket: testBucket,
-                        }, null, 2),
+                        text: JSON.stringify(verifyResult, null, 2),
                     }],
+                    ...(verifyResult.success ? {} : { isError: true }),
                 };
             } catch (err) {
+                // Attempt cleanup even on error (W3-AC1)
+                let cleanupWarning;
+                if (currentStep !== 'init' && currentStep !== 'CreateBucket') {
+                    // Bucket was created before the failure — try to clean up
+                    try {
+                        const s3Cleanup = _createS3Client({
+                            endpoint,
+                            accessKeyId: access_key_id,
+                            secretAccessKey: secret_access_key,
+                        });
+                        await s3Cleanup.deleteObject(testBucket, testKey).catch(() => {});
+                        await s3Cleanup.deleteBucket(testBucket);
+                    } catch (cleanupErr) {
+                        cleanupWarning = `Test bucket cleanup failed (${cleanupErr.message}). The bucket "${testBucket}" may remain — remove it manually.`;
+                    }
+                }
+
+                const isCredentialError = /AccessDenied|InvalidAccessKeyId|SignatureDoesNotMatch|Forbidden|401|403/i.test(err.message);
+                const credentialHint = isCredentialError
+                    ? ' Ensure you are using fullaccess credentials from the Relayer UI IAM page (not a read-only or bucket-scoped key).'
+                    : '';
+
+                const explicitIpHint = endpointAutoDetected
+                    ? ` If the endpoint cannot be reached, pass an explicit IP via the endpoint option (e.g. "http://<ip>:9000").`
+                    : '';
+
                 // AC-21: name the failing step
+                const errorPayload = {
+                    success: false,
+                    error: `Storage verification failed at ${currentStep}: ${err.message}.${credentialHint}${explicitIpHint}`,
+                    endpoint,
+                    failing_step: currentStep,
+                    ...(isCredentialError ? { credential_requirement: 'fullaccess credentials required — use the admin key pair from the Relayer UI IAM page.' } : {}),
+                    ...(cleanupWarning ? { cleanup_warning: cleanupWarning } : {}),
+                };
+
                 return {
                     content: [{
                         type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: `Storage verification failed at ${currentStep}: ${err.message}`,
-                            endpoint,
-                            failing_step: currentStep,
-                        }),
+                        text: JSON.stringify(errorPayload),
                     }],
                     isError: true,
                 };