Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added a plan for the shopper-facing MCP surface
Damian Legawiec5dcbd0527c1c
diff --git a/docs/plans/6.0-mcp-server.md b/docs/plans/6.0-mcp-server.mdindex 7bd075df40..59691aa9d5 100644--- a/docs/plans/6.0-mcp-server.md+++ b/docs/plans/6.0-mcp-server.md@@ -749,7 +749,8 @@ gem, so `pnpm test:changed` picks its specs up.7. **Later, outside this plan:** `spree mcp` stdio wrapper in `@spree/cli`that proxies to the mounted endpoint and prints client configs; a- shopper-facing Storefront MCP (own plan). At 7 the catalog runs under+ shopper-facing Storefront MCP (`docs/plans/6.1-store-mcp-server.md`).+ At 7 the catalog runs underTypeScript with `@spree/admin-sdk`, and the Ruby adapter is deletedrather than ported.diff --git a/docs/plans/6.1-store-mcp-server.md b/docs/plans/6.1-store-mcp-server.mdnew file mode 100644index 0000000000..fc20a53711--- /dev/null+++ b/docs/plans/6.1-store-mcp-server.md@@ -0,0 +1,159 @@+# Store MCP Server++**Status:** Draft — nothing built. The admin surface it reuses shipped in 6.0.+**Target:** Spree 6.1+**Depends on:** `6.0-mcp-server.md`, `6.0-mcp-oauth.md`+**Author:** Damian Legawiec+**Last updated:** 2026-10-16+**Tracking:** Linear — · GitHub —++## Summary++A second MCP endpoint that serves a shopper rather than a merchant: browse the+catalog, build a cart, check out, track an order — in the shopper's own words,+from an agent they already use. The admin server answers "how is my store+doing"; this answers "find me a birthday present under £50 and ship it by+Friday".++Everything that made the admin server work is surface-neutral and already+built: the tool contract, the in-process dispatcher, the record summaries, the+protocol adapter. What is genuinely new is a principal that is a customer+instead of a staff member, and a catalog of tools that reaches the Store API.++## Key Decisions (do not deviate without discussion)++- **One registry per surface, already split.** `Spree.store_agent_tools` exists+ and is empty. A tool declares its `audience`, and the registry refuses one+ filed on the wrong surface — so a storefront visitor can never be offered a+ back-office tool, even by an extension that registers carelessly.+- **A second endpoint, not a mode.** `POST /api/v3/store/mcp`, mounted by the+ same `spree_mcp` gem. One endpoint deciding at runtime whether its caller is+ a shopper or a merchant is the shape that produces a confused-deputy bug.+- **The Store API is the only data source.** Tools dispatch into it exactly as+ the admin tools dispatch into the Admin API. No tool reads a model.+- **Guest-first.** Most shoppers are not signed in. A publishable key plus a+ cart token has to be a first-class principal, not a degraded one.+- **Writes are narrow and enumerated.** The Store API is read-only by default+ and opts into writes per resource. The tool catalog is narrower still: cart,+ address, checkout. No tool writes a product, a price or another customer.++## Design Details++### What is reused unchanged++| Component | Why it carries over |+| --- | --- |+| `Spree::AgentTool` | The tool contract names no surface |+| `Spree::AgentTools::Registry` | Already audience-aware |+| `Spree::AgentTools::ApiDispatch` | Dispatches to any Rails path; nothing admin-specific |+| `Spree::AgentTools::RecordSummary` | Shapes a record for a model, surface-neutral |+| `Spree::Mcp::ToolAdapter`, `Server` | Speak MCP, not Spree |+| The OAuth authorization server | `use_polymorphic_resource_owner` is already on |++The admin build is about 4,600 lines of tool layer under 590 of MCP adapter.+The adapter is the part that does not need rewriting.++### What is new++**A store resource map.** `AgentResourceMap` walks+`Spree::Api::V3::Admin::ResourceController.descendants` and reads each+controller's `scoped_resource` declaration. Store controllers declare no+scope — they are gated by the publishable key and by `scope`, not by a+permission catalog. So the store map cannot be derived the same way and needs+its own basis: most likely an explicit registration per controller, since the+store surface is small enough to enumerate and too security-sensitive to infer.++**A customer principal.** `Context` already carries `store`, `user`,+`api_key`, `ability` and `request_headers`. It needs the cart token the+Store API already reads from `x-spree-token`+(`base_controller.rb:71`), and `user` has to accept the customer class. Both `admin_authentication.rb:79` and+`mcp_controller.rb:156` currently refuse a grant whose owner is not an admin;+the store endpoint needs the mirror of that check, not a relaxation of it.++**A tool catalog.** The Store API's own nested controllers decide the shape —+a cart already has `items`, `discount_codes`, `gift_cards`, `fulfillments`,+`payments` and `tax_identifiers`, so the tools follow those rather than+inventing a vocabulary:++- the catalog — products and categories, read only+- the cart and its items+- discount codes and gift cards applied to a cart+- fulfillments, which is where delivery options are chosen+- a shopper's own order, found by its token or by being signed in++Named precisely once the store resource map exists, since the map is what+says which operations are reachable.++**Authentication.** Three principals, in the order a shopper meets them:++1. **Publishable key alone** — browse the catalog. No consent screen; the key+ is public and identifies the store, not a person.+2. **Publishable key plus cart token** — a guest's own cart. The token already+ authorizes exactly one cart, which is the right granularity.+3. **OAuth, owner is a customer** — a signed-in shopper's order history and+ saved addresses. This is where a consent screen appears, and the scopes are+ the customer's own data, not the permission catalog.++### What must never be reachable++The admin surface withholds API keys, integrations, webhook endpoints and gift+card codes. The store surface starts from a smaller catalog, but the same+discipline applies and two cases are specific to it:++- **Another shopper's anything.** Every lookup scopes through the cart token or+ the signed-in customer, never through the store alone.+- **Prices a customer should not see.** Cost price, margin, supplier. The Store+ serializers already exclude these; a tool must not reach past them.++## Migration Path++1. **A store resource map**, registered explicitly rather than derived, with a+ contract spec that fails when a Store controller gains an action the map+ does not describe.+2. **The customer principal** in `Context`, plus the cart token in+ `FORWARDED_HEADERS`.+3. **Read tools** — catalog and cart, publishable key only. Testable end to+ end before any write exists.+4. **The endpoint** — `POST /api/v3/store/mcp` in `spree_mcp`, with its own+ discovery document.+5. **Cart writes**, gated on the cart token.+6. **OAuth for customers** — consent screen, customer-owned grants, order+ history.++Steps 1 to 3 are worth shipping alone: a catalog-browsing agent with no write+path and no login is useful, and it exercises the whole pipeline.++## Constraints on Current Work++- **Do not widen `Spree.admin_agent_tools`** to cover storefront cases. The+ split exists so the two catalogs cannot leak into each other.+- **A new agent tool declares its `audience`.** The registry refuses a+ mismatch, so an undeclared tool silently defaults to admin.+- **Keep `ApiDispatch` surface-neutral.** It forwards headers and calls a+ path; anything admin-specific added to it has to be unpicked here.+- **A Store API controller that gains a write** should expect to be reachable+ by an agent eventually. Scope every lookup through the cart or the customer.++## Open Questions++- **How is the store map built?** Derivation fails because Store controllers+ declare no scope. Explicit registration is safer and the surface is small,+ but it drifts unless a contract spec holds it honest.+- **Does a guest need consent at all?** A cart token authorizes one cart, which+ is arguably consent already. A consent screen for a guest may be ceremony+ without protection — but without one, an agent holding a leaked token acts+ with no record of having been granted anything.+- **What does a customer-owned grant scope look like?** The admin catalog is+ permission keys. A customer has no role. Likely a short fixed list+ (`read_orders`, `write_cart`), which is a new vocabulary rather than a reuse.+- **Checkout completion and payment.** Almost certainly out of scope for the+ first release: an agent completing a payment is a different consent question,+ and the gateway flows are browser-bound.+- **Rate limiting.** The admin endpoint is reached by a merchant's own agent.+ This one is reachable by anyone holding a publishable key, which is public.++## References++- `docs/plans/6.0-mcp-server.md` — the admin server and the tool registry+- `docs/plans/6.0-mcp-oauth.md` — the authorization server+- `docs/developer/mcp/` — the shipped admin documentationdiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex e0c1b27d00..3c20b8f21c 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -6384,3 +6384,23 @@ the path a token names was buying nothing.The specs that missed this minted tokens in Ruby and dispatched with an adminJWT, so neither consent nor the OAuth dispatch path was ever exercised. TheMCP suite now walks consent, token exchange and a tool call as a client does.++## 2026-10-16 — The store MCP surface reuses everything but the catalog++A second MCP endpoint for shoppers is planned for 6.1+(`docs/plans/6.1-store-mcp-server.md`). The tool contract, the registry, the+in-process dispatcher, the record summaries and the protocol adapter are all+surface-neutral and carry over unchanged — about 4,600 lines of tool layer+under 590 of adapter, and the adapter is the part that would otherwise need+rewriting.++Two things do not carry over. The resource map is derived by walking+`Admin::ResourceController.descendants` and reading each controller's+`scoped_resource`; Store controllers declare no scope, so the store map needs+its own basis. And a grant's owner is refused unless it is an admin user, in+two places, so a customer principal is a deliberate addition rather than a+relaxation.++The registry was split by surface during the 6.0 build for exactly this —+`Spree.store_agent_tools` exists and is empty, and a tool filed on the wrong+surface is refused at registration.