commercebridge

CommerceBridge

ライブのCommerce API（eBay、Shopify、Best Buy、Etsyのマーケットプレイスデータを単一の/v1コントラクトで提供）をラップし、あらゆるエージェント（Claude、ChatGPTなど）が直接呼び出せるMCPツールとして提供するリモートMCPサーバーです。

ライブURL： https://commercebridge-isaiahduprees-projects.vercel.app/mcp（Vercelプロジェクトcommercebridge、チームisaiahduprees-projects） — 14個のツールを提供し、実際の本番データで検証済みです（Shopifyは稼働中。eBay／Best Buy／Etsyは、各サービスのアプリキーが発行されるまで正直に利用制限を設けています）。名前に関する注意： commercebridge.vercel.appという分かりやすいエイリアスは、無関係なサードパーティ製品（WhatsAppコマースのチャットボット）が所有しています。commerce-apiのエイリアス競合と同様に、上記のチームスコープ付きURLを使用してください。

CommerceBridgeはスクレイピングを行わず、独自のデータも保持しません。各ツールは、上流のCommerce APIへ忠実にfetchを中継するだけです。APIから返される内容は、エラーも含めて変更せずにそのまま返されます。

認証が不要な理由

このコネクターが扱うデータ（eBay／Shopify／Best Buy／Etsyのマーケットプレイス掲載情報）はすべて公開されており、ユーザーごとの状態を一切持ちません。ログインするアカウントも、認可が必要なものも、ユーザーごとの課金もありません。そのため、CommerceBridgeは意図的に次の構成になっています。

• OAuthなし — ログインフロー、トークン交換、/.well-known/oauth-*エンドポイントはありません
• Supabaseなし — ユーザーテーブルやセッションストレージはありません
• 課金なし — プラン、使用量の計測、アップグレード制限はありません

これは、App Store／Google Playのデータを扱う兄弟コネクターStoreBridgeで、この組織が採用した設計判断と同じです。公開されている読み取り専用のマーケットプレイスデータには、軽量でステートレスな構成を採用しています。サインインしたユーザー自身の非公開データをプロキシし、認証が必要な、この組織のOAuthベースのBridge系コネクター（RemindersBridge、MessagesBridgeなど）よりも意図的にシンプルな構成です。

ツール

Commerce APIの各エンドポイントに対応する14個のツールを、マーケットプレイス／エンジンごとにまとめています。

eBay — 上流のデプロイにEBAY_CLIENT_ID／EBAY_CLIENT_SECRETが必要です

Tool	Endpoint	機能
search_ebay	GET /v1/search	8つのサイト（US、GB、DE、AU、CA、FR、IT、ES）を対象に、キーワード／カテゴリでeBayの出品を検索します
get_ebay_item	GET /v1/item	REST IDまたは旧形式のIDで、eBayの商品1件の詳細を取得します
get_ebay_items	GET /v1/items	1回の呼び出しで最大20件のeBay商品を一括取得します
search_ebay_sold	GET /v1/sold	販売済み／取引完了商品の相場データを取得します。eBayの別途利用制限があるMarketplace Insights APIが必要です

Shopify — キー不要、現在稼働中

Tool	Endpoint	機能
search_shopify_products	GET /v1/shopify/products	任意の公開Shopifyストアの/products.jsonから商品カタログを一覧表示します
get_shopify_product	GET /v1/shopify/product	ハンドルで商品1件を取得します
get_shopify_collections	GET /v1/shopify/collections	ストアのコレクションを一覧表示します
search_shopify	GET /v1/shopify/search	キーワードでストアの商品カタログを絞り込みます（タイトル／販売元／商品タイプ／タグ）

Best Buy — 上流ではまだ稼働していません（ルートの再デプロイ後、BESTBUY_API_KEYが必要です）

Tool	Endpoint	機能
search_bestbuy	GET /v1/bestbuy/search	キーワード／カテゴリでBest Buyの米国カタログを検索します
get_bestbuy_product	GET /v1/bestbuy/product	SKUで商品1件を取得します

Etsy — upstream ではまだ稼働していません（ルートは再デプロイ待ち。その後、ETSY_KEYSTRING と ETSY_SHARED_SECRET が必要です）

ツール	エンドポイント	機能
search_etsy	GET /v1/etsy/search	サイト全体の有効な出品をキーワード検索します
get_etsy_listing	GET /v1/etsy/listing	1件の出品を取得します（views が設定される唯一のエンドポイントです）
get_etsy_shop	GET /v1/etsy/shop	shop_id または shop_name で1件のショップを取得します
get_etsy_shop_listings	GET /v1/etsy/shop/listings	ショップの有効な出品を一覧表示します

すべてのツールには {readOnlyHint:true, destructiveHint:false, idempotentHint:true, openWorldHint:true} という注釈が付いています。つまり、読み取り専用、非破壊的、冪等で、オープンな外部データソースを対象とします。

