@xrpl-utilities/mcp 0.1.6

package/dist/transport/stdio.js

@@ -0,0 +1,28 @@
+/**
+ * stdio transport. Used when Claude Desktop (or any MCP client that
+ * launches the server as a subprocess) spawns this binary directly.
+ *
+ *   {
+ *     "mcpServers": {
+ *       "xrpl-utilities": {
+ *         "command": "npx",
+ *         "args": ["-y", "@xrpl-utilities/mcp", "--transport", "stdio"]
+ *       }
+ *     }
+ *   }
+ *
+ * Single-tenant: the user's MCP_BYPASS_KEY (if set) and any pre-signed
+ * payment_signature live on their machine, never leave it.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "../server.js";
+export async function runStdio() {
+    const server = buildServer({
+        bypassKey: process.env["MCP_BYPASS_KEY"],
+        userAgent: `xrpl-utilities-mcp/0.1.6 (stdio)`,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Server runs until the client closes stdio.
+}
+//# sourceMappingURL=stdio.js.map

package/dist/transport/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/transport/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,MAAM,MAAM,GAAG,WAAW,CAAC;QACzB,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;QACxC,SAAS,EAAE,kCAAkC;KAC9C,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,6CAA6C;AAC/C,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared types for the XRPL-Utilities MCP server.
+ *
+ * Each registered service has a base URL, a manifest URL (for the
+ * startup schema-discipline check), and a list of tools that wrap
+ * specific endpoints. Tools are MCP-callable functions; the server
+ * dispatches incoming MCP tool calls to the underlying HTTP endpoint
+ * and forwards the response.
+ */
+import type { JSONSchema7 } from "./jsonschema.js";
+export type HttpMethod = "GET" | "POST";
+/**
+ * Three auth modes are possible per tool:
+ *
+ *  - inline_x402:  caller passes `payment_signature` in tool args; the
+ *                  dispatcher forwards it as the PAYMENT-SIGNATURE
+ *                  header on the underlying call. Standard x402 v2
+ *                  verify-then-work-then-settle. $0.10 USD lands on
+ *                  the operator wallet per successful call.
+ *
+ *  - async_invoice: this MCP tool wraps one step of the Telemetry
+ *                  three-step flow (quote -> pay -> status -> results).
+ *                  The MCP wrapper itself doesn't need a payment header
+ *                  - the actual XRPL Payment happens out-of-band via
+ *                  the deeplink / QR returned by quote. The operator
+ *                  still earns $0.10 per snapshot, just settled via a
+ *                  regular Payment instead of an inline x402 header.
+ *
+ *  - free:          truly free. Reserved for endpoints like /healthz
+ *                  or /schema mirrors. Not used today; placeholder for
+ *                  future XR-* services that may expose pure metadata.
+ *
+ * The `paid` field has been retained as a deprecated alias - true was
+ * inline_x402, false was async_invoice or free. New code should switch
+ * on authMode.
+ */
+export type AuthMode = "inline_x402" | "async_invoice" | "free";
+/**
+ * A single tool definition. The MCP server exposes one MCP tool per
+ * entry. Auth/payment is handled per-call by the dispatcher based on
+ * the tool's authMode and the caller-supplied `payment_signature` arg.
+ */
+export interface ToolDef {
+    /** MCP tool name. Convention: xrpl_<service>_<verb>. */
+    name: string;
+    /** Description shown to the LLM. Be specific about pricing + return shape. */
+    description: string;
+    /** JSON Schema for the input arguments the LLM provides. */
+    inputSchema: JSONSchema7;
+    /** Underlying HTTP method on the target service. */
+    method: HttpMethod;
+    /**
+     * Path template on the target service. May contain {param} placeholders
+     * that get substituted from the input args before the request fires.
+     * Example: "/domain/{domain_id}".
+     */
+    path: string;
+    /** Auth model for this tool. See AuthMode docs above. */
+    authMode: AuthMode;
+    /**
+     * If true, the body of the HTTP request comes from the input args
+     * (minus payment_signature). If false, args go in the query string
+     * for GETs and there is no body. Only meaningful on POST.
+     */
+    bodyFromArgs?: boolean;
+    /**
+     * Args to drop from the body/query before sending. Used to strip
+     * payment_signature so it doesn't leak into the API call as a
+     * regular field.
+     */
+    stripArgs?: string[];
+}
+export interface ServiceDef {
+    /** Service identifier. Lowercased, used as a tool name prefix. */
+    id: string;
+    /** Human label for logs / errors. */
+    label: string;
+    /** Live HTTPS base. e.g. "https://sentinel.xrpl-utilities.io". */
+    baseUrl: string;
+    /** /agents.json URL — fetched at startup for schema-discipline check. */
+    manifestUrl: string;
+    /** Schema versions this MCP build is known to be compatible with. */
+    knownSchemaVersions: string[];
+    /** All tools this service exposes. */
+    tools: ToolDef[];
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared types for the XRPL-Utilities MCP server.
+ *
+ * Each registered service has a base URL, a manifest URL (for the
+ * startup schema-discipline check), and a list of tools that wrap
+ * specific endpoints. Tools are MCP-callable functions; the server
+ * dispatches incoming MCP tool calls to the underlying HTTP endpoint
+ * and forwards the response.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/validate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Startup schema-discipline check.
+ *
+ * For each registered service, fetch its live /agents.json and verify
+ *
+ *   1. The reported schema_version is one we've seen before
+ *      (knownSchemaVersions). An unrecognized version means the
+ *      upstream service may have added/renamed/removed fields the
+ *      MCP build is not aware of - the operator should bump and re-
+ *      release this MCP package after auditing the changes.
+ *
+ *   2. Each tool's path appears somewhere in the manifest's endpoints
+ *      block. If a service renames /scan to /scan/v2 we want to fail
+ *      LOUD here, not silently 404 every agent call.
+ *
+ * On dev / first-launch we may want to tolerate manifest fetch failures
+ * (so the MCP server still starts when networking is flaky); on
+ * production we want to fail-closed. STRICT_VALIDATE=1 toggles that.
+ */
+export interface ValidationResult {
+    service: string;
+    ok: boolean;
+    warnings: string[];
+    errors: string[];
+}
+export declare function validateAllServices(opts: {
+    strict: boolean;
+    fetchTimeoutMs?: number;
+}): Promise<ValidationResult[]>;

package/dist/validate.js

@@ -0,0 +1,88 @@
+/**
+ * Startup schema-discipline check.
+ *
+ * For each registered service, fetch its live /agents.json and verify
+ *
+ *   1. The reported schema_version is one we've seen before
+ *      (knownSchemaVersions). An unrecognized version means the
+ *      upstream service may have added/renamed/removed fields the
+ *      MCP build is not aware of - the operator should bump and re-
+ *      release this MCP package after auditing the changes.
+ *
+ *   2. Each tool's path appears somewhere in the manifest's endpoints
+ *      block. If a service renames /scan to /scan/v2 we want to fail
+ *      LOUD here, not silently 404 every agent call.
+ *
+ * On dev / first-launch we may want to tolerate manifest fetch failures
+ * (so the MCP server still starts when networking is flaky); on
+ * production we want to fail-closed. STRICT_VALIDATE=1 toggles that.
+ */
+import { SERVICES } from "./services/index.js";
+export async function validateAllServices(opts) {
+    const results = await Promise.all(SERVICES.map((s) => validateService(s, opts.fetchTimeoutMs ?? 8_000)));
+    return results;
+}
+async function validateService(svc, timeoutMs) {
+    const out = {
+        service: svc.label,
+        ok: true,
+        warnings: [],
+        errors: [],
+    };
+    let manifest = null;
+    try {
+        const ctl = new AbortController();
+        const tId = setTimeout(() => ctl.abort(), timeoutMs);
+        const r = await fetch(svc.manifestUrl, { signal: ctl.signal });
+        clearTimeout(tId);
+        if (!r.ok) {
+            out.warnings.push(`manifest fetch returned HTTP ${r.status}`);
+        }
+        else {
+            manifest = (await r.json());
+        }
+    }
+    catch (e) {
+        out.warnings.push(`manifest fetch failed: ${e.message}`);
+    }
+    if (!manifest) {
+        // No live manifest - we can still start, but flag it so the
+        // operator knows the validator didn't actually verify anything.
+        return out;
+    }
+    const liveVersion = String(manifest["schema_version"] ?? "");
+    if (liveVersion && !svc.knownSchemaVersions.includes(liveVersion)) {
+        const msg = `${svc.label} reports schema_version=${liveVersion}; this MCP build ` +
+            `expects one of [${svc.knownSchemaVersions.join(", ")}]. Audit upstream ` +
+            `changes and bump knownSchemaVersions.`;
+        if (svc.knownSchemaVersions.length === 0) {
+            out.warnings.push(msg);
+        }
+        else {
+            out.errors.push(msg);
+            out.ok = false;
+        }
+    }
+    // Endpoint-presence check. The manifest's endpoints block is a flat
+    // map of names to URLs/paths. We consider a tool valid if ANY entry
+    // in the manifest contains the tool's path as a substring (covers
+    // entries like '/events?since=<event_id>&limit=...').
+    const endpoints = manifest["endpoints"];
+    if (endpoints && typeof endpoints === "object") {
+        const flat = Object.values(endpoints)
+            .map((v) => String(v))
+            .join(" ");
+        for (const tool of svc.tools) {
+            // Strip path params for the substring match.
+            const skeleton = tool.path.replace(/\{[^}]+\}/g, "").replace(/\/+$/, "");
+            if (skeleton && !flat.includes(skeleton)) {
+                out.errors.push(`tool ${tool.name} declares path ${tool.path} but the manifest ` +
+                    `does not advertise that endpoint. Either rename the tool or add ` +
+                    `the new path to ${svc.label}'s endpoints.`);
+                out.ok = false;
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@xrpl-utilities/mcp",
+  "version": "0.1.6",
+  "description": "Model Context Protocol server for the XRPL-Utilities portfolio: Sentinel (wallet classifier), Pulse (signal feed), Telemetry (supply + utility floor), and Trust (XLS-70/80/81 directory). Exposes each service's read endpoints as MCP tools so AI agents can discover and use them via stdio (Claude Desktop) or HTTP/SSE (hosted at mcp.xrpl-utilities.io). Stateless passthrough — caller provides their own x402 payment header.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "xrpl-utilities-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "start:stdio": "node dist/index.js --transport stdio",
+    "start:http": "node dist/index.js --transport http",
+    "dev": "tsc --watch",
+    "test": "node --test dist/tests/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "express": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "xrpl",
+    "x402",
+    "ai-agents",
+    "xrp",
+    "rlusd",
+    "xrpl-utilities"
+  ],
+  "homepage": "https://xrpl-utilities.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XRPL-Utilities/xrpl-utilities-mcp.git"
+  }
+}