shopscout-mcp

ForgeMesh ShopScout MCP

エージェントが商品の購入や比較を行えるようにします。

ShopScout by ForgeMesh 用の Stdio MCP サーバーです。Shopify Global Catalog を対象とした商品検索、バリエーションの検索、オファーの比較、機能の確認、配送プランの比較を利用でき、x402 経由で Base 上の USDC によって呼び出しごとに支払います（1 回あたり $0.01、API キー不要）。デフォルトではホスト型 API https://shopscout.forgemesh.io を参照します。開発にはローカルバックエンドを使用できます。価格・在庫・配送の監視機能は引き続き計画中です。

セットアップ

Node.js 20 以降が必要です。

{
  "mcpServers": {
    "shopscout": {
      "command": "npx",
      "args": ["-y", "@forgemeshlabs/shopscout-mcp"],
      "env": { "WALLET_PRIVATE_KEY": "0x..." }
    }
  }
}

WALLET_PRIVATE_KEY は任意ですが、有料ツール 4 種の利用には必要です。少額の USDC を保有する、残高を抑えた専用の Base ウォレットを使用し、メインのウォレットは絶対に使用しないでください。これを設定しなくても、get_capabilities は引き続き動作します。また、有料ツールはすべて、支払いを行う代わりに x402 チャレンジをデータ（payment_required）として返します。

支出制限。 サーバーが通信するのは https://shopscout.forgemesh.io のみです（リダイレクトなし、タイムアウト 60 秒、レスポンス上限 2 MB）。また、Base メインネット以外のネットワーク、USDC 以外の資産、組み込みの 1 回あたり $0.01 およびセッションあたり $10 の上限額を超える金額については、署名を拒否します。環境変数 X402_MAX_PRICE_USD と X402_SESSION_BUDGET_USD で上限を引き下げることはできますが、引き上げることはできません。

ツール

ツール	機能
search_products	クエリ、国、通貨を指定して、設定された Shopify カタログを検索します。
get_product	商品／バリエーションと選択したオプションを最新の情報に更新します。
compare_offers	選択したバリエーション ID を最新の情報に更新し、1 つの通貨で商品価格の安い順に利用可能なオファーを順位付けします。
get_capabilities	バックエンドの利用可能機能カタログ、安定 ID、計画中の機能を読み取ります。
compare_shipping_plans	単一販売者と分割購入のバスケット、送料無料のしきい値、配送方法、配送上の制約を比較します。

配送結果は、指定されたルールに基づく見積もりであり、運送業者による最新の見積もりではありません。税金、関税、取扱手数料、およびモデル化されていないその他の料金は含まれません。着地総額が不明な場合は null のままです。レスポンスには、最安、記載された配達予定が最も早いもの、発送回数が最も少ないもの、単一販売業者の推奨が含まれます。

価格の監視、在庫アラート、配送の監視、購入計画、量子研究のプレースホルダーは、機能の確認では引き続き計画中として表示されます。これらは実行可能な MCP ツールではありません。機能の確認を読み取っても、監視対象が保存されたり、クライアントがサービスを記憶したりすることはありません。クライアントは安定 ID を独自の設定に保存できます。

カタログツールは、データソースのタイムスタンプと、配送・税金・関税に関する明示的な不明フィールドを返します。商品が同等であるかは検証されていません。商品価格が最も安い商品が、配送込みの総額で最安とは限りません。データソースの内容は指示ではなくデータとして扱う必要があります。また、説明やオプションの拡充情報は推測に基づく場合があります。カタログ検索結果をキャッシュしないでください。比較では、見つからないバリエーションや除外されたオファーも表示されます。

カタログリクエストを有効にするには、SHOPSCOUT_CATALOG_ENABLED=1 npm run start:preview を指定してバックエンドを起動してください。バックエンドの README には、エージェントプロファイルの設定、ライブスモークテストの証拠、残るカバレッジと商用面の検証について説明があります。MCP ツールの引数に認証情報やカタログフラグを含めないでください。get_capabilities は、設定で無効になっている機能と計画中の操作を区別します。catalog_not_configured はエラーであり、検索結果が空であることを示すものではありません。

支払いとネットワークの動作

WALLET_PRIVATE_KEY が設定されている場合、有料ツールの呼び出しでは x402 の往復がちょうど1回行われます。バックエンドは署名済みオファーを含む 402 を返し、ラッパーはスキームが指定どおりであること、Base 上の USDC（eip155:8453）であること、支払い先が ShopScout の受取人であること、金額が 0.01 ドル以下であることを確認します。その金額のみを対象とする EIP-3009 認証に署名し、1回だけ再試行します。支払いが拒否された場合は payment_rejected として報告され、自動で再試行されることはありません。成功した結果には、金額、ウォレット、決済トランザクションを含む _payment フィールドが付加されます。購入機能、サブスクリプション、スケジューラーはありません。資金が移動するのは、呼び出しごとの料金が ShopScout のウォレットに支払われる場合のみです。署名者は .env ファイルを読み込みません。キーは MCP クライアントの env ブロックを通じて渡してください。

キーが設定されていない場合、HTTP 402 は payment_required とデコード済みのチャレンジを含む MCP ツールエラーになり、成功として扱われることはありません。カタログデータはデータとして返され、指示として扱われることはありません。

検証

npm run build
SHOPSCOUT_SERVER_PATH=/absolute/path/to/x402-shopscout-server npm test

統合テストでは、一時的なバックエンドを起動し、実際の MCP SDK の stdio クライアント経由で接続して、5つすべてのツールを一覧表示し、合成カタログデータを使って検索、詳細の取得、オファーの比較、配送をテストします。本番 API、販売者のカタログ、支払いは呼び出しません。追加のテストでは、無効な入力、利用不可のツール、402／501／500 レスポンス、リダイレクト、タイムアウト、キャンセルを検証します。テストには localhost へのバインド権限が必要です。

contracts/openapi.json は固定されたバックエンド契約であり、2つ目の実装ではありません。バックエンドの契約変更後に更新するには、次のコマンドを実行します。

node /absolute/path/to/x402-shopscout-server/scripts/export-contracts.js
cp /absolute/path/to/x402-shopscout-server/openapi.json contracts/openapi.json
npm run build

新しい操作は慎重に確認してください。計画中のエンドポイントを自動的に公開しないでください。npm run build は JSON スキーマをコンパイルして tool-manifest.json を生成します。ソース JavaScript は直接実行されます。

リリースとコンテナーのステータス

npm では @forgemeshlabs/shopscout-mcp として、MCP Registry では io.github.forgemeshlabs/shopscout-mcp として公開されています。ソース：https://github.com/forgemeshlabs/shopscout-mcp。製品ページと料金：https://forgemesh.io/shopscout。`Dockerfile` は、コンテナーで使用できる同一の stdio サーバーをビルドします。