commercebridge

# CommerceBridge

A 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.

**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

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

## Deploy

```bash
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)
```