@opencommerceprotocol/bridge-mcp

MCP Bridge

Convert an OCP manifest into a fully functional MCP (Model Context Protocol) server. Makes any OCP store instantly usable from Claude Desktop, Cursor, and other MCP-compatible agents.

Installation

npm install @opencommerceprotocol/bridge-mcp

Quick Start

server.ts

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)

Configuration

createMCPServer(config) returns Promise<{ server: Server; start: () => Promise<void> }>.

ocpManifestOCPManifest | stringrequiredManifest object or URL to fetch it from.

handlersPartial<OCPHandlers>Custom tool handler implementations. If omitted, the bridge searches the product feed.

transport"stdio" | "sse"MCP transport type. Default: "stdio".

namestringServer name shown to clients. Default: derived from manifest merchant name.

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:

catalog-only.ts

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

full-store.ts

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

from-file.ts

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 Schema Mapping

All 11 OCP tools are mapped to MCP tool definitions with matching input schemas. Only tools listed in manifest.interact.tools are exposed. If interact.tools is not set, all 11 tools are available.

search_productsquery, category, min_price, max_price, in_stock, limit

get_productid (required)

get_product_qaid (required), question

compare_productsids[] (required, min 2), attributes[]

add_to_cartproduct_id (required), quantity (required), variant_id, agent_context

get_cart(no params)

update_cartitems[] with product_id, quantity

begin_checkoutprefill, callback_url, agent_context

check_availabilityid (required), location, quantity

check_checkout_statussession_id (required)

get_promotionsproduct_id, category

Claude Desktop Configuration

Add the MCP server to your Claude Desktop config to start using OCP tools in conversations.

~/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

Next Steps

Protocol Specification

Full reference for manifests, products, tools, and types.

UCP Bridge

Convert OCP manifests for Google UCP checkout agents.

A2A Bridge

Generate Google A2A agent cards from OCP manifests.

Playground

Validate your OCP implementation and see your score.