commercebridge

CommerceBridge

A remote MCP server that wraps the live Commerce API — eBay, Shopify, Best Buy, and Etsy marketplace data behind one /v1 contract — as MCP tools any agent (Claude, ChatGPT, etc.) can call directly.

Live: https://commercebridge-isaiahduprees-projects.vercel.app/mcp (Vercel project commercebridge, team isaiahduprees-projects) — 14 tools, verified against real production data (Shopify live; eBay/Best Buy/Etsy honestly gated until their upstream app keys are provisioned). Naming note: the clean commercebridge.vercel.app alias is owned by an unrelated third-party product (a WhatsApp-commerce chatbot) — use the team-scoped URL above, same situation as commerce-api's alias collision.

CommerceBridge does no scraping and holds no data of its own: every tool is a thin, faithful fetch relay to the upstream Commerce API. Whatever that API returns comes back unmodified, including its errors.

Why Authentication: None

This connector's underlying data — eBay/Shopify/Best Buy/Etsy marketplace listings — is fully public and carries zero per-user state. There is no account to log into, nothing to authorize, and nothing to bill per-seat. So, deliberately, CommerceBridge has:

• No OAuth — no login flow, no token exchange, no /.well-known/oauth-* endpoints
• No Supabase — no user table, no session storage
• No billing — no plans, no usage metering, no upgrade gate

This is the same architectural call this org made for StoreBridge, its sibling connector over App Store/Google Play data: public read-only marketplace data gets the lean, stateless build. It is deliberately leaner than this org's OAuth-based Bridge-family connectors (RemindersBridge, MessagesBridge, etc.), which proxy a signed-in user's own private data and do need auth.

Tools

14 tools, one per Commerce API endpoint, grouped by marketplace/engine:

eBay — needs EBAY_CLIENT_ID / EBAY_CLIENT_SECRET on the upstream deployment

Tool	Endpoint	What it does
search_ebay	GET /v1/search	Search live eBay listings by keyword/category across 8 sites (US, GB, DE, AU, CA, FR, IT, ES)
get_ebay_item	GET /v1/item	Get one eBay item's full detail by REST id or legacy id
get_ebay_items	GET /v1/items	Bulk-fetch up to 20 eBay items in one call
search_ebay_sold	GET /v1/sold	Sold/completed-item comps — needs eBay's separately-gated Marketplace Insights API

Shopify — keyless, live right now

Tool	Endpoint	What it does
search_shopify_products	GET /v1/shopify/products	List any public Shopify store's catalog from its own /products.json
get_shopify_product	GET /v1/shopify/product	Get one product by handle
get_shopify_collections	GET /v1/shopify/collections	List a store's collections
search_shopify	GET /v1/shopify/search	Keyword-filter a store's catalog (title/vendor/type/tags)

Best Buy — not yet live upstream (route pending redeploy, then needs BESTBUY_API_KEY)

Tool	Endpoint	What it does
search_bestbuy	GET /v1/bestbuy/search	Search Best Buy's US catalog by keyword/category
get_bestbuy_product	GET /v1/bestbuy/product	Get one product by SKU

Etsy — not yet live upstream (route pending redeploy, then needs ETSY_KEYSTRING + ETSY_SHARED_SECRET)

Tool	Endpoint	What it does
search_etsy	GET /v1/etsy/search	Site-wide active-listing keyword search
get_etsy_listing	GET /v1/etsy/listing	Get one listing (only endpoint where views is populated)
get_etsy_shop	GET /v1/etsy/shop	Get one shop by shop_id or shop_name
get_etsy_shop_listings	GET /v1/etsy/shop/listings	List a shop's active listings

Every tool is annotated {readOnlyHint:true, destructiveHint:false, idempotentHint:true, openWorldHint:true} — read-only, non-destructive, idempotent, over an open/external data source.

Expected upstream errors — not a bug

Only Shopify is live today. Every other engine's tool call returns an MCP tool error (isError: true) whose text is the upstream's honest error envelope, verbatim — but the exact error differs by engine, because the upstream commerce-api production deployment currently lags its own source repo:

• eBay (search_ebay*, get_ebay*) — the route is deployed, but app keys aren't provisioned, so you get:

  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 additionally always returns a 501 not_enabled gate regardless of eBay keys — that endpoint needs eBay's separately-approved Marketplace Insights API, which the base Browse API keys don't grant.

• Best Buy (search_bestbuy, get_bestbuy_product) and Etsy (search_etsy*, get_etsy*) — as of this writing, the code for these engines exists in the commerce-api source repo but the live production deployment has not been redeployed to include it yet, so these routes 404 at the HTTP layer, verified live:

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

  Once commerce-api is redeployed, these will flip to credentials_required (BESTBUY_API_KEY / ETSY_KEYSTRING+ETSY_SHARED_SECRET missing) until those keys are provisioned, then to live data — with zero changes needed here.

CommerceBridge deliberately does not catch, hide, or fake around any of this — the tool handler passes whatever the upstream says straight through as {isError: true, content: [{type:'text', text: '<code>: <message>'}]}, whether that's not_found, credentials_required, or eventually real data.

Configuration

Env var	Default	Purpose
COMMERCE_API_BASE_URL	https://commerce-api-isaiahduprees-projects.vercel.app	Upstream Commerce API base URL. Override to point at a staging/local Commerce API deployment.

No other configuration. No secrets belong in this repo — API keys live only on the upstream commerce-api deployment.

Run locally

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

Deploy

npx vercel --yes --prod

That's it — no environment variables are required for CommerceBridge itself (only the upstream commerce-api deployment needs its marketplace app keys). After deploy, point any MCP client at:

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

Local smoke test

npm test runs test/smoke.mjs, which connects a real MCP Client to buildServer() from lib/tools.js over an in-memory transport (the exact same server code api/mcp.js serves over HTTP) and checks:

1. initialize — server identifies itself as commercebridge v1.0.0
2. tools/list — all 14 tools present, each with an object inputSchema and the expected RO annotations
3. tools/call → search_shopify_products (store: "allbirds.com") — asserts isError is false and real products come back with marketplace: "shopify" — proves live data flows end-to-end
4. tools/call → search_ebay — asserts isError is true and the error text contains credentials_required — proves the upstream honest gate surfaces as a clean MCP tool error, not a crash

test/local-server.mjs is a second, thinner check that runs the actual api/mcp.js / api/health.js handlers behind a plain http.Server, to confirm the Vercel-shaped handlers themselves (GET/DELETE → 405, /api/health → {ok, service, upstream}) work outside of the SDK's in-memory transport.

Architecture

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)