Commerce Ops Harness MCP

AI-native commerce operations control plane — a remotely hosted Model Context Protocol server in TypeScript that lets AI agents investigate and safely resolve operational exceptions across orders, payments, inventory, and fulfillment.

Philosophy: the Browser Harness idea applied to commerce — a general protocol surface for multi-system truth, not one-off playbooks for a single site or ticket type. See PLAN.md and PRODUCT_DECISIONS.md.

---

Hosted MCP URL

	URL
MCP (Streamable HTTP)	http://bore.pub:7446/mcp
Health	http://bore.pub:7446/health
Service info	http://bore.pub:7446/
Source repo	https://github.com/VasuBansal7576/commerce-ops-harness

Remote MCP verified with initialize over public HTTP. The public tunnel forwards to the running TypeScript server (process must stay up; see HOSTING.md for durable PaaS deploy via render.yaml).

Local default: http://127.0.0.1:8787/mcp

---

What this is

Layer	Role
MCP tools	Protocol: timeline, entities, diagnose, guarded actions, skills
Case runtime	Investigation identity + audit
Synthetic substrate	Multi-system commerce truth with seeded failure modes
Domain skills	Learned recipes (skills/*.md) — optional guidance, not hard rails

Not included (by design): frontend, auth IdP, real payment/WMS credentials, browser automation.

---

Quick demo (primary workflow)

Scenario: paid_no_allocation — order ord_5001
Customer paid; inventory never allocated; order stuck in processing.

Agent tool sequence:

1. list_scenarios
2. open_case { "order_id": "ord_5001" }
3. get_timeline { "order_id": "ord_5001" }
4. diagnose { "order_id": "ord_5001" } → expect ALLOCATION_FAILURE
5. list_actions
6. execute_action { "type": "retry_inventory_allocation", "order_id": "ord_5001", "dry_run": true }
7. Optional commit: same with "dry_run": false, "confirm": true if free stock allows

Other scenarios (same surface):

Scenario id	Order	Primary code
paid_no_allocation	ord_5001	ALLOCATION_FAILURE
payment_order_desync	ord_5002	PAYMENT_ORDER_DESYNC
channel_wms_mismatch	ord_5003	INVENTORY_TRUTH_GAP
packed_not_shipped	ord_5004	FULFILLMENT_STALL
refund_eligible_unshipped	ord_5005	REFUND_ELIGIBLE
refund_blocked_delivered	ord_5006	REFUND_BLOCKED
partial_capture_mismatch	ord_5007	PAYMENT_AMOUNT_MISMATCH
double_reservation_race	ord_5008	INVENTORY_OVER_RESERVED

---

Connect an MCP client

Claude Desktop / Cursor (remote HTTP)

{
  "mcpServers": {
    "commerce-ops-harness": {
      "url": "http://bore.pub:7446/mcp"
    }
  }
}

Exact config keys vary by client version — use Streamable HTTP / remote MCP URL pointing at /mcp.

Local stdio

npm install
npx tsx src/stdio.ts

{
  "mcpServers": {
    "commerce-ops-harness": {
      "command": "npx",
      "args": ["tsx", "src/stdio.ts"],
      "cwd": "/path/to/commerce-ops-harness"
    }
  }
}

Local HTTP

npm install
npm run dev
# MCP at http://127.0.0.1:8787/mcp

---

MCP tools (summary)

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 — dry-run default; high-risk needs confirm=true

Harness: list_skills, get_skill, reset_demo_data

Prompts: investigate_exception, refund_decision, inventory_reconcile

Resources: commerce://scenarios, commerce://policy/refund

---

Setup (development)

git clone <this-repo>
cd commerce-ops-harness
npm install
npm test
npm run verify
npm run dev

Requirements: Node.js 20+.

---

Verification

npm test          # vitest — diagnose codes, confirm guards, mutations, audit
npm run verify    # primary E2E workflow + all scenario codes

Focused behaviors covered:

• Multi-system timeline join
• Expected primary diagnosis per seed scenario
• Dry-run does not mutate
• High-risk actions blocked without confirm
• Refund eligible vs blocked policy paths
• Payment sync, fulfillment re-trigger, inventory reconcile commits

---

Safety

• Synthetic data only
• dry_run defaults to true
• Money/stock mutations require confirm: true
• Full audit log via get_audit_log
• Fail closed on insufficient stock / policy blocks

---

Repository map

PLAN.md                 Full technical plan
PRODUCT_DECISIONS.md    Assumptions & exclusions
AI_WORKLOG.md           AI usage log for the assignment
skills/                 Domain investigation recipes
src/data/               Synthetic multi-system store
src/engine/             Diagnose, actions, cases, timeline
src/server.ts           MCP tool/resource/prompt registration
src/index.ts            Remote Streamable HTTP server
tests/                  Focused verification

---

Assignment deliverables

Item	Location
Hosted MCP URL	Above + service root JSON
Source repo	This repository
README	This file
Product decisions	PRODUCT_DECISIONS.md
Tests / verification	npm test, npm run verify
AI worklog	AI_WORKLOG.md
Async video (4–5 min)	Submitter records separately

---

License

MIT