sudzikcoin

@suverselabs/mcp-server

Claude Desktop（または任意の MCP クライアント）に、SuVerse の従量課金制の米国政府および貨物輸送 API 用の 15 個のツールを提供するMCPサーバーです。 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"
      }
    }
  }
}

秘密鍵は、ツール呼び出しの USDC 支払いに使う Base ウォレットを管理します。Base 上のウォレットに約 5～10 USDC を入金してください。ガス代用の ETH は不要です。Base での決済はガス代がスポンサーされます。残高は、無料の suverse_balance ツールでいつでも確認できます。

Claude Desktop を再起動します。Claude のツール一覧に 15 個の SuVerse ツールが表示されます。

SuVerse とは？

SuVerseは、128 の米国政府データサービス（SEC、NPS、FBI、CMS など）と、貨物書類・ルート検索機能一式を提供する x402 ゲートウェイです。呼び出しごとの料金は数十分の 1 セントから 0.50 ドルまでで、アカウントや API キーは不要です。USDC で呼び出しごとに支払います。

MCP を使う理由

このサーバーがなければ、SuVerse を呼び出すために x402 の支払い処理を自分で実装する必要があります。このサーバーを使うと、エンドポイントがネイティブな 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	トラック通行可能ルート + 通行料金 + POI
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	gov_query の 128 個のサービス ID とパラメーターを確認
suverse_estimate_cost	実行前に 1 件または複数件の呼び出し料金を見積もり
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 トークンは、今すぐ購入しても問題ありませんか？

この 3 つのツールは、上記の有料ツールとは動作が異なります。このサーバーはこれらのツールの支払いを行わず、鍵も保持しません。 支払いなしで呼び出すと、構造化された payment_required 結果が返されます。そこには、エンドポイントが返す内容、価格、および x402 チャレンジの全文（Base、Solana、Cosmos Noble での accepts。すべて USDC）が含まれます。支払うかどうかは、エージェント（またはそのランタイム）が判断します。任意の x402 購入者クライアント（例：@suverselabs/x402-client）を使っていずれかの accepts に署名し、payment_signature に base64 ヘッダー値を設定してツールを再度呼び出すと、その値が PAYMENT-SIGNATURE / X-PAYMENT として転送され、支払い後の判定結果全体（{verdict, signals, data_quality, raw}）が返されます。ウォレットとミントの引数は、ネットワーク呼び出しの前にクライアント側で base58 として検証されます。

使用例

• *"~/Downloads/load_4471.pdf のレートコンを解析して。" * → freight_parse_ratecon (file_path)
• "どの政府サービスを呼び出せますか？" → gov_list_services
• "BOL 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 では事前に料金を見積もれます。
• 厳格な上限： 1 回の呼び出しで精算される金額は、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	1 回の呼び出しあたりの厳格な上限です。
SUVERSE_BASE_RPC_URL	viem default	suverse_balance の読み取りに使用します。
SUVERSE_ALLOW_PATHS_OUTSIDE_HOME	false	$HOME の外にある file_path を許可します。
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