commercebridge

CommerceBridge

一个远程 MCP 服务，用于封装在线的 Commerce API——通过统一的 /v1 合约提供 eBay、Shopify、Best Buy 和 Etsy 市场数据——并将其作为 MCP 工具，供任何 Agent（Claude、ChatGPT 等）直接调用。

在线服务： https://commercebridge-isaiahduprees-projects.vercel.app/mcp（Vercel 项目 commercebridge，团队 isaiahduprees-projects）——共 14 个工具，已通过真实生产数据验证（Shopify 在线可用；eBay/Best Buy/Etsy 尚未配置其上游应用密钥，因此如实标记为受限）。命名说明： 简洁的 commercebridge.vercel.app 别名归属一个无关的第三方产品（一款 WhatsApp 电商聊天机器人）——请使用上述团队专属 URL，与 commerce-api 的别名冲突情况相同。

CommerceBridge 不进行抓取，也不存储任何自有数据：每个工具都是对上游 Commerce API 的轻量、忠实的 fetch 中继。该 API 返回什么，工具就原样返回什么，包括错误。

为什么无需身份验证

此连接器底层的数据——eBay/Shopify/Best Buy/Etsy 市场商品信息——完全公开，不包含任何用户专属状态。无需登录账户，无需授权，也没有按席位计费。因此，CommerceBridge 特意不提供以下内容：

• 无 OAuth——没有登录流程、令牌交换，也没有 /.well-known/oauth-* 端点
• 无 Supabase——没有用户表，也没有会话存储
• 无计费——没有套餐、用量计量，也没有升级门槛

这与本组织为其姊妹连接器 StoreBridge 所做的架构选择相同；StoreBridge 处理 App Store/Google Play 数据：公开的只读市场数据采用轻量、无状态的构建方式。与本组织基于 OAuth 的 Bridge 系列连接器（RemindersBridge、MessagesBridge 等）相比，它刻意做得更精简；后者代理的是已登录用户自己的私有数据，因此需要身份验证。

工具

共 14 个工具，每个对应一个 Commerce API 端点，并按市场/引擎分组：

eBay — 上游部署需要配置 EBAY_CLIENT_ID / EBAY_CLIENT_SECRET

工具	端点	功能
search_ebay	GET /v1/search	按关键词/类别搜索 eBay 上的实时商品信息，覆盖 8 个站点（US、GB、DE、AU、CA、FR、IT、ES）
get_ebay_item	GET /v1/item	根据 REST ID 或旧版 ID 获取一件 eBay 商品的完整详情
get_ebay_items	GET /v1/items	一次调用批量获取最多 20 件 eBay 商品
search_ebay_sold	GET /v1/sold	已售/已结束商品的可比信息——需要 eBay 单独设限的 Marketplace Insights API

Shopify — 无需密钥，目前已在线可用

工具	端点	功能
search_shopify_products	GET /v1/shopify/products	从任意公开 Shopify 商店自己的 /products.json 获取其商品目录
get_shopify_product	GET /v1/shopify/product	根据 handle 获取一件商品
get_shopify_collections	GET /v1/shopify/collections	列出商店的商品集合
search_shopify	GET /v1/shopify/search	按关键词筛选商店的商品目录（标题/供应商/类型/标签）

Best Buy — 上游尚未上线（路由待重新部署，之后需要 BESTBUY_API_KEY）

工具	端点	功能
search_bestbuy	GET /v1/bestbuy/search	按关键词/类别搜索 Best Buy 的美国商品目录
get_bestbuy_product	GET /v1/bestbuy/product	根据 SKU 获取一件商品

Etsy — 上游尚未上线（路由待重新部署，之后需要 ETSY_KEYSTRING + ETSY_SHARED_SECRET）

工具	端点	功能
search_etsy	GET /v1/etsy/search	全站活跃商品关键词搜索
get_etsy_listing	GET /v1/etsy/listing	获取一个商品（仅此端点会填充 views）
get_etsy_shop	GET /v1/etsy/shop	通过 shop_id 或 shop_name 获取一个店铺
get_etsy_shop_listings	GET /v1/etsy/shop/listings	列出店铺的活跃商品

每个工具都标注为 {readOnlyHint:true, destructiveHint:false, idempotentHint:true, openWorldHint:true} —— 只读、非破坏性、幂等，且数据源开放／外部。

预期的上游错误 —— 并非故障

目前只有 Shopify 已上线。 其他所有引擎的工具调用都会返回 MCP 工具错误（isError: true），其文本是上游原样返回的错误信息封装 —— 但不同引擎返回的具体错误各不相同，因为上游 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 还始终会返回 501 not_enabled，无论是否配置 eBay 密钥 —— 该端点需要 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 刻意不会捕获、隐藏或伪造任何这些情况 —— 工具处理程序会将上游的响应原样传递为 {isError: true, content: [{type:'text', text: '<code>: <message>'}]}，无论是 not_found、credentials_required，还是之后的真实数据。

配置

环境变量	默认值	用途
COMMERCE_API_BASE_URL	https://commerce-api-isaiahduprees-projects.vercel.app	上游 Commerce API 基础 URL。可覆盖此值，以指向暂存版／本地 Commerce API 部署。

无需其他配置。此仓库中不应存放任何密钥 —— API 密钥仅存放在上游 commerce-api 部署中。

本地运行

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

部署

npx vercel --yes --prod

就是这样 —— CommerceBridge 本身无需任何环境变量（只有上游 commerce-api 部署需要其 marketplace 应用密钥）。部署后，将任意 MCP 客户端指向：

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

本地冒烟测试

npm test 会运行 test/smoke.mjs，通过内存传输将真实 MCP Client 连接到 lib/tools.js 中的 buildServer()（与 api/mcp.js 通过 HTTP 提供服务的服务器代码完全相同），并检查：

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 是第二项更精简的检查：它会在普通的 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)