Xrpl Utilities

@xrpl-utilities/mcp

面向 XRPL-Utilities™ 产品组合的模型上下文协议服务。将全部六项服务的读取端点作为 MCP 工具提供，供 AI Agent 发现并使用；既可通过 stdio 在本地使用（Claude Desktop、MCP Inspector 等），也可通过托管端点 mcp.xrpl-utilities.io 远程使用。

涵盖的服务

服务	功能	工具
XR-Sentinel	XRPL 钱包活动模式分类器：活动评分、信号目录、标签上下文、AI 叙述；还提供免费的检查，用于验证 x402 卖方是否控制其宣传的 XRPL 账户	xrpl_sentinel_scan（付费）、xrpl_sentinel_scan_history（付费）、xrpl_sentinel_verify_origin（免费）
XR-Pulse	标准化的 XRPL 事件源（新闻、大额持仓变动、RWA 铸造与销毁、Sentinel 信号）以及免费的市场视图：Ripple 交易对手方、交易所资金流、托管日历、RLUSD 分布、RWA 概览、代币健康状况。实时 WebSocket 流通过 xrpl_pulse_stream_purchase 销售	xrpl_pulse_recent_events（付费）、xrpl_pulse_events_by_address（付费）、xrpl_pulse_stream_purchase（付费）、xrpl_pulse_ripple_counterparties（免费）、xrpl_pulse_ripple_topology（免费）、xrpl_pulse_cex_attribution（免费）、xrpl_pulse_network_stats（免费）、xrpl_pulse_xrpl_primitives（免费）、xrpl_pulse_whale_flow_24h（免费）、xrpl_pulse_exchange_flow_delta（免费）、xrpl_pulse_rwa_summary（免费）、xrpl_pulse_exchange_net_flow（免费）、xrpl_pulse_escrow_calendar（免费）、xrpl_pulse_entity_positioning（免费）、xrpl_pulse_rlusd_distribution（免费）、xrpl_pulse_token_health（免费）
XR-Telemetry	XRPL 宏观快照（供应量、流动性、AMM、Active Float）以及结算和 DEX 成交量序列	xrpl_telemetry_snapshot（付费）、xrpl_telemetry_get_quote（付费，发票）、xrpl_telemetry_get_status（付费，发票）、xrpl_telemetry_get_results（付费，发票）、xrpl_telemetry_settlement_totals（免费）、xrpl_telemetry_settlement_series（免费）、xrpl_telemetry_dex_pair_volume（免费）
XR-Trust	XRPL 许可资产技术栈（XLS-70/80/81、XLS-40 DID）的目录与深入查询、运营方索引、司法管辖区及许可域活动	xrpl_trust_list_domains（付费）、xrpl_trust_get_domain（付费）、xrpl_trust_credential_issuers（付费）、xrpl_trust_recent_events（免费）、xrpl_trust_list_operators_index（免费）、xrpl_trust_operator_drilldown（付费）、xrpl_trust_operator_attribution（免费）、xrpl_trust_usage_summary（免费）、xrpl_trust_jurisdictions（免费）、xrpl_trust_permissioned_activity（免费）
XR-Vault	现实世界资产跟踪器：按发行方统计供应量、铸造与销毁流量、AMM 池敞口	xrpl_vault_scan（付费）、xrpl_vault_daily_flow（免费）
XR-Flows	XRP ETF 管理资产规模与 XRPL 交易所资金流的对比、上市影响及跨境资金流	xrpl_flows_scan（付费）、xrpl_flows_correlation（免费）、xrpl_flows_cross_border_flow（免费）、xrpl_flows_launch_impact（免费）、xrpl_flows_etf_flow_summary（免费）
XR-Desk	综合交易台简报：市场态势、持仓情况、RLUSD 健康状况、供应压力、RWA 市场	xrpl_desk_briefing（免费）

共 44 个工具：15 个付费，29 个免费，全部为只读工具。 付费调用通过 XRPL 上的 XRP 或 RLUSD，或 Base 上的 USDC，以 x402 v2 结算。

身份验证模型

MCP 服务是一个无状态直通代理。它不持有钱包、不管理用户账户，也不补贴调用费用。

对于付费工具（每个端点均收费 0.10 USD），调用方需提供 payment_signature 参数：一个经过 base64-JSON 编码的 x402 v2 支付头，用于签署一笔 XRPL Payment，且该支付必须符合未经过身份验证的探测请求所返回的某项要求。服务器会在底层调用中将其转发为 PAYMENT-SIGNATURE 头。

如果未提供 payment_signature，底层服务会返回真实的 402 Payment Required 挑战，其中列出三种支付选项：通过 t54 facilitator 在 XRPL 上使用 XRP 和 RLUSD，或通过 Coinbase x402 facilitator 在 Base 主网上使用 USDC。MCP 服务会将该挑战作为结构化错误传回给大模型，使其能够签名并使用钱包支持的任一种支付通道重试。

运维人员可以在服务器上设置 MCP_BYPASS_KEY，为熟悉的用户或演示启用自愿使用的绕过方式。调用方在工具参数中通过 _bypass_key 传入匹配的密钥。

