Commerce Ops Harness

A remotely hosted Model Context Protocol server, written in TypeScript, that lets an AI agent investigate and safely resolve commerce operations exceptions — stuck orders, payment mismatches, inventory truth gaps, fulfillment stalls, refund decisions — across the four systems where the truth actually lives: orders, payments, inventory, and fulfillment.

The MCP is the product. There is no frontend; any MCP client (Claude, Cursor, MCP Inspector) is the operator console.

System design with diagrams: ARCHITECTURE.md. Design rationale, assumptions, and exclusions: PRODUCT_DECISIONS.md. Original technical plan: PLAN.md. AI usage: AI_WORKLOG.md.

Design

Ops exceptions cross system boundaries: a "stuck order" is a payment fact, an inventory fact, and a fulfillment non-event that no single system can explain. Rather than encoding a playbook per problem type, the server exposes a small, composable protocol surface:

• Read tools join state across systems (get_timeline, diff_inventory, get_payment_events).

• A deterministic diagnosis engine turns joined state into root-cause codes with evidence and confidence — rules over state, not lookups over seed data, so tests can assert exact outcomes.

• A guarded action executor mutates state only through dry-run previews, explicit confirmation, state-machine preconditions, and an audit trail.

• Domain skills (markdown recipes, exposed as tools and resources) capture investigation know-how without freezing the agent onto rails.

The split is deliberate: the LLM client owns natural-language reasoning; the server owns truth and safety. Diagnosis is testable because it is deterministic; the agent is useful because the tools compose.

┌────────────────────────────────────────────────────────┐
│   MCP client (Claude Desktop / Cursor / Inspector)     │
└───────────────────────────┬────────────────────────────┘
                            │ Streamable HTTP
┌───────────────────────────▼────────────────────────────┐
│         Commerce Ops Harness MCP (TypeScript)          │
│   17 tools · 3 resources · 3 prompts                   │
├────────────────────────────────────────────────────────┤
│   Case runtime        investigation identity, audit    │
│   Diagnosis engine    deterministic rules + evidence   │
│   Action executor     dry-run, confirm, preconditions  │
│   Domain skills       markdown recipes                 │
├────────────────────────────────────────────────────────┤
│   Synthetic substrate                                  │
│   orders · payments · inventory · shipments · policy   │
│   8 seeded failure scenarios                           │
└────────────────────────────────────────────────────────┘

Related MCP server: Mercora

Quick start (no local setup)

Point any MCP client at the hosted endpoint:

{
  "mcpServers": {
    "commerce-ops-harness": {
      "url": "https://commerce-ops-harness.onrender.com/mcp"
    }
  }
}

In Claude Desktop: Settings → Connectors → Add custom connector → paste the URL. Config keys vary slightly across clients; POST /mcp over Streamable HTTP is the stable contract.

Then ask the agent something like:

Order ord_5001 — the customer paid six hours ago and nothing has shipped. Investigate and fix it. Preview before committing anything.

The expected tool path: open_case → get_timeline → diagnose (returns ALLOCATION_FAILURE with evidence) → list_actions → execute_action with dry_run: true → commit with dry_run: false, confirm: true. The audit trail is available via get_audit_log.

Seeded scenarios

Every scenario is seed data on the same protocol surface — same tools, same rules, same guards.

Protocol surface

Investigate — list_scenarios · open_case · get_case · search_entities · get_entity · get_timeline · diff_inventory · get_payment_events · get_policy · get_audit_log

Reason — diagnose · list_actions · explain_state

Act (guarded) — execute_action: retry_inventory_allocation, sync_payment_status, release_reservation, retrigger_fulfillment, issue_refund, adjust_inventory_count, create_ops_exception, add_case_note

Harness — list_skills · get_skill · reset_demo_data

Resources — commerce://scenarios · commerce://policy/refund · commerce://skills/{id} (listable template)

Prompts — investigate_exception · refund_decision · inventory_reconcile

Safety model

Guards are layered so that no single flag — and no single confused agent — can cause a bad mutation:

1. Dry-run by default. Every mutation previews unless dry_run: false is explicit.

2. Confirmation for high-risk commits. Money and stock mutations additionally require confirm: true.

3. State preconditions, independent of flags. The executor validates order/shipment state and fails closed: an unallocated order cannot be shipped (INVALID_STATE), a mismatched capture cannot be synced over (AMOUNT_MISMATCH), insufficient stock cannot be allocated (INSUFFICIENT_STOCK).

4. Policy-driven refund blocks. Auto-refund is refused for packed, shipped, and delivered orders (POLICY_BLOCK) — packed included deliberately to avoid racing the warehouse — with create_ops_exception as the escalation path.

5. Idempotency. Committed actions can carry an idempotency key; replays are flagged, and the cache is store-scoped and cleared on reset so a replay can never claim a commit that didn't happen on current state.

6. Audit. Every action lands in get_audit_log with inputs, outcome, and dry-run status.

Channel and warehouse stock are kept as separate ledgers: allocation and release adjust the channel incrementally; only the explicit adjust_inventory_count reconciles one to the other.

Demo-state caveats

• The substrate is a single in-memory tenant. Concurrent testers share state; restarts reseed it. seededAt (on /health and list_scenarios) makes this visible; reset_demo_data gives a clean slate.

• Seed timestamps are relative to process start, so time-window diagnoses drift on a long-lived process. Reseed before demos.

Verification

npm test              # engine + MCP-layer integration tests
npm run verify        # end-to-end primary workflow + all scenario codes + guard checks
npm run smoke:remote  # the same checks against the hosted URL (resets shared demo state)

Two test layers, on purpose. tests/harness.test.ts covers the engine: diagnosis codes per scenario, guard behavior, mutations, idempotency, audit. tests/mcp.test.ts covers the protocol surface itself — a real MCP client over the SDK's in-memory transport exercising tool registration, schema rejection of invalid input, resources, prompts, and the primary workflow end to end. smoke-remote runs a real Streamable HTTP client against the deployed server, so "it works hosted" is a command, not a claim.

Development

Requires Node 20+.

git clone https://github.com/VasuBansal7576/commerce-ops-harness
cd commerce-ops-harness
npm install
npm test
npm run dev      # Streamable HTTP on http://127.0.0.1:8787/mcp
npm run stdio    # stdio transport for local MCP clients

Deployment

Hosted on Render's free tier (Singapore, HTTPS). Pushes to main trigger a deploy through .github/workflows/deploy.yml; .github/workflows/keep-warm.yml pings the health endpoint on a schedule to offset free-tier spin-down. Details, caveats, and alternative deploy paths (Docker, blueprint) are in HOSTING.md.

Repository map

src/server.ts           MCP surface: tools, resources, prompts
src/index.ts            Streamable HTTP entrypoint
src/stdio.ts            stdio entrypoint
src/engine/             diagnosis rules, guarded actions, cases, timeline
src/data/store.ts       synthetic substrate + seeded scenarios
src/skills/             skill loader
skills/                 domain investigation recipes (markdown)
tests/                  engine + MCP-layer tests
scripts/                local E2E verification, remote smoke

Assignment deliverables

License

MIT