Install shopping-mcp

shopping-mcp is a small WebMCP tool profile for retail. Every store exposes the same shopping tools so agents know how to browse, choose, and check out without scraping the DOM.

This site is the landing and the live demo. The installable library lives in the same repo at packages/shopping-mcp.

Install

In your storefront app:

npm install shopping-mcp

The package is not on the public npm registry yet. Until it is, point at this repo:

{
  "dependencies": {
    "shopping-mcp": "file:./packages/shopping-mcp"
  }
}

Clone retailab-shopping-mcpor copy packages/shopping-mcp into your project.

Register

Call once in the browser on the storefront page — not on your Node server. Map each handler to your own catalog and cart.

import { registerShoppingMcp } from "shopping-mcp";

registerShoppingMcp({
  handlers: {
    listProducts: () => myApi.list(),
    searchProducts: (query) => myApi.search(query),
    addToCart: (skuId, quantity) => myApi.add(skuId, quantity),
    getCart: () => myApi.cart(),
    removeFromCart: (skuId) => myApi.remove(skuId),
    checkout: () => myApi.checkout(),
  },
});

Each handler returns { ok, message, data? }. The library registers names, JSON schemas, and argument checks. It does not scrape your page and it does not own the cart.

checkout is optional. If you omit that handler, the tool is not registered. When you do implement it, require a shopper confirmation — never pay silently.

The library also mounts a floating shared cart island and registersopen_ui so an agent can show it. Pass ui: false if you do not want that widget. You can call openCartUi() from your own Cart button.

Required tools

Agents look for these names on every participating store viadocument.modelContext.

• list_productsList what this store is selling on the current page.
• search_productsSearch this page’s catalog by keyword. Does not search other stores.
• add_to_cartAdd a SKU from this page to this store’s cart. Fails if the SKU is not on this page.
• get_cartRead this store’s cart.
• remove_from_cartRemove one line from this store’s cart.
• checkoutStart checkout on this origin only, after the shopper confirms. Optional — omit the handler if you are not ready.
• open_uiShow the shared shopping cart island on the page (items and current total). Skip with ui: false.

Cart vs trip

Each store keeps its own cart and checkout. The agent (or a browser client) keeps a shared trip — needs, picks, and store URLs — by calling get_cart on each origin. That respects origin isolation and keeps purchases visible to the shopper.

• Visit store A → call its tools → snapshot lines into the trip.
• Visit store B → same tool names, that store’s cart.
• Confirm checkout per merchant. Never pay across origins in one silent step.

This demo

The homepage has a compact teaser. The /demo page is the full showcase and the URL agents should open. Both consume the same package. The cart island floats on the fake storefront. The demo also registers two extras that a real store should not ship: list_stores andswitch_store. Those only exist because NileMart, WideMart, and DartHouse share one page.

Try it

Open the live demo, or load your store in ChatGPT’s in-app browser (WebMCP on by default) or Chrome withchrome://flags/#enable-webmcp-testing.

Package source: packages/shopping-mcp. The landing demo wires it insrc/lib/demo/webmcp.ts.