proxy-shopping: buy anywhere with crypto through a proxy shopper

proxy-shopping MCP サーバー

AI エージェントが proxy-shopping P2P ネットワークをツールとして利用できるMCPサーバーです。

• プロキシショッパーを介して、現金のみ対応または非対応の店舗から、2-of-3 エスクローを使って暗号資産で購入できます。 BTC を注文ごとのエスクロー（購入者、ショッパー、エスクロー）に支払います。ショッパーが購入して発送し、商品が届いたら支払いを解放します。問題が発生した場合は、エスクローが分配を決定します。また、T2 タイムロックの後は、すべての資金を自分だけで取り戻せます。
• プロキシショッパーとして収入を得られます。 常時オンラインのショッパーノードを運用するための詳細な手順と、登録されるためのレジストリエントリが用意されています。

エージェントの隣で（stdio）、独自の鍵を持つ1つの参加者として動作します。プロトコルのロジックには、ウェブアプリと同じコードである @proxy-shopping/core を使用します。サーバーの実行中はセッションが維持されるため、見積もり、配送状況の更新、裁定結果が届き続け、データディレクトリに保存されます。レジストリ名：io.github.pad01g/proxy-shopping

公開ネットワーク ps-main は新しく、信頼できるショッパーがまだいない場合があります（信頼済みのショッパー × エスクローの組み合わせ数は network_info で確認できます）。そこでの支払いは BTC のサインネットで行われます。サインネットは、市場価値のないコインを使うテストネットワークです。ps-main では USDC はまだ利用できません。

実行

Claude Code：

claude mcp add proxy-shopping -- docker run -i --rm -v proxy-shopping-mcp:/data ghcr.io/pad01g/proxy-shopping-mcp:0.1.2

その他のクライアント（mcp.json）：

{
  "mcpServers": {
    "proxy-shopping": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "proxy-shopping-mcp:/data", "ghcr.io/pad01g/proxy-shopping-mcp:0.1.2"]
    }
  }
}

/data のボリュームには鍵と注文が保存されます。必ず保持してください。このボリュームがないと、すべての未完了注文のエスクローを管理する鍵を失います（export_backup でバックアップしてください）。データディレクトリ1つにつきIDは1つです。エージェントごと、または人ごとに別のボリュームを使用してください。

ローカルの Docker Compose ラボ（proxy-shopping-go、デモサーバーは http://localhost:8888）：

claude mcp add proxy-shopping-lab -- docker run -i --rm --add-host=host.docker.internal:host-gateway \
  -v proxy-shopping-mcp-lab:/data -e PS_NETWORK=lab -e PS_LAB_URL=http://host.docker.internal:8888 \
  ghcr.io/pad01g/proxy-shopping-mcp:0.1.2

MCPB バンドル（Claude Desktop などの MCPB クライアント向け。ファイルを開いてインストールします。Node 22 以降が必要です）：releasesから proxy-shopping-<version>.mcpb を入手してください。npm run build -w @proxy-shopping/core の後に node packages/mcp/scripts/build-mcpb.mjs を実行してビルドできます。サーバーをインストールするエージェント向け：llms-install.md。

Docker を使わない場合（Node 22、リポジトリのルートから）：npm ci && npm run build -w @proxy-shopping/core -w @proxy-shopping/mcp を実行し、次に node packages/mcp/dist/server.js を実行します（bin proxy-shopping-mcp）。

変数	デフォルト	意味
PS_NETWORK	ps-main	ps-main：公開 Nostr リレー（relay.damus.io、nos.lol、relay.primal.net）、mempool.space 経由の BTC サインネット、registryからのコーディネーターと署名済み信頼イベント。lab：デモサーバーを介した Compose ラボ
PS_DATA_DIR	~/.proxy-shopping-mcp（イメージ：/data）	ニーモニック（mnemonic、モード 0600、初回実行時に作成）とネットワークごとの状態（state-<network>.json）
PS_LAB_URL	http://localhost:8888	lab 専用：デモサーバー（リレーは /relay-1 /relay-2、/esplora、/evm、/faucet、/rates、/deployments/31337.json）
PS_CONFIG_URL / PS_CONFIG_FILE	未設定	プリセットを上書きするウェブアプリの config.json（形式は proxy-shopping-go/lab/web-config.json と同じで、relays、coordinators、esplora、evm_rpc、deployments_url、rates、timelock_policy、…を含みます）
PS_COORDINATORS	未設定	プリセットの信頼ルートを置き換える、カンマ区切りのコーディネーター公開鍵

ツール

