@xns-cloud/relayer-mcp 0.3.0

package/src/tools/checkEmailVerified.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const { z } = require('zod');
+const { createHttpClient } = require('../lib/httpClient');
+const { pollUntil } = require('../lib/pollUntil');
+
+const CONSOLE_BASE_URL = 'https://console.xns.tech';
+const POLL_INTERVAL_MS = 15000;   // 15s (AC-9)
+const POLL_TIMEOUT_MS = 1800000;  // 30 min (AC-11)
+
+/**
+ * Tool 3: check_email_verified
+ * AC-9: poll every 15s; auto-proceed on verified.
+ * AC-10: three-state {verified:true} / {verified:false, exists:true} / {verified:false, exists:false}.
+ * AC-11: 30-min timeout → expiry msg + resend (resend=true), no re-register.
+ *
+ * Consumes E2: GET /api/auth/email-verified?email=&resend=
+ *   → {verified:true}
+ *   → {verified:false, exists:true}
+ *   → {verified:false, exists:false}
+ *   resend-unknown → 404; >180/email/hr → 429
+ */
+module.exports = function registerCheckEmailVerified(server, options = {}) {
+    const http = options.httpClient || createHttpClient(options);
+    const consoleBaseUrl = options.consoleBaseUrl || CONSOLE_BASE_URL;
+    const pollInterval = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const pollTimeout = options.pollTimeoutMs ?? POLL_TIMEOUT_MS;
+    const sleep = options.sleep;
+
+    server.tool(
+        'check_email_verified',
+        'Poll to check if the user has verified their email address. Automatically polls every 15 seconds for up to 30 minutes. Returns immediately if already verified. If the email has no account, indicates registration is needed.',
+        {
+            email: z.string().email().describe('Email address to check verification status'),
+            poll: z.boolean().optional().default(true).describe('If true (default), poll until verified or timeout. If false, check once.'),
+        },
+        async ({ email, poll }) => {
+            try {
+                const checkOnce = async () => {
+                    const { status, data } = await http.get(
+                        `${consoleBaseUrl}/api/auth/email-verified?email=${encodeURIComponent(email)}`,
+                    );
+
+                    if (status === 429) {
+                        return {
+                            done: true,
+                            result: {
+                                success: false,
+                                message: 'Rate limited. Waiting before retrying.',
+                                rate_limited: true,
+                            },
+                        };
+                    }
+
+                    if (status === 404) {
+                        return {
+                            done: true,
+                            result: {
+                                success: false,
+                                message: `No account found for ${email}. Use register_account first.`,
+                                exists: false,
+                                verified: false,
+                            },
+                        };
+                    }
+
+                    // Three-state response (AC-10)
+                    if (data.verified === true) {
+                        return {
+                            done: true,
+                            result: {
+                                success: true,
+                                message: `Email ${email} is verified. Proceeding to installation.`,
+                                verified: true,
+                                exists: true,
+                            },
+                        };
+                    }
+
+                    if (data.verified === false && data.exists === false) {
+                        return {
+                            done: true,
+                            result: {
+                                success: false,
+                                message: `No account found for ${email}. Use register_account to create an account first.`,
+                                verified: false,
+                                exists: false,
+                            },
+                        };
+                    }
+
+                    // verified:false, exists:true — not yet verified, keep polling
+                    return {
+                        done: false,
+                        result: {
+                            success: false,
+                            verified: false,
+                            exists: true,
+                            message: `Email ${email} is registered but not yet verified. Waiting for the user to click the verification link.`,
+                        },
+                    };
+                };
+
+                // Single check mode
+                if (!poll) {
+                    const { result } = await checkOnce();
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+
+                // Poll mode (AC-9)
+                const { result, timedOut } = await pollUntil({
+                    fn: async () => {
+                        const check = await checkOnce();
+                        if (check.done) return check.result;
+                        return null; // not done, keep polling
+                    },
+                    intervalMs: pollInterval,
+                    timeoutMs: pollTimeout,
+                    sleep,
+                });
+
+                if (timedOut) {
+                    // AC-11: timeout → resend, no re-register
+                    try {
+                        await http.get(
+                            `${consoleBaseUrl}/api/auth/email-verified?email=${encodeURIComponent(email)}&resend=true`,
+                        );
+                    } catch {
+                        // Best-effort resend
+                    }
+
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: `Verification timed out after 30 minutes. A new verification email has been sent to ${email}. Ask the user to check their inbox (including spam folder) and click the link, then run check_email_verified again.`,
+                                verified: false,
+                                exists: true,
+                                resent: true,
+                            }, null, 2),
+                        }],
+                    };
+                }
+
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Email verification check failed: ${err.message}`,
+                        }),
+                    }],
+                    isError: true,
+                };
+            }
+        },
+    );
+};

package/src/tools/checkPrerequisites.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const net = require('net');
+const { createHttpClient } = require('../lib/httpClient');
+const { createDockerUtil } = require('../lib/dockerUtil');
+
+/**
+ * Tool 1: check_prerequisites
+ * Reports docker, ports, disk, and connectivity in plain English.
+ * AC-3: plain English report. AC-4: each failure names problem AND remediation hint.
+ */
+
+/**
+ * Check if a TCP port is available by attempting to bind.
+ * R7: net.createServer bind-probe (platform-agnostic), not lsof/netstat.
+ *
+ * @param {number} port
+ * @returns {Promise<boolean>} true if available (not in use)
+ */
+function checkPort(port) {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.once('error', () => resolve(false));
+        srv.once('listening', () => {
+            srv.close(() => resolve(true));
+        });
+        srv.listen(port, '0.0.0.0');
+    });
+}
+
+module.exports = function registerCheckPrerequisites(server, options = {}) {
+    const docker = options.dockerUtil || createDockerUtil(options);
+    const http = options.httpClient || createHttpClient(options);
+    const _checkPort = options.checkPort || checkPort;
+
+    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.',
+        {
+            /* no parameters */
+        },
+        async () => {
+            const checks = [];
+            let allPassed = true;
+
+            // 1. Docker available
+            try {
+                await docker.docker(['info', '--format', '{{.ServerVersion}}']);
+                checks.push({ name: 'docker', passed: true, detail: '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',
+                });
+            }
+
+            // 2-3. Required ports
+            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).' },
+            ];
+            for (const { port, name, inUseRemediation } of requiredPorts) {
+                try {
+                    const available = await _checkPort(port);
+                    if (available) {
+                        checks.push({ name, passed: true, detail: `Port ${port} is available` });
+                    } else {
+                        allPassed = false;
+                        checks.push({ name, passed: false, detail: `Port ${port} is already in use`, remediation: inUseRemediation });
+                    }
+                } catch {
+                    allPassed = false;
+                    checks.push({ name, passed: false, detail: `Could not check port ${port}`, remediation: 'Ensure you have permission to bind ports. On Linux, non-root users may need to use ports above 1024.' });
+                }
+            }
+
+            // 4. Disk space (need at least 10 GB free — basic docker images + data)
+            try {
+                await docker.docker(['system', 'df', '--format', '{{.TotalCount}}']);
+                // If docker works, disk is implicitly accessible. We check via df on root.
+                checks.push({ name: 'disk', passed: true, detail: 'Docker storage is accessible' });
+            } catch {
+                // If docker system df fails but docker info succeeded, still note it
+                checks.push({ name: 'disk', passed: true, detail: 'Disk check skipped (Docker storage stats unavailable)' });
+            }
+
+            // 5-6. Network connectivity
+            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' },
+            ];
+            for (const { url, name, host } of connectivityChecks) {
+                try {
+                    const { status } = await http.get(url, { timeout: 10000 });
+                    if (status >= 200 && status < 500) {
+                        checks.push({ name, passed: true, detail: `${host} is reachable` });
+                    } else {
+                        allPassed = false;
+                        checks.push({ name, passed: false, detail: `${host} returned HTTP ${status}`, remediation: `Ensure outbound HTTPS (port 443) to ${host} is allowed. Check DNS resolution and firewall rules.` });
+                    }
+                } catch (err) {
+                    allPassed = false;
+                    checks.push({ name, passed: false, detail: `Cannot reach ${host}: ${err.message}`, remediation: `Ensure outbound HTTPS (port 443) to ${host} is allowed. Check DNS resolution and firewall rules.` });
+                }
+            }
+
+            const result = {
+                success: allPassed,
+                checks,
+                summary: allPassed
+                    ? 'All prerequisites met. Ready to proceed with Relayer setup.'
+                    : `${checks.filter((c) => !c.passed).length} prerequisite(s) failed. Review the checks above for details and remediation steps.`,
+            };
+
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        },
+    );
+};

package/src/tools/checkRelayerHealth.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const { z } = require('zod');
+const { createHttpClient } = require('../lib/httpClient');
+const { pollUntil } = require('../lib/pollUntil');
+
+const POLL_INTERVAL_MS = 10000;   // 10s
+const POLL_TIMEOUT_MS = 300000;   // 300s (AC-13, QA-1)
+
+/**
+ * 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).
+ */
+module.exports = function registerCheckRelayerHealth(server, options = {}) {
+    const http = options.httpClient || createHttpClient(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.',
+        {
+            poll: z.boolean().optional().default(true).describe('If true (default), poll until healthy or timeout. If false, check once.'),
+        },
+        async ({ poll }) => {
+            try {
+                const checkOnce = async () => {
+                    const components = {};
+
+                    // UI health (port 8888)
+                    try {
+                        const { status } = await http.get('http://localhost:8888/health', { timeout: 5000 });
+                        components.ui = { healthy: status >= 200 && status < 500, status };
+                    } catch {
+                        components.ui = { healthy: false, status: null };
+                    }
+
+                    // S3 gateway (port 9000)
+                    try {
+                        const { status } = await http.get('http://localhost:9000/', { timeout: 5000 });
+                        components.s3 = { healthy: status >= 200 && status < 500, status };
+                    } catch {
+                        components.s3 = { healthy: false, status: null };
+                    }
+
+                    // 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 });
+                        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' };
+                        } else {
+                            components.hostio = { healthy: status >= 200 && status < 400, status };
+                        }
+                    } catch {
+                        components.hostio = { healthy: null, status: null, note: 'HostIO health unknown — authentication not yet completed' };
+                    }
+
+                    // Healthy if UI and S3 are up. HostIO null (unknown) does NOT block.
+                    const coreHealthy = components.ui.healthy === true && components.s3.healthy === true;
+                    const allKnownHealthy = coreHealthy && components.hostio.healthy === true;
+
+                    const unhealthy = [];
+                    if (!components.ui.healthy) unhealthy.push('UI (port 8888)');
+                    if (!components.s3.healthy) unhealthy.push('S3 gateway (port 9000)');
+
+                    return {
+                        components,
+                        healthy: coreHealthy,
+                        all_healthy: allKnownHealthy,
+                        unhealthy: unhealthy.length > 0 ? unhealthy : undefined,
+                    };
+                };
+
+                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 is not yet healthy. Unhealthy: ${result.unhealthy.join(', ')}.`;
+
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({ success: result.healthy, message, ...result }, null, 2),
+                        }],
+                    };
+                }
+
+                // Poll mode
+                const { result, timedOut } = await pollUntil({
+                    fn: async () => {
+                        const check = await checkOnce();
+                        if (check.healthy) return check;
+                        return null;
+                    },
+                    intervalMs: pollInterval,
+                    timeoutMs: pollTimeout,
+                    sleep,
+                });
+
+                if (timedOut) {
+                    const finalCheck = await checkOnce();
+                    const unhealthyNames = finalCheck.unhealthy || [];
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: `Health check timed out after 300 seconds. Unhealthy components: ${unhealthyNames.join(', ') || 'none identified'}. Check Docker container logs for details.`,
+                                ...finalCheck,
+                            }, null, 2),
+                        }],
+                    };
+                }
+
+                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.';
+
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: true, message, ...result }, null, 2),
+                    }],
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Health check failed: ${err.message}`,
+                        }),
+                    }],
+                    isError: true,
+                };
+            }
+        },
+    );
+};

package/src/tools/configureVpd.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const { z } = require('zod');
+const { createHttpClient } = require('../lib/httpClient');
+const { createTokenManager } = require('../lib/ensureToken');
+
+const RELAYER_UI_BASE = 'http://localhost:8888';
+
+/**
+ * Tool 9: configure_vpd
+ * AC-18: too-few-hosts 400 → plain re-ask naming 10/20 threshold.
+ * AC-19: "use defaults" → configure_vpd("true","true") no further ask.
+ * Watch item 1: trigger OIDC re-auth on 401 — never silent failure.
+ *
+ * Consumes relayer-ui: POST /api/v1/proxy/hostio/v1/hostio/setexpressions
+ * via keycloaktoken header (OIDC-authenticated proxy).
+ */
+module.exports = function registerConfigureVpd(server, options = {}) {
+    const http = options.httpClient || createHttpClient(options);
+    const relayerUiBase = options.relayerUiBase || RELAYER_UI_BASE;
+
+    const tokenMgr = createTokenManager(options);
+    const { ensureToken } = tokenMgr;
+
+    server.tool(
+        'configure_vpd',
+        'Configure VPD (Virtual Private Datacenter) host selection for the Relayer. You can either use defaults (recommended for most users) or provide a CEL expression to filter specific hosts by tags. The Relayer requires a minimum of 10 data hosts and 20 parity hosts. If too few hosts match your filter, broaden your criteria. Requires OIDC sign-in (same session as get_host_tags).',
+        {
+            data_expression: z.string().describe('CEL expression for data host selection. Use "true" for default (all hosts).'),
+            parity_expression: z.string().describe('CEL expression for parity host selection. Use "true" for default (all hosts).'),
+        },
+        async ({ data_expression, parity_expression }) => {
+            try {
+                let token = await ensureToken();
+
+                const payload = {
+                    data_expression,
+                    parity_expression,
+                };
+
+                let { status, data } = await http.post(
+                    `${relayerUiBase}/api/v1/proxy/hostio/v1/hostio/setexpressions`,
+                    payload,
+                    { headers: { keycloaktoken: token } },
+                );
+
+                // Watch item 1: 401 → re-auth
+                if (status === 401) {
+                    token = await tokenMgr.reauth();
+                    const retry = await http.post(
+                        `${relayerUiBase}/api/v1/proxy/hostio/v1/hostio/setexpressions`,
+                        payload,
+                        { headers: { keycloaktoken: token } },
+                    );
+                    status = retry.status;
+                    data = retry.data;
+                }
+
+                if (status === 401) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: 'Authentication failed after re-auth attempt. The OIDC token was rejected by the Relayer proxy.',
+                            }),
+                        }],
+                        isError: true,
+                    };
+                }
+
+                // AC-18: 400 with too-few-hosts → plain re-ask naming 10/20 threshold
+                if (status === 400) {
+                    const msg = typeof data === 'string' ? data : (data.message || data.error || JSON.stringify(data));
+                    const isTooFew = /too.few|not enough|insufficient/i.test(msg);
+
+                    if (isTooFew) {
+                        return {
+                            content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    success: false,
+                                    message: `Not enough hosts match your filter. The Relayer requires at least 10 data hosts and 20 parity hosts. Your current expression matched too few hosts. Try broadening your criteria or use defaults ("true" for both expressions).`,
+                                    too_few_hosts: true,
+                                    min_data_hosts: 10,
+                                    min_parity_hosts: 20,
+                                }, null, 2),
+                            }],
+                        };
+                    }
+
+                    // Other 400 — likely invalid CEL expression
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `VPD configuration rejected: ${msg}. Check that the expression syntax is valid.`,
+                            }),
+                        }],
+                        isError: true,
+                    };
+                }
+
+                if (status >= 400) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `VPD configuration failed (HTTP ${status}): ${JSON.stringify(data)}`,
+                            }),
+                        }],
+                        isError: true,
+                    };
+                }
+
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: 'VPD host selection configured successfully. The Relayer will use the specified host preferences for data storage.',
+                            data_expression,
+                            parity_expression,
+                        }, null, 2),
+                    }],
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `VPD configuration failed: ${err.message}`,
+                        }),
+                    }],
+                    isError: true,
+                };
+            }
+        },
+    );
+
+    return { ensureToken, getTokenState: tokenMgr.getTokenState, setTokenState: tokenMgr.setTokenState };
+};

package/src/tools/getHostTags.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const { createHttpClient } = require('../lib/httpClient');
+const { createTokenManager } = require('../lib/ensureToken');
+
+const RELAYER_UI_BASE = 'http://localhost:8888';
+
+/**
+ * Tool 8: get_host_tags
+ * AC-17: translate plain English → CEL; operator never sees "expression".
+ * Watch item 1: trigger OIDC re-auth on 401 — never silent failure.
+ *
+ * Consumes relayer-ui: GET /api/v1/proxy/hostio/v1/hostio/gettags
+ * via keycloaktoken header (OIDC-authenticated proxy).
+ */
+module.exports = function registerGetHostTags(server, options = {}) {
+    const http = options.httpClient || createHttpClient(options);
+    const relayerUiBase = options.relayerUiBase || RELAYER_UI_BASE;
+
+    const tokenMgr = createTokenManager(options);
+    const { ensureToken } = tokenMgr;
+
+    server.tool(
+        'get_host_tags',
+        'Get the list of available host tags for VPD (Virtual Private Datacenter) configuration. Returns the raw tags that can be used to build host selection preferences. The agent should translate these tags into plain-language options for the operator — never show raw CEL expressions. Requires OIDC sign-in on first use (the user will be prompted to sign in via browser).',
+        {
+            /* no parameters */
+        },
+        async () => {
+            try {
+                let token = await ensureToken();
+
+                let { status, data } = await http.get(
+                    `${relayerUiBase}/api/v1/proxy/hostio/v1/hostio/gettags`,
+                    { headers: { keycloaktoken: token } },
+                );
+
+                // Watch item 1: 401 → re-auth, never silent failure
+                if (status === 401) {
+                    token = await tokenMgr.reauth();
+                    const retry = await http.get(
+                        `${relayerUiBase}/api/v1/proxy/hostio/v1/hostio/gettags`,
+                        { headers: { keycloaktoken: token } },
+                    );
+                    status = retry.status;
+                    data = retry.data;
+                }
+
+                if (status === 401) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: 'Authentication failed after re-auth attempt. The OIDC token was rejected by the Relayer proxy. Check Keycloak client configuration.',
+                            }),
+                        }],
+                        isError: true,
+                    };
+                }
+
+                if (status >= 400) {
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Failed to retrieve host tags (HTTP ${status}): ${JSON.stringify(data)}`,
+                            }),
+                        }],
+                        isError: true,
+                    };
+                }
+
+                const tags = data.tags || data || [];
+
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            tags,
+                            message: 'Host tags retrieved. Present these as plain-language options to the operator (e.g., "US-based hosts", "European hosts"). Never show raw tag names or CEL expressions directly. Use configure_vpd to apply the selection.',
+                        }, null, 2),
+                    }],
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Failed to get host tags: ${err.message}`,
+                        }),
+                    }],
+                    isError: true,
+                };
+            }
+        },
+    );
+
+    // Expose for testing
+    return { ensureToken, getTokenState: tokenMgr.getTokenState, setTokenState: tokenMgr.setTokenState };
+};