🛒 CommerceOps MCP Server — AI-First Commerce Operations Server

An AI-native, production-grade Model Context Protocol (MCP) server written in TypeScript, designed to enable AI Operations Agents to autonomously investigate and resolve complex e-commerce operational exceptions (stuck orders, missed payment webhooks, warehouse fulfillment delays, and oversold inventory).

---

🎯 Key Architectural Pillars

1. Raw Operational Signals (No Pre-Baked Diagnostic Labels): Seed orders store only realistic backend fields (order_status, payment, inventory, fulfillment). diagnose() computes root-cause explanations and evidence dynamically at runtime.

2. Strict Bounded Action Enum & Safety Policy: All state mutations are restricted to a closed enum of actions (refund_duplicate_charge, requeue_to_warehouse, release_reserved_stock, resync_shipping_address). Every resolution call structurally enforces a pre-execution safety check (evaluate_safety).

3. Universal Risk-Score Pre-Gate & Central Policy Config:

   • Payment Risk Gate: Orders with risk_score > 60 are blocked and escalated immediately.
   • Autonomous Refund Cap: Auto-refunds capped at ₹1,000 INR. Over-limit refunds are escalated.
   • Fulfillment Staleness Threshold: Warehouse requeue requires days_since_last_update >= 3.
   • Oversold Stock Protection: Stock release blocked if stock_on_hand === 0.

4. Neon PostgreSQL Database & Dual Store Architecture:

   • Cloud Persistence: Uses @neondatabase/serverless to store all 6 normalized order tables, audit_log, and order_analysis_log in a Neon DB instance when DATABASE_URL is set.
   • Local Dev Fallback: Gracefully falls back to an in-memory store when running locally without a database connection.

