@xns-cloud/relayer-mcp 0.3.0

package/src/tools/installRelayer.js

@@ -0,0 +1,102 @@
+'use strict';
+
+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.
+const TEMPLATE_PATH = path.join(__dirname, '..', 'templates', 'docker-compose.yml');
+
+/**
+ * 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.
+ *
+ * `compose_url` stays as an optional override for internal/custom installs;
+ * when given, the old download-a-URL behaviour is preserved.
+ */
+module.exports = function registerInstallRelayer(server, options = {}) {
+    const docker = options.dockerUtil || createDockerUtil(options);
+    const _execFile = options.execFile;
+    const fsp = options.fs || require('fs').promises;
+
+    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_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)'),
+            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 }) => {
+            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');
+
+                // Create install directory (execFile, no shell)
+                await new Promise((resolve, reject) => {
+                    execFileFn('mkdir', ['-p', install_path], {}, (err) => {
+                        if (err) return reject(new Error(`Failed to create directory ${install_path}: ${err.message}`));
+                        resolve();
+                    });
+                });
+
+                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();
+                        });
+                    });
+                } 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`);
+                }
+
+                // Run docker compose up -d. cwd + env so ${UI_PORT}/${MINIO_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) },
+                });
+
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            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',
+                        }, null, 2),
+                    }],
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Relayer installation failed: ${err.message}`,
+                        }),
+                    }],
+                    isError: true,
+                };
+            }
+        },
+    );
+};

