@opencommerceprotocol/bridge-mcp

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

Installation

npm install @opencommerceprotocol/bridge-mcp

Quick Start

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:

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

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

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:

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

mcp-bridge.js:

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:

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