5. Durable Auditing & Order Analysis Activity Logging:

   • Audit Log: Durably records every resolution attempt (executed vs escalated), policy reason, and actor.
   • Analysis Log: Records diagnostic runs, evidence snapshots, and safety check evaluations for full operational auditability.
   • Exposed via MCP resources (commerce://audit/log, commerce://analysis/log) and REST API (/api/audit, /api/analysis).

---

🏗️ Technical Architecture Diagram

+-----------------------------------------------------------------------------------+
|                            MCP AI CONSUMER CLIENT                                 |
|            (Claude Desktop / Cursor / Custom Agent / Antigravity IDE)             |
+-----------------------------------------------------------------------------------+
                                         │
                   Remote SSE (/sse) OR Stdio Transport (--stdio)
                                         ▼
+-----------------------------------------------------------------------------------+
|                           COMMERCE OPS MCP SERVER                                 |
|                                                                                   |
|  +------------------------+  +------------------------+  +---------------------+  |
|  |     BOUNDED TOOLS      |  |     MCP RESOURCES      |  |     MCP PROMPTS     |  |
|  | - list_orders          |  | - orders/seed          |  | - investigate_stuck |  |
|  | - search_orders        |  | - audit/log            |  +---------------------+  |
|  | - diagnose             |  | - analysis/log         |                           |
|  | - evaluate_safety      |  +------------------------+                           |
|  | - execute_resolution   |                                                       |
|  +------------------------+                                                       |
|                                        │                                          |
|                                        ▼                                          |
|                  +------------------------------------------+                     |
|                  |     SAFETY & ESCALATION POLICY ENGINE    |                     |
|                  | - MAX_AUTO_REFUND_LIMIT_INR (₹1,000)     |                     |
|                  | - Risk Gate (risk_score <= 60)          |                     |
|                  | - Staleness Threshold (3 days)           |                     |
|                  +------------------------------------------+                     |
|                                        │                                          |
|                                        ▼                                          |
|                  +------------------------------------------+                     |
|                  |      COMMERCE STORE & DATA ENGINE        |                     |
|                  |   (OMS, WMS, Payment Gateway, Audit Log) |                     |
|                  +------------------------------------------+                     |
|                                        │                                          |
|                                        ▼                                          |
|                  +------------------------------------------+                     |
|                  |     DURABLE FILE & NEON DB PERSISTENCE   |                     |
|                  |         (./data/audit_log.json)          |                     |
|                  +------------------------------------------+                     |
+-----------------------------------------------------------------------------------+

---

📊 Seed Dataset & Policy Matrix (6 Core Scenarios)

Order ID	Customer	Amount	Raw Signals	Diagnostic Root Cause	Policy / Safety Evaluation	Expected Outcome
ORD-1001	Aarav Sharma	₹300	captured, pending, webhook: false, risk: 10	Missed gateway webhook	Amount ₹300 <= ₹1,000 cap	EXECUTED: Refund ₹300 recorded
ORD-1002	Priya Patel	₹4,999	reserved, picked: false, stale: 4 days	Fulfillment stalled at warehouse	Stale 4 days >= 3 threshold	EXECUTED: Requeued for picking
ORD-1003	Vikramaditya Roy	₹4,000	status: refund_requested, risk: 20	Refund requested above cap	Amount ₹4,000 > ₹1,000 cap	ESCALATED: Requires supervisor approval
ORD-1004	Sneha Kulkarni	₹12,999	captured, reserved, stock_on_hand: 0	Inventory oversold (flash-sale)	Stock on hand is 0	ESCALATED: Requires procurement review
ORD-1005	Rohan Verma	₹1,499	captured, picked: true, stock_on_hand: 31	No issue found (control case)	N/A (normal processing)	NO ACTION: Progressing normally
ORD-1006	Meera Nair	₹500	captured, pending, webhook: false, risk: 85	Missed gateway webhook	Risk score 85 > 60 threshold	ESCALATED: Blocked by Fraud Risk Gate

---

🛠️ MCP Tools, Resources & Prompts

1. Bounded MCP Tools (src/mcp/tools.ts)

Tool Name	Description	Key Arguments
list_orders	Returns triage-level list of orders with computed flagged_for_review boolean.	status (optional filter)
search_orders	Returns full raw order record (nested payment, inventory, fulfillment, items).	order_id (required), status, customer
diagnose	Computes root-cause reasoning, evidence snapshot, and recommended action.	order_id (required)
evaluate_safety	Pre-execution safety check against centralized policy thresholds.	order_id (required), action (required)
execute_resolution	Executes bounded action after safety check. Writes to audit & analysis logs.	order_id (required), action (required), actor
reset_store_to_defaults	TRUNCATEs DB/memory store and re-seeds original 6 seed orders.	None

2. MCP Resources (src/mcp/resources.ts)

• commerce://orders/seed: Live JSON list of all seed orders.
• commerce://audit/log: Immutable audit log of all resolution attempts (executed / escalated).
• commerce://analysis/log: Full agent activity trace (diagnostic runs, evidence, safety evaluations).

3. MCP Prompts (src/mcp/prompts.ts)

• investigate_stuck_order: Step-by-step guided prompt instructing an AI Operations Agent to search order, run diagnosis, evaluate safety guardrails, execute resolution, and draft transparent customer updates.

---

🚀 Deployment & Environment Setup

1. Environment Variables (.env)

Copy .env.example to .env:

DATABASE_URL=postgresql://neondb_owner:password@ep-host.aws.neon.tech/neondb?sslmode=require
PORT=3000

2. Build & Run locally

# Install dependencies
npm install

# Build TypeScript to dist/
npm run build

# Start production SSE server
npm start

3. Deploying to Render

• Environment: Node.js Web Service
• Build Command: npm run build
• Start Command: npm start
• Environment Variables: Add DATABASE_URL pointing to your Neon database URL.

---

🧪 Testing & MCP Inspector CLI Verification

Run Unit Test Suite (Vitest)

npm test

Output:

 ✓ tests/workflow.test.ts (1 test)
 ✓ tests/guardrails.test.ts (6 tests)
 ✓ tests/mcp-tools.test.ts (5 tests)

 Test Files  3 passed (3)
      Tests  12 passed (12)

Test via MCP Inspector CLI (dist/stdio.js)

# 1. Test ORD-1006 risk score escalation
npx @modelcontextprotocol/inspector --cli node dist/stdio.js \
  --method tools/call --tool-name execute_resolution \
  --tool-arg order_id=ORD-1006 --tool-arg action=refund_duplicate_charge

# 2. Test ORD-1001 auto-refund execution
npx @modelcontextprotocol/inspector --cli node dist/stdio.js \
  --method tools/call --tool-name execute_resolution \
  --tool-arg order_id=ORD-1001 --tool-arg action=refund_duplicate_charge

# 3. Read Analysis Activity Logs Resource
npx @modelcontextprotocol/inspector --cli node dist/stdio.js \
  --method resources/read --uri commerce://analysis/log

---

📁 Repository Structure

commerce-ops-mcp/
├── src/
│   ├── index.ts                # Remote SSE/HTTP Express Server (/sse, /message, /health, /api/*)
│   ├── stdio.ts                # Stdio Entrypoint for local MCP Inspector testing
│   ├── server.ts               # MCP Server instantiation & tool/resource registration
│   ├── chat.ts                 # Interactive Ops AI Chat handler
│   ├── config.ts               # Centralized Policy Config thresholds (caps, risk limit, staleness)
│   ├── db/
│   │   └── client.ts           # Singleton Neon Serverless PostgreSQL SQL client
│   ├── domain/
│   │   ├── types.ts            # Core Interfaces (Order, Payment, Inventory, AuditLog, AnalysisLog)
│   │   ├── mockData.ts         # Raw 6 Seed Orders (no diagnostic labels)
│   │   ├── store.ts            # In-Memory Store Implementation (ICommerceStore)
│   │   └── dbStore.ts          # Neon PostgreSQL Store Implementation (DatabaseCommerceStore)
│   └── mcp/
│       ├── tools.ts            # 5 Bounded MCP Tools + reset tool
│       ├── resources.ts        # MCP Resources (orders, audit log, analysis activity log)
│       ├── prompts.ts          # MCP Prompts (guided investigation workflow)
│       └── guardrails.ts       # Safety Guardrail Engine wrapper
├── tests/
│   ├── guardrails.test.ts      # Policy thresholds & Risk-score pre-gate tests
│   ├── mcp-tools.test.ts       # Bounded tool execution & audit log tests
│   └── workflow.test.ts        # Full 6-seed scenario integration tests
├── .env.example                # Template environment file
├── .gitignore                  # Git ignore rules (.env, dist/, node_modules/, draft files)
├── AI_WORKLOG.md               # AI Worklog, Prompts & Correction Audit
├── package.json
└── tsconfig.json