Ce AI

LLM Docs Header: All requests to https://llm-docs.commercengine.io must include the Accept: text/markdown header (or append .md to the URL path). Without it, responses return HTML instead of parseable markdown.

Commerce Engine Agent Tools (WebMCP)

@commercengine/ai publishes your storefront's capabilities to a browser AI agent through WebMCP. The agent searches the catalog, resolves variants, edits the shopper's real cart, and navigates the site — through the SDK, not by clicking DOM elements.

npm install @commercengine/ai

Peer: @commercengine/storefront. Optional: @commercengine/checkout (>= 0.3.0) for cart-drawer and checkout tools.

Impact Levels

• CRITICAL — tools that never register, unbounded mutations, cross-origin navigation
• HIGH — capability gating, retry semantics, session ownership
• MEDIUM — diagnostics, timing, agent ergonomics

Where the Boundary Sits

The package deliberately stops short of completing a purchase.

Agent CAN:  search · inspect products and variants · read the cart
            add / update / remove cart lines · navigate · open cart
            open checkout · open the login screen
Agent CANNOT: enter addresses · apply payment · place an order
            sign anyone in · read or supply a password or OTP

open_checkout hands control back to the shopper. There are no payment tools and no credential tools, and the login tool only opens the screen — its description tells the agent explicitly never to ask for a password or one-time code. This matches where every serious headless-commerce agent integration draws the line: an agent may assemble an order, a human completes it.

Quick Start

import { registerCommerceWebMcp } from "@commercengine/ai/webmcp";
import { createHostedCheckoutBridge } from "@commercengine/ai/checkout";
import { getCheckout } from "@commercengine/checkout";
import { routes, site } from "./commerce-seo.config";  // shared with @commercengine/seo
import { storefront } from "./storefront";

const registration = await registerCommerceWebMcp({
  storefront,
  siteUrl: site.url,
  routes,
  checkout: createHostedCheckoutBridge({ getState: () => getCheckout() }),
  navigation: { navigate: (url) => router.push(url) },
  diagnostics: import.meta.env.DEV
    ? (event) => console.info("[commerce-ai]", event.code, event.message ?? "")
    : undefined,
});

// Keep the controller for teardown. Calling it unregisters every tool this call installed —
// so call it from a cleanup function, not here:
// registration?.abort();

Returns null — never throws — when the browser has no model context. Framework-specific mount points are in references/registration.md.

routes and site come from defineCommerceSeoConfig. Sharing one declaration with @commercengine/seo means a crawler and an agent can never be told different URLs for the same product.

siteUrl is validated where it is configured, not carried into an agent's results: an ftp:// scheme, embedded credentials, or a sub-path throws a RangeError at construction. An agent is the surface where a bad origin does the most damage, because every URL a tool returns is built from it and handed straight to a model.

References

Capability Gating

Tools register only when you supply the capability behind them. A storefront with no checkout bridge simply has no cart-drawer tools; nothing errors.

Counted against the published package, so you can predict the number before you look:

The session tools come from the storefront's own browser session, found via clientStorefront() or session(). A storefront exposing neither registers the four catalog tools and nothing else — which looks identical to a bug, so check the accessor name first when cart tools are missing.

This is why an agent reporting "login isn't available on this site" is usually correct and intentional — the checkout build exposed no openLogin.

Cart Semantics

Get these wrong and an agent will corrupt a real shopper's cart.

Three behaviours the package handles for you:

• Promotional free items. Lines auto-added by an active promotion are reported removable: false and cannot be removed. set_cart_item_quantity operates on the paid quantity, leaving the free allocation alone.
• Ordering rules. min_order_quantity, max_order_quantity, and increment steps are validated before the call, and the constraints are stated in the tool description so the agent can get it right first time rather than by trial and error.
• Stale checkout. The next add or create automatically resets a stale checkout session.

Two Signals, Doing Different Jobs

