CommerceOps Bridge

CommerceOps Bridge is an agent-native workspace helping merchants resolve duplicate payments, draft customer responses via WebMCP tools, and automate exception auditing while keeping total control.

Comment

CommerceOps Bridge — Project Story

What inspired me

Commerce work often looks simple from the outside: investigate an exception, understand what happened, contact the customer, and decide what to do next.

In practice, that work is fragmented across order systems, payment records, shipping updates, support tools, subscription bills, and internal policies. A merchant or operations specialist has to reconstruct the situation manually before they can make a safe decision. The cost is not only time. Fragmented context also creates uncertainty, duplicated work, and the risk of taking an action without enough evidence.

The WebMCP Challenge made me think about a different model: what if a web application did not only present information to people, but also exposed its useful operations directly to an AI agent?

That led to CommerceOps Bridge — an agent-native operations workspace where a person and an agent can investigate an issue together. The agent gathers structured context and prepares recommendations. The merchant reviews the evidence, edits communication, and remains responsible for approval.

The central idea is simple:

Agents should reduce the work of finding and organizing context, while people should retain control over consequential decisions.

What problem we are solving

CommerceOps Bridge focuses on the gap between agent assistance and human accountability.

The project demonstrates how a merchant can:

  • Find an open commerce exception.
  • Retrieve order and payment context through structured tools.
  • Detect a duplicate payment pattern.
  • Compare a proposed resolution with an alternative.
  • Review evidence and policy references.
  • Edit an unsent customer message.
  • Approve preparation without triggering an external refund.
  • Review a decision audit trail.
  • Run an operating-cost audit.
  • Prepare an editable support escalation packet.

Before this approach, an agent would have to infer application behavior from visible page elements or rely on loosely connected integrations. With WebMCP, the application can explicitly describe the operations an agent is allowed to discover and request.

What we learned

1. WebMCP is most valuable when the tools represent real user intent

It is easy to expose a tool that demonstrates a technical API call. It is more useful to expose operations that map to actual work, such as get_order_context, check_refund_policy, propose_resolution, and prepare_escalation_packet.

The tool names, descriptions, input schemas, and returned data should help an agent understand the application without guessing from the layout.

2. Structured context is more useful than a collection of page fragments

The order context tool returns an order, payments, shipment information, and evidence references together. This gives the agent a coherent record that can be interpreted and traced.

The result also taught us an important implementation detail: a browser may return the tool result as a serialized JSON string. The consumer must parse it once before displaying tables or using nested fields. Double-stringifying the result produces the escaped output that is difficult for people to read.

3. Human control needs to be visible in the product

A safety statement hidden in documentation is not enough. The interface therefore makes the boundary visible:

  • Customer messages are labeled UNSENT and remain editable.
  • The workflow says Approve preparation, rather than claiming that a refund was completed.
  • The audit trail records the merchant action.
  • The external-action status explicitly shows no.
  • The demo does not call a live refund, message, Shopify, or payment-provider API.

This makes the distinction between assistance, preparation, approval, and execution clear to both the user and the judge.

4. A good agent-native experience still needs to work for people

WebMCP is not a replacement for a coherent user interface. The dashboard, queue, evidence panels, recommendation cards, and audit trail give a person a clear way to understand and verify what the agent did.

The strongest experience is shared: structured tools for agents and readable explanations for people.

How we built the project

We followed a lightweight spec-driven development process. Each feature moved through a short cycle:

  1. Define the user outcome and acceptance criteria.
  2. Describe the interaction and safety boundaries.
  3. Implement the domain logic and UI.
  4. Expose the relevant operation as a WebMCP tool where appropriate.
  5. Test the deterministic behavior.
  6. Verify the result in the deployed application.

Product structure

CommerceOps Bridge is a Vite-powered front-end application. It uses deterministic seeded commerce data so the public demo is repeatable and does not depend on paid accounts or live merchant systems.

The application is organized around three layers:

  • Seeded data: orders, payments, shipments, support cases, evidence, applications, and fees.
  • Domain functions: investigation, payment timeline, policy checks, recommendations, message drafting, cost audit, and escalation preparation.
  • Presentation and tools: the dashboard UI plus WebMCP registrations that expose selected domain operations to agents.

