solana-x402-compliance

x402 MCP サーバー

軽量で無駄のないModel Context Protocol （MCP）サーバーです。Solana Enterprise Payment Gateway の POST /api/v1/compliance/screen-address エンドポイントを、AI エージェント（Claude Desktop、Cursor、VS Code Cline、ElizaOS）向けの自律型ツールとして公開します。

エージェントは、各スクリーニング時に 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	sha256 of smoke-test-payer-seed-v1	64 桁の 16 進数、または 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 バイト）。
• 出力： verdict、riskScore、flags、および評価タイムスタンプを含む、整形済み JSON テキスト。

ツール get_channel_status：

• 説明： 指定された x402 決済チャネルの現在の稼働状況、上限、および決済状態を取得します。
• 入力： channel_id — 決済チャネルの一意の識別子。
• 出力： status（"ACTIVE"）、currency（"USDC"）、network（"solana-devnet"）、capacity（"10000.00"）、および lastSettlementBlock を含む、整形済み JSON テキスト。

ツール generate_compliance_report：

• 説明： Solana ウォレットアドレスまたはトランザクション署名について、制裁対象者リストおよび脅威インテリジェンスのログと照合した、不変の監査サマリーレポートを生成します。
• 入力： identifier — Solana ウォレットアドレス（32 バイトの Base58）またはトランザクション署名（64 バイトの Base58）。
• 出力： complianceStatus（"PASSED" | "FLAGGED" | "UNSCREENED"）、riskScore（スクリーニング済みの識別子の場合は数値、未スクリーニングの場合は null）、flags、sanctionsMatch、 checkedLists（未スクリーニングの場合は []、それ以外の場合は ["OFAC", "EU_SANCTIONS", "CHAIN_REPUTATION"]）、lastEvaluated、 evaluationTimestamp、timestamp、および reportId を含む、整形済み JSON テキスト。このレポートはフェイルクローズ方式です。セッション内のメモリ上のスクリーニング台帳を参照し、screen_solana_address で対象の識別子がライブスクリーニングされるまで "UNSCREENED" を返します。

アーキテクチャと同期ワークフロー

このコンポーネントは、リポジトリ内で独立してデプロイできる3つの領域のうちの1つです。変更がどこにあるかによって、同期方法は異なります。

変更箇所	同期／デプロイ操作
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）を宣言し、設定可能な2つのフィールド である 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

同じ npx -y @msantagiulianab/x402-mcp-server コマンドと上記の環境変数を指定して、MCP サーバーのエントリーを追加します（Settings → MCP）。

ElizaOS

同じ npx -y @msantagiulianab/x402-mcp-server コマンドを使用して、stdio ベースの MCP クライアントプラグインを登録します。これにより、エージェントからツール screen_solana_address を呼び出せるようになります。