package/src/tools/registerAccount.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const { z } = require('zod');
+const { createHttpClient } = require('../lib/httpClient');
+
+const CONSOLE_BASE_URL = 'https://console.xns.tech';
+
+/**
+ * Tool 2: register_account
+ * AC-5: silent register, confirms account at {email}.
+ * AC-6: 409 → "email already has account" + next_action skip hint.
+ * AC-7: 422 → names the specific password rule.
+ * AC-8: Gate 1 dialogue names email + auth.xns.tech + auto-check.
+ *
+ * Consumes E2: POST /api/auth/register
+ *   → 201 {success:true, userId, message:"Verification email sent"}
+ *   → 409 {success:false, message} (already registered)
+ *   → 422 {success:false, message} (validation error — password rules)
+ *   → 429 {success:false, message} (rate limited)
+ */
+module.exports = function registerRegisterAccount(server, options = {}) {
+    const http = options.httpClient || createHttpClient(options);
+    const consoleBaseUrl = options.consoleBaseUrl || CONSOLE_BASE_URL;
+
+    server.tool(
+        'register_account',
+        'Register a new XNS account with an email and password. After registration, the user must verify their email at auth.xns.tech by clicking the link sent to their inbox. Use check_email_verified to poll for verification status. If the email already has an account, you can skip to install_relayer.',
+        {
+            email: z.string().email().describe('User email address'),
+            password: z.string().min(8).describe('Password (minimum 8 characters)'),
+        },
+        async ({ email, password }) => {
+            try {
+                const { status, data } = await http.post(
+                    `${consoleBaseUrl}/api/auth/register`,
+                    { email, password },
+                );
+
+                if (status === 201) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Account registered for ${email}. A verification email has been sent. The user must click the verification link at auth.xns.tech before proceeding. Use check_email_verified to poll for verification.`,
+                                email,
+                                userId: data.userId,
+                            }),
+                        }],
+                    };
+                }
+
+                if (status === 409) {
+                    // AC-6: carry next_action skip hint
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: `Email ${email} already has an account. You can skip registration and proceed directly to install_relayer.`,
+                                next_action: 'skip_to_install',
+                                email,
+                            }),
+                        }],
+                    };
+                }
+
+                if (status === 422) {
+                    // AC-7: name the specific password rule
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: data.message || 'Validation error — check password requirements (minimum 8 characters, at least one uppercase, one lowercase, one number).',
+                                email,
+                            }),
+                        }],
+                        isError: true,
+                    };
+                }
+
+                if (status === 429) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: data.message || 'Rate limited. Please wait before retrying registration.',
+                                email,
+                            }),
+                        }],
+                        isError: true,
+                    };
+                }
+
+                // Unexpected status
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Unexpected response (HTTP ${status}): ${data.message || JSON.stringify(data)}`,
+                            email,
+                        }),
+                    }],
+                    isError: true,
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Registration request failed: ${err.message}`,
+                        }),
+                    }],
+                    isError: true,
+                };
+            }
+        },
+    );
+};

package/src/tools/setupCliCredentials.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { z } = require('zod');
+const { createHttpClient } = require('../lib/httpClient');
+
+/**
+ * Tool 11: setup_cli_credentials
+ *
+ * After check_claim_status reaches STATE_3, the user has a provisioned Relayer
+ * but no CLI credentials. This tool:
+ *   1. Creates an IAM user "xns-cli" via the Relayer UI MC proxy
+ *   2. Receives the one-time {access_key, secret_key} response
+ *   3. Writes ~/.xns/credentials (AC-11 JSON schema, mode 0600)
+ *
+ * The muse_token is the Keycloak JWT already held by the agent from the
+ * configure_vpd / get_host_tags calls — no new auth step required.
+ */
+module.exports = function registerSetupCliCredentials(server, options = {}) {
+    const http = options.httpClient || createHttpClient(options);
+
+    server.tool(
+        'setup_cli_credentials',
+        'Provision S3 IAM credentials for the XNS CLI. Creates an IAM user in the Relayer and writes ~/.xns/credentials so that `xns ls` and other S3 verbs work without further configuration. Call once after check_claim_status reaches STATE_3.',
+        {
+            muse_token: z.string().describe('Keycloak/Muse token — the same token used for get_host_tags and configure_vpd'),
+            installation_id: z.string().optional().default('').describe('Installation ID from check_claim_status STATE_3 result — used as cost_center_id in credentials'),
+            relayer_ui_url: z.string().optional().default('http://localhost:8888').describe('Relayer UI base URL (default: http://localhost:8888)'),
+        },
+        async ({ muse_token, installation_id, relayer_ui_url }) => {
+            try {
+                // Step 1: create IAM user "xns-cli" via MC proxy
+                const { status, data } = await http.post(
+                    `${relayer_ui_url}/api/v1/mc/user`,
+                    { user: 'xns-cli' },
+                    { headers: { keycloaktoken: muse_token } }
+                );
+
+                if (status !== 200) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Relayer returned HTTP ${status}`,
+                                detail: data,
+                            }),
+                        }],
+                    };
+                }
+
+                const ak = data.access_key || data.AccessKey || '';
+                const sk = data.secret_key || data.SecretKey || '';
+
+                if (!ak || !sk) {
+                    const msg = data.message || data.Message || data.error || data.Error || 'no credentials in response';
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Relayer: ${msg}`,
+                                hint: 'CLI credentials may already exist. Run `xns ls` — if it works, credentials are valid.',
+                            }),
+                        }],
+                    };
+                }
+
+                // Step 2: derive S3 endpoint (same host, port 9000)
+                const s3Endpoint = relayer_ui_url.replace(/:(\d+)(\/|$)/, ':9000$2');
+
+                // Step 3: write ~/.xns/credentials (AC-11 JSON schema, mode 0600)
+                const credsPath = path.join(os.homedir(), '.xns', 'credentials');
+                fs.mkdirSync(path.dirname(credsPath), { recursive: true });
+
+                const creds = {
+                    version: 1,
+                    profiles: {
+                        default: {
+                            endpoint: s3Endpoint,
+                            access_key_id: ak,
+                            secret_access_key: sk,
+                            cost_center_id: installation_id,
+                            muse_token: muse_token,
+                        },
+                    },
+                    active_profile: 'default',
+                };
+
+                fs.writeFileSync(credsPath, JSON.stringify(creds, null, 2), { mode: 0o600 });
+
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: 'CLI credentials written to ~/.xns/credentials. The user can now run `xns ls` to list their storage.',
+                            s3_endpoint: s3Endpoint,
+                        }),
+                    }],
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: err.message,
+                        }),
+                    }],
+                };
+            }
+        }
+    );
+};

package/src/tools/startClaim.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const { createHttpClient } = require('../lib/httpClient');
+
+const RELAYER_UI_BASE = 'http://localhost:8888';
+
+/**
+ * Tool 6: start_claim
+ * AC-14: Gate 2 dialogue: claim_url + expires_at + auto-detect.
+ * AC-15a: on 402: stop polling, do NOT loop TTL, name specific action.
+ *
+ * Consumes relayer-ui: POST /api/v1/claim/init
+ *   → {claim_id, claim_url, expires_at}
+ *   → 402: payment method required (E3 not yet deployed)
+ *   → 502: upstream error
+ */
+module.exports = function registerStartClaim(server, options = {}) {
+    const http = options.httpClient || createHttpClient(options);
+    const relayerUiBase = options.relayerUiBase || RELAYER_UI_BASE;
+
+    server.tool(
+        'start_claim',
+        'Start a claim session to link this Relayer installation to an XNS account. Returns a claim URL that the user must open in a browser to complete the claim. The claim has an expiration time. After calling this, use check_claim_status to monitor claim progress.',
+        {
+            /* no parameters */
+        },
+        async () => {
+            try {
+                const { status, data } = await http.post(`${relayerUiBase}/api/v1/claim/init`, {});
+
+                // AC-15a: 402 → stop, do NOT loop, name the action
+                if (status === 402) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                continue_polling: false,
+                                message: 'A payment method is required before claiming a Relayer. Please add a payment method to your account at console.xns.tech, then run start_claim again.',
+                            }, null, 2),
+                        }],
+                    };
+                }
+
+                if (status === 502 || status >= 500) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: data.error || 'Failed to initiate claim — upstream service error. Try again in a few seconds.',
+                            }),
+                        }],
+                        isError: true,
+                    };
+                }
+
+                if (status >= 400) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: data.error || `Claim initiation failed (HTTP ${status}).`,
+                            }),
+                        }],
+                        isError: true,
+                    };
+                }
+
+                // Success — AC-14: present claim_url + expires_at
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: `Claim session started. The user must open the following URL in a browser to complete the claim. This session expires at ${data.expires_at}.`,
+                            claim_id: data.claim_id,
+                            claim_url: data.claim_url,
+                            expires_at: data.expires_at,
+                            next_action: 'Use check_claim_status to monitor when the claim is completed.',
+                        }, null, 2),
+                    }],
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Claim initiation failed: ${err.message}`,
+                        }),
+                    }],
+                    isError: true,
+                };
+            }
+        },
+    );
+};