Claiming a tool set is not atomic — it is a sequence of awaited registerTool calls. Two overlapping registrations against one model context would race for the same names and one would throw InvalidStateError: Duplicate tool name. React Strict Mode makes this the ordinary case, not an edge one: it mounts, cleans up and mounts again back-to-back on every dev mount, and both passes dispatch their first tool before either resumes, so cleanup alone cannot break the tie.

Registrations against one context are therefore serialized — a second call waits for the first to settle, including any rollback.

import { CommerceWebMcpAbortError, registerCommerceWebMcp } from "@commercengine/ai/webmcp";

useEffect(() => {
  const controller = new AbortController();
  let registration: { abort: () => void } | null = null;
  void registerCommerceWebMcp({ ...config, signal: controller.signal })
    .then((result) => { registration = result; })
    .catch((error) => { if (!(error instanceof CommerceWebMcpAbortError)) throw error; });
  return () => { controller.abort(); registration?.abort(); };
}, []);

Cancellation rejects with CommerceWebMcpAbortError, which callers are expected to swallow — it means "you asked for this". Without config.signal, cleanup can run before the controller exists and the stale pass stays live after its component has gone away.

Routes: The Agent Resolves Both Directions

routes.product runs in the browser, during tool execution. A resolver that performs a CMS lookup would need that credential on the client, so the portable shape is a pure function over route data the browser already has.

import { createCommerceRouteManifest } from "@commercengine/seo/routes";
const manifest = createCommerceRouteManifest(await loadRouteRecords());

export const routes = {
  // OUTBOUND: entity → URL. Never guess. `null` means "no public page".
  product: (input) => manifest.productPath(input),

  // INBOUND: public slug → CE identifier. The `?? publicSlug` tail is a deliberate
  // choice, valid ONLY because this storefront also answers to catalog slugs — it
  // keeps a page published since the last refresh working when the two agree.
  // Return null instead where CMS slugs are the only accepted form.
  resolveProductRoute: (publicSlug) => manifest.resolveProduct(publicSlug)?.productId ?? publicSlug,
};

resolveProductRoute matters as much as product. An agent reads a CMS page slug off the page and calls get_product("knee-pain-relief-oil") — without the inbound mapping that goes straight to a catalog which has never heard of it.

The two directions have opposite fallback rules, and the distinction is easy to lose:

Returning null from an inbound resolver fails the tool with route_not_found before any catalog request, rather than passing an unmapped slug to a catalog that has never heard of it.

Separately: do not ship a 100,000-product manifest to the browser merely to resolve a search page. This package performs no route-data transport and imposes no API, batching or cache policy — at that size, back the same hooks with a storefront-owned point cache that loads only the result set.

Diagnostics

Registration reports what happened, always. Silence is the one thing it will not do:

diagnostics: (event) => console.info("[commerce-ai]", event.code, event.message ?? "")

message is always a printable string, so a single console line never requires narrowing error first.

Wire diagnostics in development on every app. Without them, "did registration happen?" is unanswerable without probing globals — and that silence is exactly what lets a registration bug survive typecheck, build, lint, and a Lighthouse audit.

WebMCP Availability

WebMCP is a Community Group draft, not a standard. It is available in Chromium 149+ behind chrome://flags/#enable-webmcp-testing, or under an origin trial token.

The draft moved modelContext from navigator to document. The package prefers document.modelContext and falls back to navigator.modelContext, so both work. When an agent reports "this page doesn't expose WebMCP", the overwhelmingly likely cause is that the flag is off — nothing the page does can change that.

Everything draft-specific is confined to one module, so churn is a change to one file rather than to every tool.

Common Pitfalls

See Also

• ce-seo — shares defineCommerceSeoConfig; the .md mirrors and llms.txt serve crawlers the same content
• ce-cart-checkout — hosted checkout, cart rules, promotions
• ce-catalog — Product vs Item, variants, has_variant