npm package: @opencommerceprotocol/bridge-mcp
Description: Open Commerce Protocol — MCP (Model Context Protocol) server bridge
Latest version: 1.0.0

# @opencommerceprotocol/bridge-mcp

MCP (Model Context Protocol) server bridge for the [Open Commerce Protocol](https://opencommerceprotocol.org). Exposes all OCP tools as MCP tools — compatible with Claude Desktop, Cursor, and any MCP-enabled agent.

## Installation

```bash
npm install @opencommerceprotocol/bridge-mcp
```

## Quick Start

```typescript
import { createMCPServer } from '@opencommerceprotocol/bridge-mcp';

const { server, start } = await createMCPServer({
  ocpManifest: 'https://mystore.com/.well-known/ocp.json',
  transport: 'stdio',
});

await start();  // connects via stdio (for Claude Desktop / Cursor)
```

## `createMCPServer(config)`

Returns `Promise<{ server: Server; start: () => Promise<void> }>`.

### `MCPBridgeConfig`

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `ocpManifest` | `OCPManifest \| string` | Yes | Manifest object or URL |
| `handlers` | `Partial<OCPHandlers>` | No | Custom tool handler implementations |
| `transport` | `'stdio' \| 'sse'` | No | Transport type (default: `'stdio'`) |
| `name` | `string` | No | Server name (default: derived from manifest) |

## Use Cases

### Catalog-only (no handlers needed)

If your store has a product feed but no cart/checkout API, the bridge automatically searches the feed:

```typescript
const { start } = await createMCPServer({
  ocpManifest: 'https://mystore.com/.well-known/ocp.json',
  // No handlers needed — search_products reads from the feed URL in the manifest
});

await start();
```

### Full store with cart and checkout

```typescript
const { start } = await createMCPServer({
  ocpManifest: manifest,
  handlers: {
    search_products: async ({ query, category, limit }) => {
      const res = await fetch(`/api/products?q=${query}&category=${category}&limit=${limit}`);
      return res.json();
    },
    get_product: async ({ id }) => {
      const res = await fetch(`/api/products/${id}`);
      return res.json();
    },
    add_to_cart: async ({ product_id, quantity }) => {
      const res = await fetch('/api/cart', {
        method: 'POST',
        body: JSON.stringify({ product_id, quantity }),
      });
      return res.json();
    },
    begin_checkout: async ({ prefill }) => {
      const res = await fetch('/api/checkout', {
        method: 'POST',
        body: JSON.stringify(prefill),
      });
      return res.json();
    },
  },
});

await start();
```

### Load manifest from file

```typescript
import { readFileSync } from 'fs';
import type { OCPManifest } from '@opencommerceprotocol/spec';

const manifest = JSON.parse(readFileSync('.well-known/ocp.json', 'utf-8')) as OCPManifest;

const { start } = await createMCPServer({ ocpManifest: manifest });
await start();
```

## Tool Schemas

The bridge maps all 11 OCP tools to MCP tool definitions with matching input schemas:

| OCP Tool | MCP Input Parameters |
|----------|---------------------|
| `search_products` | `query`, `category`, `min_price`, `max_price`, `in_stock`, `limit` |
| `get_product` | `id` (required) |
| `get_product_qa` | `id` (required), `question` |
| `compare_products` | `ids[]` (required, min 2), `attributes[]` |
| `add_to_cart` | `product_id` (required), `quantity` (required), `variant_id`, `agent_context` |
| `get_cart` | _(no params)_ |
| `update_cart` | `items[]` with `product_id`, `quantity` |
| `begin_checkout` | `prefill`, `callback_url`, `agent_context` |
| `check_availability` | `id` (required), `location`, `quantity` |
| `check_checkout_status` | `session_id` (required) |
| `get_promotions` | `product_id`, `category` |

Only tools listed in `manifest.interact.tools` are exposed. If `interact.tools` is not set, all 11 tools are exposed.

## Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mystore": {
      "command": "node",
      "args": ["/path/to/mcp-bridge.js"]
    }
  }
}
```

`mcp-bridge.js`:
```javascript
import { createMCPServer } from '@opencommerceprotocol/bridge-mcp';
const { start } = await createMCPServer({
  ocpManifest: 'https://mystore.com/.well-known/ocp.json',
});
await start();
```

## CLI Alternative

Generate and run the bridge without writing code:

```bash
npx @opencommerceprotocol/cli bridge --protocol mcp --manifest .well-known/ocp.json
```