solana-x402-compliance

x402 MCP 服务

一个轻量、精简的 Model Context Protocol （MCP）服务，将 Solana Enterprise Payment Gateway 的 POST /api/v1/compliance/screen-address 端点作为自主工具提供给 AI Agent（Claude Desktop、Cursor、VS Code Cline、ElizaOS）。

Agent 会在每次筛查时透明地协商并结算 x402 微支付：接收 HTTP 402 Payment Required 挑战，在内存中签署 Ed25519 通道凭证（使用 Node.js 内置的 crypto，无需 Web3 SDK），然后在请求中加入 PAYMENT-SIGNATURE 标头并重试。

独立 npm 包

该服务已作为独立包发布到 npm 注册表——运行时无需克隆或构建：

npx -y @msantagiulianab/x402-mcp-server

请参阅 package.json，了解当前版本和元数据。该包包含编译后的 ESM dist/ 包，以及此 README 和 LICENSE。

目录结构

agent-tools/mcp-server/
├── src/
│   ├── base58.ts          # zero-dependency Base58 codec
│   ├── ed25519.ts         # Node crypto Ed25519 keypair + canonical payload
│   ├── x402-client.ts     # autonomous X402Client (402 -> sign -> retry)
│   └── index.ts           # MCP server + tool registration
├── test/                  # offline unit + stdio integration tests
├── test-agent-call.js     # live verification against the running Docker stack
├── package.json
├── smithery.yaml          # Smithery registry manifest
└── tsconfig.json

安装与构建

cd agent-tools/mcp-server
npm install
npm run build          # tsc -> dist/ (ESM)

运行（stdio 传输）

npx -y @msantagiulianab/x402-mcp-server   # published package
# or, from a local checkout:
npm start
# or: node dist/index.js

环境变量：

变量	默认值	用途
X402_GATEWAY_URL	https://msb-solana-enterprise-payment-gateway.duckdns.org	网关根 URL
X402_CHANNEL_ID	chan_smoke_test_001	x402 支付通道 ID
X402_PRIVATE_KEY_SEED	smoke-test-payer-seed-v1 的 sha256	64 位十六进制或 UTF-8 材料种子

X402_GATEWAY_URL 和 X402_CHANNEL_ID 由 MCP 宿主（Claude Desktop、Cline、Smithery 等）注入；X402_PRIVATE_KEY_SEED 为可选项，默认使用确定性的冒烟测试付款方。

工具 screen_solana_address：

• 描述： 根据制裁名单和威胁情报数据库检查 Solana 地址。通过 x402 自动协商并结算微支付。
• 输入： address — 有效的 Base58 Solana 公钥（解码后为 32 字节）。
• 输出： 格式化的 JSON 文本，包含 verdict、riskScore、flags 和评估时间戳。

工具 get_channel_status：

• 描述： 获取指定 x402 支付通道当前的运行状态、限额和结算状态。
• 输入： channel_id — 支付通道的唯一标识符。
• 输出： 格式化的 JSON 文本，包含 status（"ACTIVE"）、currency（"USDC"）、network（"solana-devnet"）、capacity（"10000.00"）和 lastSettlementBlock。

工具 generate_compliance_report：

• 描述： 根据制裁名单和威胁情报日志，为 Solana 钱包地址或交易签名生成不可篡改的审计摘要报告。
• 输入： identifier — Solana 钱包地址（32 字节 Base58）或交易签名（64 字节 Base58）。
• 输出： 格式化的 JSON 文本，包含 complianceStatus（"PASSED" | "FLAGGED" | "UNSCREENED"）、riskScore（已筛查标识符对应的数字，未筛查时为 null）、flags、sanctionsMatch、checkedLists（未筛查时为 []，否则为 ["OFAC", "EU_SANCTIONS", "CHAIN_REPUTATION"]）、lastEvaluated、evaluationTimestamp、timestamp 和 reportId。该报告采用失败关闭策略：它会引用会话的内存筛查账本，在标识符通过 screen_solana_address 实时筛查前返回 "UNSCREENED"。

架构与同步工作流

此组件是代码仓库中三个可独立部署的部分之一。根据变更所在的位置，同步方式有所不同：

变更所在位置	同步／部署操作
Java 后端（src/main/...）	推送到 GitHub，然后在 Hetzner VPS 上运行 git pull，以重建／重启容器或 jar。
MCP 服务（agent-tools/mcp-server/src/...）	更新 package.json 中的 version，然后运行 npm publish。
文档／smithery.yaml（README.md、smithery.yaml）	只需推送到 GitHub——无需重新加载 VPS，也无需运行 npm publish。

后端和 MCP 服务独立部署：Java 变更无需运行 npm publish，MCP 变更也无需重新加载 VPS。 文档和注册表元数据（smithery.yaml）仅通过 GitHub 发布。

smithery.yaml

smithery.yaml 是 Smithery 注册表清单。它声明了 stdio startCommand （npx -y @msantagiulianab/x402-mcp-server），并公开两个可配置字段 ——gatewayUrl 和 channelId——分别映射到 X402_GATEWAY_URL 和 X402_CHANNEL_ID 环境变量。更新后只需推送到 GitHub；Smithery 注册表会直接从代码仓库为其编制索引。

测试

npm test

此命令会编译项目并运行：

• base58.test.js — 验证 Base58 编解码往返及 32 字节地址。
• ed25519.test.js — 黄金向量检查，确保规范载荷和 Ed25519 签名与 smoke-test.sh／JVM 的 PaymentVoucher 布局完全一致。
• x402-client.test.js — 针对模拟网关进行完整的 402→签名→重试协商， 并独立验证生成的凭证中的 Ed25519 签名。
• mcp-server.test.js — 启动实际服务，并通过 stdio 使用 MCP 客户端与其交互（列出工具并调用 screen_solana_address）。

对运行中堆栈进行实时验证

启动 Docker 堆栈后（docker compose up -d --build）：

npm run test:tool

此操作会针对 http://localhost:8080 测试工具处理程序：

• 未标记的地址 4Nd1mBQtrMJVYVfKf2PJy9NZGibCcTRxpETqdrBHu19Y → CLEAR_TO_TRANSACT。
• 已标记的地址 Fc1EwQUZyTEagaDvA1utHXCcZNyG1x2PLt2DfNu1cJdH → BLOCKED。

客户端配置

Claude Desktop

添加到 claude_desktop_config.json：

macOS／Linux

{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "npx",
      "args": ["-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}

VS Code Cline

添加到 cline_mcp_settings.json：

{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "npx",
      "args": ["-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}

Cursor

添加 MCP 服务条目（Settings → MCP），指向相同的 npx -y @msantagiulianab/x402-mcp-server 命令，并设置上述环境 变量。

ElizaOS

注册一个基于 stdio 的 MCP 客户端插件，使用相同的 npx -y @msantagiulianab/x402-mcp-server 命令；Agent 即可调用工具 screen_solana_address。