bhs-mcp

MCP server for Blackhearts & Sparrows product data, deployed as a Cloudflare Worker.

Uses the Code Mode pattern — the LLM writes TypeScript that executes against a typed BHS API in a sandboxed Dynamic Worker, rather than calling fixed tools directly.

Architecture

LLM -> code tool -> Dynamic Worker (sandbox)
                        | bhs.search(...)
                     BhsProxy (RPC bridge)
                        |
                     Host Worker
                        |
                     Meilisearch / GraphQL APIs

The sandbox has no network access. All external calls go through the BhsProxy RPC bridge to the host worker.

MCP Tools

Tool	Description
`schema`	TypeScript type definitions, method signatures, and example queries
`tools`	Sandbox capabilities, constraints, and guidance
`code`	Execute TypeScript with access to the `bhs` API object

Sandbox API

// Search products
const wines = await bhs.search({ type: "Wine", country: "France", priceMax: 30 });

// Get product details
const product = await bhs.product("44253");

// List stores
const stores = await bhs.stores();

// Manage cart
const cart = await bhs.cart.create();
await bhs.cart.addItems(cart.uid, [{ sku: "44253", masterSku: "44253", quantity: 6 }]);
const url = bhs.cart.checkoutUrl(cart.uid);

Development

npm install
npm run dev        # wrangler dev
npm run typecheck  # tsc --noEmit
npm run deploy     # wrangler deploy

Deployment

Route: bhs.jackemcpherson.com/mcp*

Depends on @jackemcpherson/bhs-cli for API functions and types.

bhs-mcp

bhs-mcp

Architecture

MCP Tools

Sandbox API

Development

Deployment

Latest Blog Posts

MCP directory API