Shopify Catalog Health Copilot

A WebMCP copilot that helps Shopify merchants and AI agents find, fix, and verify catalog issues together, turning product data into search - and agent-ready storefronts.

Comment

Inspiration

WebMCP already lets shopping agents interact with storefronts (I noticed Shopify-powered stores have this). I wanted to explore the merchant side of that future: who makes sure the underlying product catalog is understandable enough for those agents to use? Based on my research, catalog hygiene was the first pain point in the Shopify Reddit Community's "most annoying manual task" thread.

Product catalogs often contain missing identifiers, vague descriptions, incomplete image alt text, inconsistent variants, and weak taxonomy. These issues affect traditional search today and can make products harder for AI shopping agents to understand and recommend.

Catalog Health Copilot turns catalog maintenance into a collaborative workflow between a Shopify merchant (human) and an AI agent via webMCP.

What it does

Catalog Health Copilot connects to a Shopify development store and audits its products across six areas:

  • Identifiers
  • Product content
  • Media
  • SEO
  • Commercial data
  • Agent readiness

It converts those findings into a prioritized issue queue and health score. From the same live page or dashboard, a merchant and their agent can:

  1. Scan the catalog.
  2. Find the highest-impact issues.
  3. Open a specific issue and inspect its context.
  4. Generate an OpenAI-assisted fix for text.
  5. Review or edit the proposed field-level change.
  6. Apply approved changes to Shopify.
  7. Re-fetch the product and verify the live result.
  8. Preview how a shopping agent interprets the product before and after the fix.

The web app remains usable as an ordinary web application when WebMCP is unavailable or when humans are using it. WebMCP adds a structured collaboration layer rather than replacing the interface.

Catalog auditing involves large amounts of repetitive inspection, prioritization, drafting, and verification. An agent is well suited to that labor, while the merchant should retain judgment over brand voice and product accuracy.

Instead of asking an agent to guess its way through buttons and page layouts, the application exposes ten WebMCP tools:

scan_catalog, get_health_score, list_issues, show_issue, generate_fix, apply_fix, apply_approved, dismiss_issue, verify_fix, and preview_agent_view.

This lets the agent work with structured product data while keeping its actions visible in the same interface the merchant is viewing. When the agent selects an issue, creates a draft, or applies a fix, the page updates too.

The result is a governed scan → explain → draft → review → apply → verify workflow that would be fragile and difficult to coordinate through visual browser automation alone.

How I built it

The frontend is built with React, TypeScript, and Vite. All WebMCP tools are registered in the top-level document using:

document.modelContext.registerTool(...)

The tools call the same catalog-controller functions used by the visible interface. This gives the human and the agent shared state, permissions, progress, and verification results.

A Cloudflare Worker serves the application and its API routes. It connects server-side to:

  • Shopify Admin GraphQL API for catalog reads and controlled product updates
  • OpenAI API for context-aware fix drafts, with deterministic templates as a fallback
  • Cloudflare rate limiting and observability for protecting sensitive endpoints and recording mutation outcomes

Shopify and OpenAI credentials never reach the browser.

Safe demo-store writes

The public demo intentionally allows controlled writes so judges can experience the complete WebMCP workflow. I added several server-enforced safeguards:

  • Only products carrying the catalog-health-seed tag can be modified.
  • Variant and image IDs must belong to the selected seeded product.
  • Only an explicit allowlist of product fields is writable.
  • A request can contain no more than ten changes.
  • Write and OpenAI endpoints have independent rate limits.
  • ALLOW_LIVE_WRITES provides an emergency kill switch.
  • Every attempted mutation is logged with its outcome.
  • A guarded reset command restores the deterministic 30-product demo catalog.

These restrictions let the demonstration remain interactive without exposing a production storefront.

Challenges I faced

One major challenge was designing for WebMCP as a genuine product capability rather than attaching tools to an existing interface. ChatGPT’s in-app browser requires tools to be registered imperatively in the top-level document, so the application could not be an iframe or embedded Shopify Admin app.

Another challenge was keeping the visible interface synchronized with agent activity. I solved this by routing both UI controls and WebMCP tools through the same controller instead of creating separate automation logic.

The most important challenge was safe write access. A public demonstration needs to be easy for you, the judges, to use, but unrestricted Shopify mutations would be inappropriate. The seed-tag policy, ownership validation, allowlist, limits, logging, kill switch, and reset workflow let me keep the full experience available.

What I learned

I learned that agent-native UX is not simply about giving an agent more autonomy. The best experience makes actions structured, visible, interruptible, editable, and verifiable.

I also learned that verification deserves to be a first-class tool. A successful API response is not enoughthe application re-fetches Shopify data and returns evidence that the intended field actually changed.

Most importantly, WebMCP makes it possible for a human and an agent to operate inside one coherent product experience: the agent handles scale and repetition, while the human keeps context and judgment.

What’s next

For a production store, I would add merchant authentication, Shopify OAuth, role-based approvals, persistent audit history, configurable catalog policies, and scheduled monitoring. I would also expand the checks using storefront analytics and order history to identify products that are technically available but consistently undiscoverable.

Built With

Share this project:

Updates

Submission history