{
  "markdown": "# CommerceBridge\n\nA remote MCP server that wraps the live [Commerce API](https://commerce-api-isaiahduprees-projects.vercel.app) — eBay, Shopify, Best Buy, and Etsy marketplace data behind one `/v1` contract — as MCP tools any agent (Claude, ChatGPT, etc.) can call directly.\n\n**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.\n\nCommerceBridge 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.\n\n## Why Authentication: None\n\nThis 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:\n\n- **No OAuth** — no login flow, no token exchange, no `/.well-known/oauth-*` endpoints\n- **No Supabase** — no user table, no session storage\n- **No billing** — no plans, no usage metering, no upgrade gate\n\nThis 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.\n\n## Tools\n\n14 tools, one per Commerce API endpoint, grouped by marketplace/engine:\n\n### eBay — needs `EBAY_CLIENT_ID` / `EBAY_CLIENT_SECRET` on the upstream deployment\n| Tool | Endpoint | What it does |\n|---|---|---|\n| `search_ebay` | `GET /v1/search` | Search live eBay listings by keyword/category across 8 sites (US, GB, DE, AU, CA, FR, IT, ES) |\n| `get_ebay_item` | `GET /v1/item` | Get one eBay item's full detail by REST id or legacy id |\n| `get_ebay_items` | `GET /v1/items` | Bulk-fetch up to 20 eBay items in one call |\n| `search_ebay_sold` | `GET /v1/sold` | Sold/completed-item comps — needs eBay's separately-gated Marketplace Insights API |\n\n### Shopify — keyless, live right now\n| Tool | Endpoint | What it does |\n|---|---|---|\n| `search_shopify_products` | `GET /v1/shopify/products` | List any public Shopify store's catalog from its own `/products.json` |\n| `get_shopify_product` | `GET /v1/shopify/product` | Get one product by handle |\n| `get_shopify_collections` | `GET /v1/shopify/collections` | List a store's collections |\n| `search_shopify` | `GET /v1/shopify/search` | Keyword-filter a store's catalog (title/vendor/type/tags) |\n\n### Best Buy — not yet live upstream (route pending redeploy, then needs `BESTBUY_API_KEY`)\n| Tool | Endpoint | What it does |\n|---|---|---|\n| `search_bestbuy` | `GET /v1/bestbuy/search` | Search Best Buy's US catalog by keyword/category |\n| `get_bestbuy_product` | `GET /v1/bestbuy/product` | Get one product by SKU |\n\n### Etsy — not yet live upstream (route pending redeploy, then needs `ETSY_KEYSTRING` + `ETSY_SHARED_SECRET`)\n| Tool | Endpoint | What it does |\n|---|---|---|\n| `search_etsy` | `GET /v1/etsy/search` | Site-wide active-listing keyword search |\n| `get_etsy_listing` | `GET /v1/etsy/listing` | Get one listing (only endpoint where `views` is populated) |\n| `get_etsy_shop` | `GET /v1/etsy/shop` | Get one shop by `shop_id` or `shop_name` |\n| `get_etsy_shop_listings` | `GET /v1/etsy/shop/listings` | List a shop's active listings |\n\nEvery tool is annotated `{readOnlyHint:true, destructiveHint:false, idempotentHint:true, openWorldHint:true}` — read-only, non-destructive, idempotent, over an open/external data source.\n\n## Expected upstream errors — not a bug\n\n**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:\n\n- **eBay** (`search_ebay*`, `get_ebay*`) — the route **is** deployed, but app keys aren't provisioned, so you get:\n  ```\n  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.\n  ```\n  `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.\n\n- **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:\n  ```\n  not_found: No route for GET /v1/bestbuy/search\n  not_found: No route for GET /v1/etsy/shop\n  ```\n  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**.\n\nCommerceBridge 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.\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `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. |\n\nNo other configuration. No secrets belong in this repo — API keys live only on the upstream `commerce-api` deployment.\n\n## Run locally\n\n```bash\nnpm install\nnpm test              # local smoke test — initialize, tools/list, 2x tools/call (see below)\n```\n\n## Deploy\n\n```bash\nnpx vercel --yes --prod\n```\n\nThat'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:\n\n```\nhttps://<your-deployment>.vercel.app/api/mcp\n```\n\n## Local smoke test\n\n`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:\n\n1. **`initialize`** — server identifies itself as `commercebridge` v1.0.0\n2. **`tools/list`** — all 14 tools present, each with an object `inputSchema` and the expected RO annotations\n3. **`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\n4. **`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\n\n`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.\n\n## Architecture\n\n```\nlib/tools.js   — buildServer(): McpServer + all 14 tool registrations + upstream fetch relay\napi/mcp.js     — POST /api/mcp — stateless StreamableHTTPServerTransport, no auth\napi/health.js  — GET /api/health — {ok, service, upstream}\ntest/          — smoke.mjs (in-memory client/server), local-server.mjs (HTTP handler check)\n```\n",
  "bytes": 8146,
  "sha": "4ad36ff618d88bc3a8866e477d1fe008309c8127016bc44d06921032204b3c48",
  "repo_slug": "isaiahdupree/commercebridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_isaiahdupree_commercebridge_9fbb236d/readme"
}