WebMCP implementation

The application registers tools through document.modelContext.registerTool().

The current tool set includes:

  • list_open_exceptions
  • get_order_context
  • get_payment_timeline
  • check_refund_policy
  • propose_resolution
  • draft_customer_message
  • get_cost_audit
  • prepare_escalation_packet

Each tool has a name, description, input schema, and execution function. The execution functions call deterministic domain logic and return structured results.

The most important demo path is:

  1. Discover tools with document.modelContext.getTools().
  2. Select get_order_context.
  3. Execute it for ORD-1042.
  4. Review the returned customer, order, payment, and evidence data.
  5. Continue the same investigation through the application interface.

This demonstrates that WebMCP is not only mentioned in the project; it is used to discover and execute an operation exposed by the live page.

Challenges we faced

WebMCP availability differs by browser

WebMCP support is still emerging. Chrome requires the WebMCP testing flag, while other browser environments may expose different support levels. We handled this by keeping the application useful in preview mode while making the tool definitions and traces visible in the product.

For the final demo, we use a WebMCP-enabled Chrome session and show both discovery and direct execution in DevTools.

Tool results may arrive as escaped JSON

The direct Console result appeared as one escaped string rather than a readable object. The fix was to detect whether the returned value is a string and call JSON.parse() exactly once. We then use console.table() for the order and payment records so the result is easy to understand during the recording.

Deployment initially published the wrong asset state

The first Cloudflare Pages deployment skipped the build step because no build command was configured. The deployment technically succeeded, but the page did not load the application correctly.

We corrected the Cloudflare configuration to use:

  • Build command: npm run build
  • Build output directory: dist
  • Root directory: blank, because the Vite project is at the repository root

After that change, the live application deployed successfully at:

https://commerceops-bridge.pages.dev/

We did not have a Shopify store or live commerce credentials

Rather than make unsupported claims or require paid setup, we deliberately used deterministic seeded data. This keeps the demo reproducible and lets us focus on the WebMCP interaction model.

The application clearly states that it does not connect to Shopify, live payment providers, or external refund APIs. This is a limitation of the prototype, but it is also an intentional safety boundary for the hackathon demonstration.

Demonstrating the technology without overwhelming the story

DevTools is useful evidence of WebMCP, but a long Console session can distract from the product. We therefore show DevTools only for tool discovery and direct execution, then close it before demonstrating the main merchant workflow.

The rest of the demo uses the application’s own structured tool trace, recommendation panels, unsent communication state, and audit trail.

Why this approach matters

CommerceOps Bridge is not trying to automate every merchant action. It explores a more practical division of responsibility:

  • The agent handles retrieval, organization, comparison, and preparation.
  • The application exposes those operations explicitly through WebMCP.
  • The person reviews evidence, edits the outcome, and approves the next step.
  • The system records what happened and whether an external action occurred.

That model can extend beyond duplicate payments to delivery exceptions, returns, refund reviews, inventory mismatches, support escalations, and other operational workflows.

Current scope and next steps

The current project is a polished prototype using deterministic demo data. The next production steps would be:

  • Add authenticated connectors for Shopify, payment providers, shipping systems, and support platforms.
  • Add server-side authorization for tools and merchant roles.
  • Add real persistence for audit events.
  • Add provider-specific idempotency and refund safeguards.
  • Add automated tests for tool contracts and permission boundaries.
  • Measure investigation time, resolution accuracy, and escalation quality with real merchant data.

The prototype intentionally stops before those external side effects. It demonstrates the core interaction pattern first: a web application that is understandable to people, directly usable by agents, and careful about human approval.

Closing reflection

The most important lesson from building CommerceOps Bridge is that WebMCP is not merely another integration surface. It changes how we can design web applications.

Instead of asking agents to imitate a person clicking through a page, the application can expose meaningful capabilities directly. Instead of asking people to trust an opaque automation, the interface can show the evidence, recommendation, safety boundary, and audit record.

That is the future we wanted to explore with CommerceOps Bridge: a web where agents make complex work easier, while people remain informed and in control.

Built With

Share this project:

Updates

Submission history