托管端点会针对每位调用方单独限制失败的 _bypass_key 尝试，限制远比普通请求严格：每分钟 60 个请求的上限是公平使用限制，而非对密钥的访问控制。每次猜测都会消耗额度，而非每个 HTTP 请求，因此批量 JSON-RPC 请求体无法绕过限制；额度耗尽后，只会拦截实际携带 _bypass_key 的请求——tools/list、免费工具和付费 x402 调用仍可正常使用。批次最多包含 20 条消息。请使用至少 32 个随机字节的密钥，并为每项服务单独设置或轮换密钥，不要在整个服务组合中共用一个密钥。限流桶的键控取决于 TRUST_PROXY_HOPS 是否与容器前方代理的实际数量相符——请参阅 .env.example。

H-Seal 收据共同签名（可选）

在服务器上设置 PROVIDER_IDENTITY（我们的 CAIP-10，例如 xrpl:0:r...）和 PROVIDER_KEY_RAW（32 字节 ed25519 种子，以十六进制表示），即可为每个工具响应添加共同签名，并附上 H-Seal 提供方证明。该证明会随工具结果附加在 _meta.hSeal 中，调用方因此可以为此次交互建立防篡改、可独立验证的链上收据。任一变量未设置时，此功能都不会启用，响应保持不变。切勿将密钥硬编码——仅通过环境变量设置。

当后端为自己的输出添加共同签名时，MCP 也会生成一份双方收据（_meta.hSealReceipt）。该收据使用运维人员的密钥签名，因此请将 HSEAL_ALLOWED_PROVIDERS 设置为你愿意为其背书的 XR-* 后端 CAIP-10 身份。若未设置，则任何能够证明自己持有其所声明身份对应密钥的提供方都会被接受。responseHash 始终根据实际交付的正文重新计算；requestHash 则仍由提供方声明（后端会对 MCP 无法重现的合成请求对象进行哈希），结果会通过 requestHashBasis 说明这一点。请参阅 src/hSeal.ts 和运维手册 docs/hseal-provider.md（其中介绍当前身份、ed25519 曲线注意事项，以及如何轮换或恢复密钥）。

使用方法

在本地通过 Claude Desktop 使用（stdio）

添加到 Claude Desktop 配置文件（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "xrpl-utilities": {
      "command": "npx",
      "args": ["-y", "@xrpl-utilities/mcp", "--transport", "stdio"]
    }
  }
}

重启 Claude Desktop。44 个工具应会以 xrpl_ 前缀显示。让 Claude“使用 XR-Sentinel 扫描钱包 rXXX”或“列出 XRPL 上的许可域”，工具调用就会通过该服务。

远程使用（HTTP/SSE）

将任意 MCP 客户端指向 https://mcp.xrpl-utilities.io/mcp。工具列表和身份验证模型相同。

实际需要支付的内容

为避免每次调用都遇到 402 挑战，你的客户端需要：

1. 在至少一种受支持的支付通道上持有钱包： 一个持有 XRP（以及可选的 RLUSD 信任线）的 XRPL 钱包，或 一个在 Base 主网上持有 USDC 的 EVM 钱包。
2. 每次调用付费工具时，签署一笔符合先前探测结果中某个 accepts 条目的支付。XRPL 支付通道使用 XRPL Payment；Base 支付通道使用 EIP-3009 transferWithAuthorization。
3. 将经过 base64-JSON 编码的信封作为 payment_signature 传递。

参考实现： x402-xrpl 支持 XRPL 支付通道。官方 x402 软件包（带有 [evm] 附加组件）支持 Base USDC 支付通道。两者都可作为任意语言的模板。

本地开发

npm install
npm run build
node dist/index.js --transport http --port 8080
npm test          # builds, then runs the node:test suite in tests/

将 MCP Inspector 指向 http://localhost:8080/mcp，即可交互式查看 工具定义。

设置 STRICT_VALIDATE=1，可将无法读取的清单视为漂移，而不是警告。默认关闭此选项，是因为 Railway 会在 ON_FAILURE 时重启： 如果启动时因校验失败而关闭服务，端点就会陷入崩溃重启循环；每当某个后端尚未就绪时，还会连带使其他五个健康服务的工具无法使用。无论如何，未读取清单的服务都会记录 NOT CHECKED——“无法检查”绝不会被报告为“全部正常”。

发布

通过推送标签来发布。Release 工作流会构建项目、验证 package.json 中的版本与标签一致，然后使用 sigstore 来源证明发布到 npm，最后通过 GitHub OIDC 将相同版本同步至官方 MCP Registry（无需额外密钥）。

npm version patch       # or minor / major
git push --follow-tags  # pushes commit + tag, CI does the rest

已发布的构件会在约 90 秒内出现在 npmjs.com/package/@xrpl-utilities/mcp。 来源证明声明会以绿色勾选标记显示在软件包页面上。MCP Registry 条目位于 registry.modelcontextprotocol.io， 其反向 DNS 名称为 io.github.XRPL-Utilities/mcp。

许可证

MIT。完整项目组合见 xrpl-utilities.com。