ZShop Agent Cart

Inspiration

Shopping agents are often forced to infer intent from pixels, scrape inconsistent product cards, and guess whether an action is safe. ZShop Agent Cart explores a better contract: the storefront exposes precise capabilities while the shopper keeps a visible, shared workspace and remains in control of consequential choices.

What it does

ZShop registers five WebMCP tools directly from the live storefront:

• set_shopping_goal makes the shopper's brief visible to both human and agent.
• search_products searches the live catalog and returns compact, comparable facts.
• inspect_product reads current price, stock, fulfilment, description, and option requirements.
• view_cart reads the authenticated shopper's selected items and total.
• add_product_to_cart adds simple products through the existing signed-in session.

The on-page companion shows the shared goal and a live activity trail, so the human can see what the agent is doing without leaving the shopping experience. Products with variants are deliberately not guessed: the tool returns a product URL and asks the shopper to select options. Checkout remains human-controlled.

Why WebMCP is the right fit

Commerce mixes fast-changing facts, authenticated state, and actions with different risk levels. WebMCP lets the site describe each capability with a narrow JSON schema and behavioral annotations instead of asking an agent to reverse-engineer the UI. The result is faster and more reliable than click automation, while preserving the storefront's own validation, authentication, and cart rules.

Before this extension, a shopper could browse ZShop and an agent could separately offer generic advice. Now they can work in the same live catalog and session: the person states intent and handles preference-heavy decisions; the agent retrieves current facts, narrows choices, and performs bounded cart work; both share visible context.

How we built it

The Nuxt 4 client plugin detects document.modelContext, then registers typed tools with registerTool. Each tool has a constrained input schema, clear descriptions, and read-only, destructive, idempotent, and open-world hints. Tool handlers call the same production catalog and cart APIs as the storefront and reuse the existing auth token. A Vue composable keeps the shared goal and recent action log reactive in the companion UI.

Focused Vitest coverage validates product normalization and rejects malformed search terms and numeric inputs. A CDP-based WebMCP host test injects the browser API, verifies all five registrations, executes the goal and live catalog search tools, and confirms that the human-visible companion updates.

Challenges

The central design challenge was choosing boundaries, not simply exposing every UI action. Product options cannot be selected safely from incomplete intent, and checkout has financial consequences, so neither is automated. Another challenge was keeping the experience useful outside a WebMCP-enabled browser; the storefront still works normally and the companion explains when agent capabilities are unavailable.

Accomplishments

• Five working WebMCP tools backed by a live multilingual catalog.
• Shared human-agent context visible in the existing storefront.
• Authenticated cart access without a second agent-specific account system.
• Explicit safety boundaries for variants and checkout.
• Reproducible tests, public source, MIT license, and dated challenge-period commits.

What we learned

Agent-native UX is strongest when structured capabilities and visible human feedback are designed together. Schemas make actions reliable; the companion makes them understandable. The most important tool behavior can also be a refusal to guess.

What's next

Next we would add preference memory approved by the shopper, side-by-side comparison cards generated from tool results, and a confirmation protocol for reversible versus consequential actions. We would also localize tool descriptions alongside ZShop's Chinese, English, Thai, and Traditional Chinese interface.

Built with

WebMCP, Nuxt 4, Vue 3, TypeScript, Vant, Vitest, Docker

Links

• Live demo: https://zshop.zwlab.app/
• Source: https://github.com/walker-shop/joyshop-web

Built With

• docker
• nuxt-4
• typescript
• vant
• vitest
• vue.js
• webmcp