sudzikcoin

@suverselabs/mcp-server

一个 MCP 服务，为 Claude Desktop（或任何 MCP 客户端）提供 15 个工具，用于调用 SuVerse 的按次付费美国政府和货运 API。每次请求都会通过 x402 协议自动使用 Base 上的 USDC 付款——你只需为钱包充值一次，Claude 就能在工作时付款。你的私钥不会离开你的设备。

✅ 已发布到 npm： https://www.npmjs.com/package/@suverselabs/mcp-server

快速开始

通过 npx 安装（无需本地构建）：

npx -y @suverselabs/mcp-server

Claude Desktop 设置

添加到 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "suverse": {
      "command": "npx",
      "args": ["-y", "@suverselabs/mcp-server"],
      "env": {
        "SUVERSE_BASE_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE"
      }
    }
  }
}

私钥控制着一个 Base 钱包，用于支付工具调用的 USDC 费用。向其中存入约 $5-10 USDC（Base 网络）。无需 ETH 支付 Gas 费——Base 结算由 Gas 赞助。你可以随时使用免费的 suverse_balance 工具查看余额。

重启 Claude Desktop。15 个 SuVerse 工具将显示在 Claude 的工具列表中。

什么是 SuVerse？

SuVerse 是一个 x402 网关，接入了 128 项美国政府数据服务（SEC、NPS、FBI、CMS 等），以及货运单据解析和路线规划套件。每次调用的费用从几分之一美分到 $0.50 不等；无需账户或 API 密钥——只需按次使用 USDC 付款。

为什么使用 MCP？

没有这个服务，你就得自行编写 x402 付款逻辑来调用 SuVerse。有了它，这些端点会作为 Claude 原生工具显示：用自然语言提出请求，Claude 就会调用它们，并从你已充值的 Base 钱包中透明地付款。

工具

付费（每次调用使用 Base 上的 USDC 付款）

工具	价格	用途
freight_parse_ratecon	$0.10	运价确认单 → JSON
freight_parse_bol_pod	$0.15	提单 / POD → JSON
freight_parse_fuel_receipt	$0.05	燃油收据 → JSON（IFTA）
freight_parse_w9	$0.07	IRS W-9 → JSON
freight_parse_insurance_cert	$0.08	ACORD 25 COI → JSON
freight_parse_permit	$0.25	超限/超重许可证 → JSON
freight_truck_route	$0.50	符合卡车通行规定的路线 + 收费信息 + 兴趣点
freight_calculate_tolls	$0.10	计算折线路线的收费预估
freight_trip_telematics	$0.01	GPS 行程分析
gov_query	$0.005	按 ID 调用 128 项政府服务中的任意一项
gov_cms_open_payments	$0.01	按 NPI 查询 CMS Open Payments
gov_fbi_crime_data	$0.01	按州/年份查询 FBI 犯罪统计数据

免费（无需付款）

工具	用途
gov_list_services	查看 128 个 gov_query 服务 ID 和参数
suverse_estimate_cost	调用前预估单次或多次调用的价格
suverse_balance	链上 USDC 余额，以及各工具的剩余调用次数
suverse_search_endpoints	搜索 SuVerse 所知的所有 x402 端点（自有端点 + CDP Bazaar 镜像）

聚合评估结果（x402，无需托管——服务不会付款）

工具	价格	回答的问题
suverse_market_pulse	$0.10	当前加密货币市场处于什么状态？
suverse_wallet_reputation	$0.03	这个 Solana 钱包的交易是否可信或值得跟随？
suverse_token_check	$0.05	现在买入这个 Solana 代币是否合理？

这三个工具的工作方式与上面的付费工具不同：此服务不会为它们付款，也不持有用于这些工具的密钥。 不付款调用时，它们会返回结构化的 payment_required 结果，其中包含端点的回答内容、价格，以及原样返回的 x402 挑战（accepts 支持 Base、Solana 和 Cosmos Noble，均使用 USDC）。你的 Agent（或其运行时）可以决定是否付款：使用任意 x402 买家客户端（例如 @suverselabs/x402-client）为其中一个 accepts 签名，然后再次调用该工具，并将 payment_signature 设置为 base64 请求头值——它会被转发为 PAYMENT-SIGNATURE / X-PAYMENT，并返回完整的付费评估结果（{verdict, signals, data_quality, raw}）。在发起任何网络调用前，钱包和 mint 参数都会在客户端进行 base58 格式校验。