ツール	機能
network_info	ネットワーク、リレー、コーディネーター、チェーン、信頼されている購入者 × エスクローの組み合わせ数、正確なステータス
wallet	ID の公開鍵、BTC signet アドレスと残高（ネットワークで対応している場合は EVM／USDC）
lab_faucet	ラボ専用：このウォレットにテスト用 BTC／USDC を送金し、ブロックをマイニング
find_offers	ショップ URL、地域、支払い方法に対応する、信頼されている購入者 × エスクローの組み合わせ。手数料、現金対応地域、来歴（コーディネーター → オペレーターのリスト）を含む
request_quote	1 つの組み合わせで注文し、見積もりを待機。その検証結果を返す：独自の情報源とのレートの乖離、再計算したエスクローアドレス、タイムロック
get_order / list_orders	ステータス、タイムライン、次の手順。get_order はステータスを待機できます
accept_quote	有効な見積もりを承認（レートの乖離が大きい場合は acknowledge_rate_deviation が必要）
fund_order	資金を移動します：ロック分とエスクローの前払い手数料を支払う（confirm: true）
confirm_receipt	資金を移動します：商品を受け取り、購入者への支払いに署名する（confirm: true）
open_dispute	エスクローに裁定を依頼し、証拠と自分のアドレスの鍵を渡す（confirm: true）
review_ruling / countersign_ruling	エスクローによる分割内容を確認し、連署する（資金を移動します、confirm: true）
accept_refund_offer	資金を移動します：購入者による協力的な返金に連署する（confirm: true）
refund_after_timelock	資金を移動します：T2 の後、単独で資金を取り戻す（confirm: true）
cancel_order	資金を入れる前に注文をキャンセル
report	購入者またはエスクローを、登録したオペレーターに報告
export_backup	12 語のニーモニックを表示（confirm: true）
become_shopper	プロキシ購入者として収益を得るための計画：要件、手数料、ps-main のノード設定と compose ファイル、登録方法
registry_entry	レジストリへのプルリクエスト用ファイルを、指定の形式で正確に生成：shoppers/<name>.json {pk, contact, description, regions (cash regions), payments, escrows}、escrows/<name>.json {pk, contact, description, sla_days}、operators/<name>.json {pk, contact, description, regions}、coordinators/<name>.json {pk, contact, description, url?, bundle?}

購入の流れ：network_info → wallet（資金を入れる）→ find_offers → request_quote → accept_quote → fund_order → （delivered になるまで get_order）→ confirm_receipt。

すべてのツールは短いテキストと、同じデータを含む構造化 JSON を返します。

安全性

• 資金を移動するツールや秘密情報を開示するツールは、confirm: true がない限り何も実行しません。指定がない場合は、実行した場合の内容（金額、受取人、手数料）を表示します。エージェントはそれを人に示し、確認を求めてから実行してください。
• 検証に失敗した見積もり（信頼されていない組み合わせ、独自の計算結果と一致しないエスクローアドレス、ポリシーの範囲外のタイムロック、合計が一致しない金額）は承認できません。独自の情報源とのレートの乖離が 10％を超える場合は、明示的な確認が必要です。
• 支払いへの署名は、プロトコルで許可されたテンプレート（購入者への支払い、返金、分割内容に一致する裁定）に限られます。チェーン上で支払いが確認された場合にのみ、completed／settled／refunded と報告されます。
• ニーモニックがデータディレクトリの外に出るのは、export_backup を通じてのみです。配送先アドレスは購入者に対して暗号化されており、エスクローが読み取れるのは、異議申し立てを開始した場合のみです。
• 信頼は、設定したコーディネーターからのみ得られます（network_info には、そのコーディネーターと情報の出所が表示されます）。注文の信頼性は、オペレーターが登録した購入者とエスクロー次第です。

テスト

# from the repository root, in Docker (no host Node needed)
docker run --rm -v "$PWD":/src -v ps-npm:/root/.npm -w /src node:22-bookworm \
  sh -c "npm ci && npm run build -w @proxy-shopping/core && npm test -w @proxy-shopping/mcp"

# end to end against the running compose lab: a BTC order through MCP tool calls over stdio
docker run --rm --add-host=host.docker.internal:host-gateway -v "$PWD":/src -v ps-npm:/root/.npm -w /src/packages/mcp \
  -e PS_LAB_URL=http://host.docker.internal:8888 node:22-bookworm npm run test:lab

単体テストでは、MCP クライアントを介して、コアのメモリ内ワールド（リレー、チェーン、スクリプト化された買い物客、エスクロー）に対して各ツールを実行し、registry_entry が書き込むファイルに対してレジストリ独自のバリデーター（proxy-shopping-registry/scripts/registry.ts validate）を実行します。テストでは、このリポジトリの隣に ../proxy-shopping-registry があること（または PS_REGISTRY_DIR が設定されているか、/proxy-shopping-registry にマウントされていること）を想定しています（SKIP_REGISTRY=1 を指定するとスキップされます）。上記の Docker コマンドに -v "$PWD/../proxy-shopping-registry":/proxy-shopping-registry:ro を追加してください。