想定される upstream のエラー — バグではありません

現在稼働しているのは Shopify のみです。 それ以外のエンジンへのツール呼び出しはすべて、MCP ツールエラー（isError: true）を返します。そのテキストは upstream のエラーエンベロープをそのまま示したものですが、upstream の commerce-api 本番デプロイが現在、独自のソースリポジトリより遅れているため、エラーの内容はエンジンによって異なります。

• eBay（search_ebay*、get_ebay*）— ルートはデプロイされていますが、アプリキーがプロビジョニングされていないため、次のエラーが返ります。

  credentials_required: eBay app credentials required — set EBAY_CLIENT_ID and EBAY_CLIENT_SECRET (free at developer.ebay.com). This API wraps eBay's free Browse API.
  

  search_ebay_sold は eBay のキーの有無にかかわらず、常に 501 not_enabled というゲートエラーを返します。このエンドポイントには eBay の別途承認が必要な Marketplace Insights API が必要で、基本の Browse API キーでは利用できません。

• Best Buy（search_bestbuy、get_bestbuy_product）と Etsy（search_etsy*、get_etsy*）— この文書の執筆時点では、これらのエンジンのコードは commerce-api ソースリポジトリにありますが、稼働中の本番デプロイにはまだ含まれていません。そのため、実際に確認したところ、これらのルートは HTTP レイヤーで 404 を返します。

  not_found: No route for GET /v1/bestbuy/search
  not_found: No route for GET /v1/etsy/shop
  

  commerce-api が再デプロイされると、キーがプロビジョニングされるまでは credentials_required（BESTBUY_API_KEY／ETSY_KEYSTRING+ETSY_SHARED_SECRET が未設定）に変わり、キーがプロビジョニングされると実データを返すようになります。ここで変更する必要は一切ありません。

CommerceBridge は、これらの状況を意図的に捕捉したり、隠したり、偽装したりしません。ツールハンドラーは、upstream が返す内容を {isError: true, content: [{type:'text', text: '<code>: <message>'}]} としてそのまま渡します。not_found、credentials_required、そして将来的な実データのいずれも同様です。

設定

環境変数	デフォルト値	用途
COMMERCE_API_BASE_URL	https://commerce-api-isaiahduprees-projects.vercel.app	upstream の Commerce API ベース URL です。ステージング環境やローカルの Commerce API デプロイを指定するには、値を上書きしてください。

これ以外の設定はありません。このリポジトリにシークレットを置かないでください。API キーは upstream の commerce-api デプロイにのみ設定します。

ローカルで実行

npm install
npm test              # local smoke test — initialize, tools/list, 2x tools/call (see below)

デプロイ

npx vercel --yes --prod

以上です。CommerceBridge 自体には環境変数は必要ありません（マーケットプレイスのアプリキーが必要なのは upstream の commerce-api デプロイのみです）。デプロイ後、任意の MCP クライアントから次の接続先を指定してください。

https://<your-deployment>.vercel.app/api/mcp

ローカルスモークテスト

npm test は test/smoke.mjs を実行します。このテストでは、lib/tools.js の buildServer() に対して、メモリ内トランスポート経由で実際の MCP Client を接続します（HTTP 経由で api/mcp.js が提供するものとまったく同じサーバーコードです）。そして、次の項目を確認します。

1. initialize — サーバーが自身を commercebridge v1.0.0 として識別する
2. tools/list — 14 個すべてのツールが存在し、それぞれにオブジェクト型の inputSchema と想定どおりの RO アノテーションがある
3. tools/call → search_shopify_products（store: "allbirds.com"）— isError が false であり、marketplace: "shopify" を含む実際の商品が返されることを確認します。これにより、実際のデータがエンドツーエンドで流れることを証明します
4. tools/call → search_ebay — isError が true で、エラーテキストに credentials_required が含まれることを確認します。これにより、上流側の適切なゲートによるエラーが、クラッシュではなく、クリーンな MCP ツールエラーとして表面化することを証明します

test/local-server.mjs は、さらに簡易的な 2 つ目のチェックです。通常の http.Server の背後で実際の api/mcp.js／api/health.js ハンドラーを実行し、Vercel 向けのハンドラー自体が（GET／DELETE → 405、/api/health → {ok, service, upstream}）、SDK のメモリ内トランスポートの外でも機能することを確認します。

アーキテクチャ

lib/tools.js   — buildServer(): McpServer + all 14 tool registrations + upstream fetch relay
api/mcp.js     — POST /api/mcp — stateless StreamableHTTPServerTransport, no auth
api/health.js  — GET /api/health — {ok, service, upstream}
test/          — smoke.mjs (in-memory client/server), local-server.mjs (HTTP handler check)