@xrpl-utilities/mcp 0.1.6

package/README.md

@@ -0,0 +1,109 @@
+# @xrpl-utilities/mcp
+
+[Model Context Protocol](https://modelcontextprotocol.io) server for the
+XRPL-Utilities™ portfolio. Exposes the read endpoints of all four
+services as MCP tools so AI agents can discover and use them — either
+locally via stdio (Claude Desktop, MCP Inspector, etc.) or remotely
+via the hosted endpoint at `mcp.xrpl-utilities.io`.
+
+## Services covered
+
+| Service       | What it does                                            | Tools |
+|---------------|---------------------------------------------------------|-------|
+| **XR-Sentinel**  | XRPL wallet activity-pattern classifier (0-100 score, 22-signal catalog, AI narrative) | `xrpl_sentinel_scan`, `xrpl_sentinel_scan_history` |
+| **XR-Pulse**     | Normalized XRPL signal feed — public-source news + on-chain whale activity + XLS-70/80/81 lifecycle | `xrpl_pulse_recent_events` |
+| **XR-Telemetry** | XRPL macro snapshot — supply, liquidity, AMM, Active Float, Burst Math utility floor | `xrpl_telemetry_snapshot`, `xrpl_telemetry_get_quote`, `xrpl_telemetry_get_status`, `xrpl_telemetry_get_results` |
+| **XR-Trust**     | Directory + drill-down for XRPL permissioned-asset stack (XLS-70/80/81 + XLS-40 DID) | `xrpl_trust_list_domains`, `xrpl_trust_get_domain`, `xrpl_trust_credential_issuers`, `xrpl_trust_recent_events` |
+
+11 tools total, all read-only. Every paid call is settled via x402 v2
+on the XRPL mainnet through the t54 facilitator.
+
+## Auth model
+
+The MCP server is a **stateless passthrough proxy**. It does not hold
+wallets, manage user accounts, or subsidize calls.
+
+For paid tools (every endpoint at $0.10 USD), the caller supplies a
+`payment_signature` argument: a base64-JSON-encoded x402 v2 payment
+header signing an XRPL Payment that matches one of the requirements
+returned by an unauthenticated probe. The server forwards it as the
+`PAYMENT-SIGNATURE` header on the underlying call.
+
+If you don't supply `payment_signature`, the underlying service
+returns its real `402 Payment Required` challenge with the XRP +
+RLUSD requirements. The MCP server passes that back to the LLM as
+a structured error so it can sign and retry.
+
+Operators can set `MCP_BYPASS_KEY` on the server to enable an opt-in
+bypass for friendlies / demos. The caller passes the matching key as
+`_bypass_key` in the tool args. Rate-limited at the proxy layer.
+
+## Use it
+
+### Locally via Claude Desktop (stdio)
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "xrpl-utilities": {
+      "command": "npx",
+      "args": ["-y", "@xrpl-utilities/mcp", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 11 tools should appear with the prefix
+`xrpl_`. Ask Claude to "scan the wallet rXXX with XR-Sentinel" or
+"list permissioned domains on XRPL" and the tool calls flow through.
+
+### Remotely (HTTP/SSE)
+
+Point any MCP client at `https://mcp.xrpl-utilities.io/mcp`. Same
+tool list, same auth model.
+
+## What you need to actually pay
+
+To avoid 402 challenges on every call, your client needs to:
+
+1. Hold a funded XRPL wallet (XRP + optional RLUSD trustline).
+2. On each paid tool call, sign a Payment matching one of the
+   `accepts` entries from a prior probe.
+3. Pass the base64-JSON-encoded header as `payment_signature`.
+
+The Python reference implementation is
+[`x402-xrpl`](https://pypi.org/project/x402-xrpl/) — useful as a
+template even if you're using a different language.
+
+## Local dev
+
+```bash
+npm install
+npm run build
+node dist/index.js --transport http --port 8080
+```
+
+Point MCP Inspector at `http://localhost:8080/mcp` to walk through
+tool definitions interactively.
+
+## Releases
+
+Releases are cut by tag push. The `Release` workflow builds, validates
+that `package.json` version matches the tag, then publishes to npm
+with sigstore provenance.
+
+```bash
+npm version patch       # or minor / major
+git push --follow-tags  # pushes commit + tag, CI does the rest
+```
+
+The published artifact appears at
+[npmjs.com/package/@xrpl-utilities/mcp](https://www.npmjs.com/package/@xrpl-utilities/mcp)
+within ~90 seconds. Provenance attestation is visible on the package
+page as a green check.
+
+## License
+
+MIT. Full portfolio at [xrpl-utilities.com](https://xrpl-utilities.com).

package/dist/dispatch.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Tool dispatcher: receives an MCP tool call, looks up the owning
+ * service + tool, builds the underlying HTTP request, forwards the
+ * response.
+ *
+ * Auth model (per-tool, see ToolDef.authMode):
+ *
+ *   inline_x402   - caller passes payment_signature in tool args; the
+ *                   dispatcher forwards it as the PAYMENT-SIGNATURE
+ *                   header. Standard x402 v2; \$0.10 USD settled inline
+ *                   via the t54 facilitator on every successful call.
+ *
+ *   async_invoice - MCP wrapper around one step of Telemetry's three-
+ *                   step flow (quote -> pay -> status -> results). The
+ *                   wrapper itself doesn't carry a payment header; the
+ *                   actual XRPL Payment happens out-of-band when the
+ *                   caller pays the deeplink returned by quote.
+ *
+ *   free          - no payment ever. Reserved for future pure-metadata
+ *                   wrappers; not used by any current tool.
+ *
+ * Operator-issued bypass: if MCP_BYPASS_KEY is set on the MCP process
+ * AND an inline_x402 tool call includes a matching `_bypass_key` in
+ * args, the dispatcher forwards it as the dev-bypass header on the
+ * underlying service (rate-limited at the MCP transport layer).
+ *
+ * The web-origin bypass that the marketing site uses is deliberately
+ * NOT honored here: that bypass is meant for the human-facing site,
+ * not for agent traffic. Otherwise the MCP server would silently turn
+ * a paid agent API into a free one.
+ */
+export interface DispatchOptions {
+    /**
+     * Global bypass key from the MCP_BYPASS_KEY env var. When the caller
+     * also presents this key (via the `_bypass_key` reserved tool arg),
+     * the dispatcher uses it as the dev-bypass header on the underlying
+     * service. Rate-limited by the caller (see transport-http).
+     */
+    bypassKey?: string;
+    /** Override base URLs (useful for tests pointing at localhost). */
+    baseUrlOverride?: (serviceId: string) => string | undefined;
+    /**
+     * Identity string put on the User-Agent header so service-side logs
+     * can distinguish MCP traffic from direct API users.
+     */
+    userAgent?: string;
+}
+/**
+ * Run a single tool call. Throws on missing tool / network error /
+ * non-2xx upstream response. Caller (the MCP server adapter) is
+ * responsible for catching and converting to an MCP-shaped error.
+ */
+export declare function dispatchTool(toolName: string, args: Record<string, unknown>, opts?: DispatchOptions): Promise<unknown>;

package/dist/dispatch.js

@@ -0,0 +1,158 @@
+/**
+ * Tool dispatcher: receives an MCP tool call, looks up the owning
+ * service + tool, builds the underlying HTTP request, forwards the
+ * response.
+ *
+ * Auth model (per-tool, see ToolDef.authMode):
+ *
+ *   inline_x402   - caller passes payment_signature in tool args; the
+ *                   dispatcher forwards it as the PAYMENT-SIGNATURE
+ *                   header. Standard x402 v2; \$0.10 USD settled inline
+ *                   via the t54 facilitator on every successful call.
+ *
+ *   async_invoice - MCP wrapper around one step of Telemetry's three-
+ *                   step flow (quote -> pay -> status -> results). The
+ *                   wrapper itself doesn't carry a payment header; the
+ *                   actual XRPL Payment happens out-of-band when the
+ *                   caller pays the deeplink returned by quote.
+ *
+ *   free          - no payment ever. Reserved for future pure-metadata
+ *                   wrappers; not used by any current tool.
+ *
+ * Operator-issued bypass: if MCP_BYPASS_KEY is set on the MCP process
+ * AND an inline_x402 tool call includes a matching `_bypass_key` in
+ * args, the dispatcher forwards it as the dev-bypass header on the
+ * underlying service (rate-limited at the MCP transport layer).
+ *
+ * The web-origin bypass that the marketing site uses is deliberately
+ * NOT honored here: that bypass is meant for the human-facing site,
+ * not for agent traffic. Otherwise the MCP server would silently turn
+ * a paid agent API into a free one.
+ */
+import { findToolOwner } from "./services/index.js";
+/**
+ * Run a single tool call. Throws on missing tool / network error /
+ * non-2xx upstream response. Caller (the MCP server adapter) is
+ * responsible for catching and converting to an MCP-shaped error.
+ */
+export async function dispatchTool(toolName, args, opts = {}) {
+    const owner = findToolOwner(toolName);
+    if (!owner) {
+        throw new Error(`unknown tool: ${toolName}`);
+    }
+    const { service, tool } = owner;
+    const baseUrl = opts.baseUrlOverride?.(service.id) ?? service.baseUrl;
+    // Substitute path params (e.g. /domain/{domain_id}) from args.
+    let path = tool.path;
+    const consumedPathArgs = new Set();
+    path = path.replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, (_, key) => {
+        if (!(key in args)) {
+            throw new Error(`tool ${toolName} requires path parameter ${key}, missing from args`);
+        }
+        consumedPathArgs.add(key);
+        return encodeURIComponent(String(args[key]));
+    });
+    // Strip args reserved for transport-level concerns (payment_signature,
+    // _bypass_key) AND args already consumed by path params. What remains
+    // is the actual API payload.
+    const stripSet = new Set([
+        ...(tool.stripArgs ?? []),
+        "_bypass_key",
+        "payment_signature",
+    ]);
+    const apiArgs = {};
+    for (const [k, v] of Object.entries(args)) {
+        if (consumedPathArgs.has(k))
+            continue;
+        if (stripSet.has(k))
+            continue;
+        apiArgs[k] = v;
+    }
+    // Auth resolution. The caller can either supply payment_signature
+    // (which we forward as PAYMENT-SIGNATURE) or _bypass_key (which we
+    // verify against MCP_BYPASS_KEY before forwarding to the underlying
+    // service as its dev-bypass header).
+    const headers = {
+        Accept: "application/json",
+        "User-Agent": opts.userAgent ?? "xrpl-utilities-mcp/0.1.6",
+    };
+    const callerPaymentSig = stringArg(args.payment_signature);
+    const callerBypassKey = stringArg(args._bypass_key);
+    if (tool.authMode === "inline_x402") {
+        if (callerPaymentSig) {
+            headers["PAYMENT-SIGNATURE"] = callerPaymentSig;
+        }
+        else if (callerBypassKey && opts.bypassKey && callerBypassKey === opts.bypassKey) {
+            // Operator-issued bypass. Forward as the dev-bypass header that
+            // the underlying services accept (D_BYPASS_KEY pattern).
+            headers["PAYMENT-SIGNATURE"] = callerBypassKey;
+        }
+        else {
+            // No auth supplied. Fire the request anyway so the caller gets
+            // the real 402 challenge back from the underlying service - that
+            // tells them what payment_signature shape to send next time. The
+            // MCP server is a transparent proxy here, not an enforcer.
+        }
+    }
+    // async_invoice + free both fall through with no PAYMENT-SIGNATURE
+    // header. async_invoice tools wrap the Telemetry quote/status/results
+    // flow where payment happens out-of-band; free is reserved for
+    // future pure-metadata wrappers.
+    // Build the request URL (query for GET, body for POST).
+    let url = baseUrl + path;
+    let body;
+    if (tool.method === "GET") {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(apiArgs)) {
+            if (v === undefined || v === null)
+                continue;
+            params.append(k, String(v));
+        }
+        const qs = params.toString();
+        if (qs)
+            url += "?" + qs;
+    }
+    else if (tool.method === "POST") {
+        if (tool.bodyFromArgs) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(apiArgs);
+        }
+    }
+    // Run the request. The MCP SDK gives us 30+ seconds of headroom on
+    // most clients; we cap at 60s here so an upstream stall surfaces as
+    // a timeout error instead of hanging the MCP session forever.
+    const ctl = new AbortController();
+    const timeoutId = setTimeout(() => ctl.abort(), 60_000);
+    let res;
+    try {
+        res = await fetch(url, { method: tool.method, headers, body, signal: ctl.signal });
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parsed = text;
+    }
+    // Surface 402 challenges + 4xx/5xx errors as structured errors so
+    // the LLM can reason over them and retry with a payment_signature.
+    if (!res.ok) {
+        return {
+            _error: true,
+            status: res.status,
+            response: parsed,
+            hint: res.status === 402
+                ? "This endpoint requires x402 payment. Sign an XRPL Payment matching one of the entries in 'accepts', base64-JSON-encode it, and pass as payment_signature."
+                : undefined,
+        };
+    }
+    return parsed;
+}
+function stringArg(v) {
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Entry point. Dispatches to stdio or HTTP transport based on a
+ * --transport flag (or the MCP_TRANSPORT env var).
+ *
+ * Usage:
+ *   xrpl-utilities-mcp --transport stdio   # for Claude Desktop config
+ *   xrpl-utilities-mcp --transport http    # for hosted Railway deploy
+ *
+ * Default is stdio so the npm-published entry-point Just Works when
+ * Claude Desktop launches it.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Entry point. Dispatches to stdio or HTTP transport based on a
+ * --transport flag (or the MCP_TRANSPORT env var).
+ *
+ * Usage:
+ *   xrpl-utilities-mcp --transport stdio   # for Claude Desktop config
+ *   xrpl-utilities-mcp --transport http    # for hosted Railway deploy
+ *
+ * Default is stdio so the npm-published entry-point Just Works when
+ * Claude Desktop launches it.
+ */
+import { runStdio } from "./transport/stdio.js";
+import { runHttp } from "./transport/http.js";
+import { validateAllServices } from "./validate.js";
+function parseArgs(argv) {
+    let transport = (process.env["MCP_TRANSPORT"] === "http" ? "http" : "stdio");
+    let port = Number(process.env["PORT"] ?? "8080");
+    let skipValidate = process.env["MCP_SKIP_VALIDATE"] === "1";
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--transport" || a === "-t") {
+            const v = argv[++i];
+            if (v === "stdio" || v === "http")
+                transport = v;
+        }
+        else if (a === "--port" || a === "-p") {
+            port = Number(argv[++i] ?? port);
+        }
+        else if (a === "--skip-validate") {
+            skipValidate = true;
+        }
+    }
+    return { transport, port, skipValidate };
+}
+async function main() {
+    const { transport, port, skipValidate } = parseArgs(process.argv.slice(2));
+    // Schema-discipline check. On stdio we run silently and only complain
+    // on stderr (Claude Desktop captures stdout for the JSON-RPC stream).
+    // On HTTP we log normally.
+    if (!skipValidate) {
+        const results = await validateAllServices({ strict: false });
+        const log = transport === "stdio" ? console.error : console.log;
+        for (const r of results) {
+            if (r.errors.length) {
+                log(`[validate] ${r.service}: ERRORS`);
+                r.errors.forEach((e) => log(`  ${e}`));
+            }
+            if (r.warnings.length) {
+                log(`[validate] ${r.service}: warnings`);
+                r.warnings.forEach((w) => log(`  ${w}`));
+            }
+        }
+        const anyError = results.some((r) => r.errors.length);
+        if (anyError && process.env["MCP_FAIL_ON_DRIFT"] === "1") {
+            process.exit(2);
+        }
+    }
+    if (transport === "stdio") {
+        await runStdio();
+    }
+    else {
+        await runHttp(port);
+    }
+}
+main().catch((e) => {
+    console.error("xrpl-utilities-mcp fatal:", e);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/jsonschema.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Minimal JSON Schema typing. The MCP SDK accepts plain objects as
+ * tool input schemas; we only need a small subset of Draft 7 to
+ * describe the args we care about (string / number / object / etc.).
+ */
+export interface JSONSchema7 {
+    type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+    description?: string;
+    properties?: Record<string, JSONSchema7>;
+    required?: string[];
+    enum?: unknown[];
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    items?: JSONSchema7;
+    additionalProperties?: boolean | JSONSchema7;
+    default?: unknown;
+    examples?: unknown[];
+}

package/dist/jsonschema.js

@@ -0,0 +1,7 @@
+/**
+ * Minimal JSON Schema typing. The MCP SDK accepts plain objects as
+ * tool input schemas; we only need a small subset of Draft 7 to
+ * describe the args we care about (string / number / object / etc.).
+ */
+export {};
+//# sourceMappingURL=jsonschema.js.map

package/dist/jsonschema.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP server core. Wires the registered tools into the MCP SDK's
+ * Server abstraction and routes incoming tool calls through the
+ * dispatcher. Transport-agnostic — the same Server object is later
+ * connected via stdio (transport-stdio) or HTTP/SSE (transport-http).
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type DispatchOptions } from "./dispatch.js";
+export declare function buildServer(opts?: DispatchOptions): Server;

package/dist/server.js

@@ -0,0 +1,93 @@
+/**
+ * MCP server core. Wires the registered tools into the MCP SDK's
+ * Server abstraction and routes incoming tool calls through the
+ * dispatcher. Transport-agnostic — the same Server object is later
+ * connected via stdio (transport-stdio) or HTTP/SSE (transport-http).
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ALL_TOOLS, SERVICES } from "./services/index.js";
+import { dispatchTool } from "./dispatch.js";
+const SERVER_NAME = "xrpl-utilities";
+const SERVER_VERSION = "0.1.6";
+export function buildServer(opts = {}) {
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {}, resources: {} } });
+    // ---- Tools ---------------------------------------------------------------
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: ALL_TOOLS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const args = (req.params.arguments ?? {});
+        try {
+            const result = await dispatchTool(req.params.name, args, opts);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `xrpl-utilities-mcp dispatch error: ${e.message}`,
+                    },
+                ],
+            };
+        }
+    });
+    // ---- Resources -----------------------------------------------------------
+    // Each service's live agents.json + /schema is exposed as a resource
+    // so the LLM can fetch the full manifest / output-shape detail without
+    // a tool call. This is the MCP-native way to surface "static-ish"
+    // documentation alongside the actionable tools.
+    const resources = SERVICES.flatMap((s) => [
+        {
+            uri: `${s.baseUrl}/agents.json`,
+            mimeType: "application/json",
+            name: `${s.label} agents.json`,
+            description: `Live agent-discovery manifest for ${s.label}: schema_version, capabilities, endpoint catalog, payment requirements.`,
+        },
+        {
+            uri: `${s.baseUrl}/schema`,
+            mimeType: "application/json",
+            name: `${s.label} /schema`,
+            description: `Field-level output shape for ${s.label} responses. Source of truth for what each tool returns.`,
+        },
+    ]);
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources,
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        const uri = req.params.uri;
+        const ctl = new AbortController();
+        const tId = setTimeout(() => ctl.abort(), 10_000);
+        try {
+            const r = await fetch(uri, { signal: ctl.signal });
+            const text = await r.text();
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: r.headers.get("content-type") ?? "application/json",
+                        text,
+                    },
+                ],
+            };
+        }
+        finally {
+            clearTimeout(tId);
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/services/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Master service registry. Adding a new XR-* service is a single line:
+ * import the new module + push it onto SERVICES.
+ *
+ * Tool names are globally namespaced (xrpl_<service>_<verb>) so cross-
+ * service calls in one MCP session don't collide with each other or
+ * with any other MCP server the user may have connected.
+ */
+import type { ServiceDef } from "../types.js";
+export declare const SERVICES: ServiceDef[];
+/** Flat list of every tool across every registered service. */
+export declare const ALL_TOOLS: {
+    _serviceId: string;
+    _baseUrl: string;
+    name: string;
+    description: string;
+    inputSchema: import("../jsonschema.js").JSONSchema7;
+    method: import("../types.js").HttpMethod;
+    path: string;
+    authMode: import("../types.js").AuthMode;
+    bodyFromArgs?: boolean;
+    stripArgs?: string[];
+}[];
+/** Look up the owning service for a given tool name. */
+export declare function findToolOwner(toolName: string): {
+    service: ServiceDef;
+    tool: ServiceDef["tools"][number];
+} | null;

package/dist/services/index.js

@@ -0,0 +1,25 @@
+/**
+ * Master service registry. Adding a new XR-* service is a single line:
+ * import the new module + push it onto SERVICES.
+ *
+ * Tool names are globally namespaced (xrpl_<service>_<verb>) so cross-
+ * service calls in one MCP session don't collide with each other or
+ * with any other MCP server the user may have connected.
+ */
+import { sentinel } from "./sentinel.js";
+import { pulse } from "./pulse.js";
+import { telemetry } from "./telemetry.js";
+import { trust } from "./trust.js";
+export const SERVICES = [sentinel, pulse, telemetry, trust];
+/** Flat list of every tool across every registered service. */
+export const ALL_TOOLS = SERVICES.flatMap((s) => s.tools.map((t) => ({ ...t, _serviceId: s.id, _baseUrl: s.baseUrl })));
+/** Look up the owning service for a given tool name. */
+export function findToolOwner(toolName) {
+    for (const service of SERVICES) {
+        const tool = service.tools.find((t) => t.name === toolName);
+        if (tool)
+            return { service, tool };
+    }
+    return null;
+}
+//# sourceMappingURL=index.js.map

package/dist/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,MAAM,CAAC,MAAM,QAAQ,GAAiB,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;AAE1E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9C,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CACtE,CAAC;AAEF,wDAAwD;AACxD,MAAM,UAAU,aAAa,CAAC,QAAgB;IAG5C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;QAC5D,IAAI,IAAI;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/services/pulse.d.ts

@@ -0,0 +1,12 @@
+/**
+ * XR-Pulse: normalized XRPL signal feed bridging public-source news,
+ * on-chain whale activity, and XLS-70/80/81 permissioned-domain
+ * lifecycle events into one time-ordered stream.
+ *
+ * News carries a four-hour XRPL price-window correlation. Whale rows
+ * carry sender + receiver addresses with XRPScan institutional
+ * labels. Permissioned-domain rows mirror XR-Trust's /events with
+ * cross-product enrichment. Paid via x402 ($0.10 USD per query).
+ */
+import type { ServiceDef } from "../types.js";
+export declare const pulse: ServiceDef;