OrderOps MCP

OrderOps is a small, AI-native operations service for investigating and safely resolving commerce order exceptions. It gives an MCP-capable assistant a coherent workflow across synthetic order, payment, inventory, and fulfillment systems without requiring an operator to ask an engineer for every trace.

Source repository: https://github.com/Flamki/order-ops-mcp

The deliberately narrow automated path is an expired inventory reservation: when payment is captured, stock is available, and fulfillment is blocked on the missing reservation, an operator can review a state-bound proposal and approve a re-reservation. Payment changes, customer data, refunds, cancellations, and customer contact are never automated.

Hosted endpoint

• MCP: https://order-ops-mcp.shared-trapezoid.workers.dev/mcp
• Health: https://order-ops-mcp.shared-trapezoid.workers.dev/health

The Cloudflare deployment has been claimed by its owner and the deployed Streamable HTTP endpoint has been verified with the included MCP client. Proposal, execution, and idempotency state is coordinated in one SQLite-backed Durable Object.

Product workflow

1. orders_list_exceptions discovers the three synthetic exception cases.
2. orders_investigate joins evidence from the OMS, payment processor, inventory service, and fulfillment provider.
3. orders_propose_resolution rechecks policy and creates a 10-minute proposal bound to the current order-state fingerprint.
4. The assistant presents the evidence, exact changes, and approval phrase to a human and stops.
5. orders_execute_resolution validates exact approval, expiry, unchanged state, policy preconditions, and an idempotency key before mutating the synthetic order.
6. The operator receives a structured before/after receipt. An exact retry returns the original receipt and does not mutate twice.

The MCP is the product boundary, not a wrapper around a separate UI. Tool descriptions tell the model when to call each capability, Zod schemas advertise and validate inputs and structured outputs, annotations identify read and write behavior, and the server exposes the governing runbook as an MCP resource. A prompt provides a client-independent triage workflow.

MCP surface

Capability	Role	Side effect
orders_list_exceptions	Discover synthetic cases	None
orders_investigate	Explain cross-system root cause and evidence	None
orders_propose_resolution	Create a short-lived, state-bound proposal	No order mutation
orders_execute_resolution	Apply the single permitted resolution and return a receipt	Mutates synthetic state
demo_reset_synthetic_state	Let another evaluator replay the synthetic workflow	Clears all demo state
ops://runbooks/order-exceptions/v1	Machine-readable automation policy	None
triage-order-exception	Prompt that enforces investigate → propose → wait	None

Demo cases

Order	Diagnosis	Automated?
ORD-1001	Captured payment, expired reservation, fulfillment blocked, stock available	Yes, with explicit approval
ORD-1002	Payment failed	No
ORD-1003	Invalid shipping address	No
ORD-1004	Healthy control order	No action needed

All records are synthetic and contain no customer PII or production credentials.

Test with an MCP client

Use the MCP Inspector and connect to http://localhost:8787/mcp:

npx @modelcontextprotocol/inspector@latest

Or use the included real Streamable HTTP client:

npm install
npm run dev

In a second terminal:

npm run demo

The default demo stops before mutation. Only after reviewing the proposal:

npm run demo -- --execute-approved

If another evaluator has already resolved the shared synthetic order:

npm run demo -- --reset-first --execute-approved

To target a deployed server:

$env:MCP_URL = "https://your-worker.workers.dev/mcp"
npm run demo

Verify and deploy

Requirements: Node.js 22+ and npm.

npm install
npm run verify
npx wrangler deploy --dry-run
npm run deploy

npm run verify performs strict TypeScript checking and 14 focused tests. The tests cover diagnosis, out-of-policy cases, exact approval, proposal expiry, stale state, mutation receipts, idempotent replay, and idempotency conflicts. npm audit currently reports zero known vulnerabilities.

Cloudflare Workers is used because it directly supports remote Streamable HTTP MCP via the TypeScript MCP SDK and provides a small deployment surface. The server follows the current stateless handler pattern rather than the deprecated sessionful McpAgent path.

Architecture and boundaries

MCP client
    |
Streamable HTTP /mcp
    |
tool schemas + policy gates
    |
investigation / proposal / execution domain
    |
synthetic OMS + payments + inventory + fulfillment adapter

For the bounded demo, a named Durable Object serializes operations and persists the synthetic adapter, proposals, receipts, and idempotency ledger in SQLite. A production version would replace the synthetic order adapter with internal OMS/WMS APIs, add OAuth and role scopes, retain immutable audit events, rate-limit writes, and define operational reset/recovery procedures. The domain rules and tests remain reusable.

Human approval is a semantic client boundary, not proof of human presence: an untrusted client can copy an approval phrase. Production execution therefore also needs authenticated operator identity and an approval UI or MCP elicitation flow.

See product decisions, AI worklog, demo script, and client communication drafts.