使用示例

• “解析 ~/Downloads/load_4471.pdf 中的货运报价单。” → freight_parse_ratecon（file_path）
• “可以调用哪些政府服务？” → gov_list_services
• “解析 10 份提货单要花多少钱？” → suverse_estimate_cost
• “我的 SuVerse 余额是多少？” → suverse_balance
• “获取 Apple 的 SEC 公司信息。” → gov_query（service: "sec.company_info"）

file_path 输入

文档工具接受本地 file_path——服务会读取文件，通过魔数验证文件确实是 PDF/图像，并将其编码为 base64。无需将 base64 粘贴到聊天中。

费用透明度与安全性

• 每个付费工具的描述都会注明价格；suverse_estimate_cost 可提前估算费用。
• **硬性上限：**单次调用结算金额绝不会超过 SUVERSE_MAX_PAYMENT_USDC（默认 $0.60），也绝不会超过工具公布的价格；取两者中的较低值。
• **客户端幂等性：**在短时间窗口内重复执行相同请求会返回缓存的响应，而不会重复付费（补充 SuVerse 服务端的幂等性保障）。

安全性

• SUVERSE_BASE_PRIVATE_KEY 从环境中读取，仅用于在本地签署 EIP-3009 USDC 授权，绝不会记录日志，也绝不会传输到任何地方；但会作为已签名的付款标头发送给 SuVerse。
• 所有诊断信息都输出到 stderr（stdout 是 MCP 协议通道）。
• file_path 读取范围限制在你的主目录内（可通过 SUVERSE_ALLOW_PATHS_OUTSIDE_HOME=true 覆盖），并拒绝访问敏感位置（.ssh、.aws、credentials、密钥文件等），同时验证内容类型。

发送到设备之外的数据

文档解析工具会将文件内容（以 base64 编码，或通过 pdf_base64 / image_base64 / text 传入的内容）上传到 api.suverse.io 进行解析。因此，虽然你的私钥不会离开设备，你要求 Claude 解析的文档会离开设备。只传入你愿意交由 SuVerse 处理的文件。上述 file_path 保护措施（主目录限制、敏感位置拒绝列表、魔数类型检查）限制了可读取的文件范围，但任何实际解析的文件都会被传输。免费工具（gov_list_services、suverse_estimate_cost、suverse_balance）以及链上余额读取都不会发送文件数据。

配置参考

环境变量	默认值	说明
SUVERSE_BASE_PRIVATE_KEY	—	**必填。**0x Base 私钥。
SUVERSE_API_BASE	https://api.suverse.io
SUVERSE_MAX_PAYMENT_USDC	0.60	单次调用的硬性上限。
SUVERSE_BASE_RPC_URL	viem 默认值	用于读取 suverse_balance。
SUVERSE_ALLOW_PATHS_OUTSIDE_HOME	false	允许 file_path 指向 $HOME 之外。
SUVERSE_IDEMPOTENCY_TTL_MS	120000	客户端幂等性窗口。

开发

适用于贡献者或从源代码运行。最终用户应使用上方的 npx 快速开始。

git clone https://github.com/sudzikcoin/suverse-mcp && cd suverse-mcp
npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest (mocked HTTP)
npm run build       # tsup → dist/index.js
npm run dev         # run from source (tsx)

要在 Claude Desktop 中运行本地构建，请将 command/args 指向构建后的文件，而不是 npx：

{
  "mcpServers": {
    "suverse": {
      "command": "node",
      "args": ["/absolute/path/to/suverse-mcp/dist/index.js"],
      "env": { "SUVERSE_BASE_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE" }
    }
  }
}

许可证

MIT