Commerce Operations Recovery MCP

A remotely hosted TypeScript MCP server for safely recovering a specific commerce failure where a processor payment was captured, but the local order remained blocked because its webhook failed.

The server investigates the current state, prepares an exact recovery plan, waits for approval, and applies the approved changes in one PostgreSQL transaction.

Live MCP demo

Base URL: https://commerce-ops-recovery-mcp.demostore.workers.dev

The /mcp route is a protocol endpoint, so opening it directly in a browser may return Method Not Allowed. Connect through Claude, MCP Inspector, or another compatible remote MCP client.

Claude custom connector

In Claude, open Customize → Connectors, add a custom connector, and use:

Name: Commerce Operations Recovery
URL: https://commerce-ops-recovery-mcp.demostore.workers.dev/mcp

Enable the connector in a new conversation, then try:

Use the Commerce Operations Recovery connector.

First call get_demo_guide. Then investigate ORD-DEMO-1043 and explain whether
it is eligible for recovery.

Do not apply any recovery until I explicitly approve it.

MCP Inspector

Launch MCP Inspector:

npx @modelcontextprotocol/inspector

Select Streamable HTTP, enter the deployed /mcp URL above, connect, and select List Tools. Start with get_demo_guide, especially if another reviewer may already have changed the public demo state.

The service uses synthetic commerce data and does not contact real payment or fulfillment providers. Public demo state is mutable, so a successfully recovered order may later appear as already recovered.

Related MCP server: CommerceOps MCP Server

Tech stack

• TypeScript

• Cloudflare Workers

• Hono

• Cloudflare Agents SDK for MCP

• Model Context Protocol

• PostgreSQL

• Drizzle ORM

• Cloudflare Hyperdrive

• Zod

• Vitest

The application runs on Cloudflare Workers. Hono handles /health, /health/database, and /mcp, while Cloudflare's createMcpHandler exposes the MCP server through Streamable HTTP.

Node.js and pnpm are used for local scripts, tests, database migrations, and development tooling. The application itself is not hosted as a traditional Node.js server.

MCP tools

• get_demo_guide — shows the workflow, database availability, repository link, and mutable demo orders.

• investigate_order — checks current order, payment, webhook, inventory, reservation, and fulfillment state without making changes.

• prepare_recovery_plan — creates or reuses an expiring record containing the exact proposed changes.

• apply_recovery — applies an explicitly approved plan atomically and idempotently.

Setup

Install dependencies:

pnpm install

Copy the local environment template:

cp .env.example .env

Set a direct PostgreSQL connection string in CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE. The example uses sslmode=verify-full so TLS certificate and hostname verification remain explicit across upcoming pg releases.

PROJECT_REPOSITORY_URL is optional. Configure it as a normal public Worker variable to expose the repository link through get_demo_guide; the guide returns null when it is absent.

Run database migrations and verify the schema:

pnpm db:migrate
pnpm db:verify

Seed the scenarios on a database where they do not already exist:

pnpm db:seed

db:seed is intentionally non-destructive. It creates the complete scenario set, makes no change when all four orders already exist, and reports a clear conflict when only part of the set exists.

If the scenarios were changed during testing, deliberately restore them with:

pnpm db:reset-demo

The reset runs in one transaction and removes only the known synthetic demo orders and their related plans, idempotency records, audit events, reservations, webhook evidence, payments, fulfillment rows, items, and dedicated inventory. It does not reset unrelated data.

Start the Worker locally:

pnpm dev

The local MCP endpoint is normally:

http://localhost:8787/mcp

Use the URL printed by Wrangler if it is different.

Demo orders

Demo orders are mutable. Start with get_demo_guide or call investigate_order before preparing a plan because a successful application changes an eligible order's state.

Recovery flow

investigate_order
→ prepare_recovery_plan
→ explicit approval
→ apply_recovery

The read-only guide is optional and helps reviewers discover the workflow:

get_demo_guide
→ investigate_order
→ prepare_recovery_plan
→ apply_recovery

Safety

The complete allowed/forbidden mutation contract is documented in Order Recovery Boundary.

Before making changes, the server:

1. Validates approval and the idempotency request.

2. Checks for a completed idempotent request.

3. Locks the recovery plan.

4. Locks and reloads the latest commerce state.

5. Checks plan status, expiry, and order version.

6. Re-runs recovery eligibility.

7. Confirms that current changes exactly match the approved plan.

8. Applies every permitted change in one PostgreSQL transaction.

A successful recovery may:

• Mark the local payment as paid.

• Create the exact approved inventory reservations.

• Increase reserved inventory.

• Move the order and fulfillment forward.

• Increment the order version.

• Mark the plan as applied.

• Record audit and idempotency evidence.

It does not:

• Retry, capture, refund, or void the processor payment.

• Change physical on-hand inventory.

• Change order-item quantities.

• Modify packed or dispatched fulfillment.

• Contact a real payment processor or fulfillment provider.

• Execute arbitrary SQL or arbitrary status changes.

Idempotency

An approved apply request requires a caller-provided idempotency key.

• Same key and same request → return the original result without repeating mutations.

• Same key used for different request data → IDEMPOTENCY_KEY_CONFLICT.

• Different key used against an applied plan → PLAN_ALREADY_APPLIED.

Reuse a key only when retrying the same application request.

Health and database connectivity

The Worker exposes:

• GET /health for service health.

• GET /health/database for a fixed PostgreSQL connectivity check.

• /mcp for Streamable HTTP MCP clients.

Verify the local database path with:

curl http://localhost:8787/health/database

The connectivity endpoint runs only a fixed SELECT 1; it never accepts SQL from the request. get_demo_guide reports the same availability concept but still loads safely when PostgreSQL is unavailable.

Local development uses the direct connection string to emulate the HYPERDRIVE binding. To test the hosted Hyperdrive configuration without a deployment, use:

pnpm dev:remote

Remote development uses the hosted database, so treat it like a production-data connection.

Database schema

src/db/schema.ts is the source of truth. Generated PostgreSQL migrations and Drizzle metadata are committed under migrations/.

With the direct connection configured in .env:

pnpm db:generate
pnpm db:migrate
pnpm db:verify

db:verify checks the public table and constraint catalog. Worker traffic uses the Hyperdrive binding, while local migration and seed scripts use the direct PostgreSQL connection.

MCP Inspector

With the Worker running, list the registered tools from another terminal:

pnpm dlx @modelcontextprotocol/inspector@latest \
  --cli http://localhost:8787/mcp \
  --transport http \
  --method tools/list

Suggested demonstration sequence:

1. Call get_demo_guide.

2. Investigate ORD-DEMO-1043.

3. Prepare its recovery plan.

4. Call apply_recovery with approved: false and confirm no mutation.

5. Apply with approved: true and a new idempotency key.

6. Repeat with the same key and verify idempotentReplay: true.

7. Use ORD-DEMO-1044 for a second clean recovery demonstration.

Validation

pnpm test
pnpm typecheck
pnpm lint
pnpm db:verify

Scope

The project uses synthetic commerce data and does not communicate with a real payment processor or fulfillment provider.

Approval is represented by approved: true in the MCP call. Operator identity is not independently authenticated within this assignment.