package/src/tools/verifyStorage.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const { z } = require('zod');
+const { createS3Client } = require('../lib/s3Client');
+
+/**
+ * Tool 10: verify_storage
+ * AC-20: targets localhost: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.
+ */
+module.exports = function registerVerifyStorage(server, options = {}) {
+    const _createS3Client = options.createS3Client || createS3Client;
+
+    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.',
+        {
+            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)'),
+        },
+        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';
+
+            try {
+                const s3 = _createS3Client({
+                    endpoint,
+                    accessKeyId: access_key_id,
+                    secretAccessKey: secret_access_key,
+                });
+
+                // Step 1: CreateBucket
+                currentStep = 'CreateBucket';
+                await s3.createBucket(testBucket);
+
+                // Step 2: PutObject
+                currentStep = 'PutObject';
+                await s3.putObject(testBucket, testKey, testContent);
+
+                // Step 3: GetObject
+                currentStep = 'GetObject';
+                const retrieved = await s3.getObject(testBucket, testKey);
+
+                // 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,
+                    };
+                }
+
+                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),
+                    }],
+                };
+            } catch (err) {
+                // AC-21: name the failing step
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Storage verification failed at ${currentStep}: ${err.message}`,
+                            endpoint,
+                            failing_step: currentStep,
+                        }),
+                    }],
+                    isError: true,
+                };
+            }
+        },
+    );
+};