# 🛒 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 & Step-by-Step Call Flow

### 1. Vertical Sequential Call & Policy Execution Flow

```text
[ Ops User Inquiry ]
  │  "Investigate operational exception or order status"
  ▼
[ Client LLM (MCP Consumer) ]
  │
  ├─► STEP 1: Discovery & Telemetry Retrieval
  │   Tool Call: search_orders(order_id)
  │   └──► [ CommerceOps MCP Server ]
  │        Returns: Raw Telemetry Record (order_status, payment, inventory, fulfillment, risk_score)
  │
  ├─► STEP 2: Root-Cause Reasoning & Evidence Synthesis
  │   Tool Call: diagnose(order_id)
  │   └──► [ CommerceOps MCP Server ]
  │        Returns: Dynamic root_cause, evidence snapshot & recommended resolution action
  │
  ├─► STEP 3: Agentic Decision Node
  │   Evaluate Resolution Pathway:
  │   ├── Autonomous Resolution  ──► (Proceed to Pre-Execution Safety Evaluation)
  │   └── Escalation Required    ──► (Flag for Supervisor / Procurement / Fraud Review)
  │
  ├─► STEP 4: Pre-Execution Safety & Policy Guardrails
  │   Tool Call: evaluate_safety(order_id, action)
  │   └──► [ CommerceOps MCP Server Policy Engine ]
  │        Evaluates Central Rules:
  │        ├── 1. Fraud Risk Pre-Gate  : (risk_score <= 60)
  │        ├── 2. Auto-Refund Cap      : (amount <= ₹1,000 INR)
  │        ├── 3. Fulfillment Staleness : (days_inactive >= 3)
  │        └── 4. Oversold Stock Gate  : (stock_on_hand > 0)
  │        Returns: { allowed: boolean, reason: string }
  │
  ├─► STEP 5: State Mutation & Durable Audit Logging
  │   Tool Call: execute_resolution(order_id, action)
  │   └──► [ CommerceOps MCP Server Data Engine ]
  │        ├── Mutates Order State (refunded / requeued_picking / escalated)
  │        └── Appends Audit Entry to commerce://audit/log & Neon PostgreSQL
  │        Returns: Execution outcome & durable audit ID
  │
  ▼
[ Ops User Response ]
  Transparent report: Root cause + Guardrail status + Execution result + Audit trace
```

### 2. High-Level Component Architecture

```text
+-----------------------------------------------------------------------------------+
|                            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    |                     |
|                  | - Risk Gate (risk_score <= 60)          |                     |
|                  | - MAX_AUTO_REFUND_LIMIT_INR (₹1,000)     |                     |
|                  | - Staleness Threshold (3 days)           |                     |
|                  | - Oversold Stock Protection (OnHand > 0) |                     |
|                  +------------------------------------------+                     |
|                                        │                                          |
|                                        ▼                                          |
|                  +------------------------------------------+                     |
|                  |      COMMERCE STORE & DATA ENGINE        |                     |
|                  |   (OMS, WMS, Payment Gateway, Audit Log) |                     |
|                  +------------------------------------------+                     |
|                                        │                                          |
|                                        ▼                                          |
|                  +------------------------------------------+                     |
|                  |     DURABLE FILE & NEON DB PERSISTENCE   |                     |
|                  |         (./data/audit_log.json)          |                     |
|                  +------------------------------------------+                     |
+-----------------------------------------------------------------------------------+
```

### 3. Detailed Step-by-Step Execution Lifecycle

1. **Discovery & Data Fetch (`list_orders` / `search_orders`)**:
   - The Client LLM searches or fetches raw order signals (`payment.payment_status`, `payment.risk_score`, `fulfillment.picking_status`, `inventory.stock_on_hand`).
   - Signal data contains zero pre-baked diagnostic answers.

2. **Dynamic Root Cause Diagnosis (`diagnose`)**:
   - The server inspects raw telemetry dynamically and infers root cause (e.g., missed payment webhook, warehouse bottleneck, oversold flash-sale, fraud risk).
   - Returns diagnostic evidence snapshot and recommended resolution action.

3. **Pre-Execution Safety & Escalation Gate (`evaluate_safety`)**:
   - Before executing any mutation, safety policies are evaluated in strict order:
     1. **Fraud Risk Gate**: `payment.risk_score > 60` immediately short-circuits execution and marks order as `ESCALATED` to human fraud team.
     2. **Autonomous Refund Cap**: Refunds > ₹1,000 INR require human manager escalation.
     3. **Fulfillment Staleness Threshold**: Warehouse requeue requires elapsed staleness `>= 3 days`.
     4. **Oversold Inventory Gate**: Stock release blocked if physical inventory on hand is 0.

4. **Bounded State Mutation & Durable Auditing (`execute_resolution`)**:
   - **Allowed Actions**: Bounded enum (`mark_order_paid_reconcile`, `refund_duplicate_charge`, `refund_over_cap`, `requeue_to_warehouse`, `release_reserved_stock`, `resync_shipping_address`).
   - If safety passes, state is updated (`paid`, `requeued`, `refunded`, etc.) and an `executed` entry is logged.
   - If safety fails or human review is required, status becomes `escalated` and an `escalated` entry is logged.
   - All events append to both `commerce://audit/log` and `commerce://analysis/log` (or Neon DB tables).

---

## 📊 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 | Reconcile missed webhook (no money movement) | **EXECUTED**: Status set to `paid`, webhook flag set `true` |
| `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 (`recommended_action: null`) |
| `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`:

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

### 2. Build & Run locally

```bash
# 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`)

```bash
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`)

```bash
# 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=mark_order_paid_reconcile

# 2. Test ORD-1001 reconciliation 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=mark_order_paid_reconcile

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

---

## 🧠 Design Rationale & Production Limitations

### Deterministic Rule-Based Diagnostic Engine vs. Free-Form LLM Reasoning

The `diagnose()` tool is implemented as a **deterministic, rule-based engine** rather than having the LLM reason freely over raw order data each time:

- **How it works**: The tool evaluates a fixed set of priority rules against raw telemetry fields (payment gateway status, webhook receipt, inventory reservation, staleness, stock levels) and returns the first matching root cause alongside structured evidence. Nothing is pre-labeled in the seed data itself — the conclusion is computed fresh on every call.
- **Why this design**: Root-causing whether an order is stuck and why has one correct answer given the data. Externalizing this into a deterministic engine ensures diagnostic accuracy is **reliable, repeatable, and unit-testable**, rather than left to non-deterministic LLM judgment each time.
- **LLM's Role**: The Client LLM's role is to decide what to do with the diagnosis (call `evaluate_safety`, `execute_resolution`, or report back), not to re-derive the root cause itself.
- **Scenarios Covered**:
  1. Missed/Dropped Payment Webhook (`mark_order_paid_reconcile`)
  2. Stalled Warehouse Fulfillment (`requeue_to_warehouse`)
  3. Over-Cap Refund Request (`refund_over_cap`)
  4. Oversold Flash-Sale Inventory (`release_reserved_stock`)
  5. Healthy Control Case (`recommended_action: null`)

### Production Trade-offs & Limitations

- **Rule Scalability**: This hardcoded rule-based approach covers the 5 seeded e-commerce scenarios well, but would not scale cleanly to hundreds of complex edge cases as-is.
- **Production Architecture Next Steps**: A full enterprise production version would:
  1. Externalize rules into a **data-driven rule engine table** (e.g. JSON-Logic / Drools).
  2. Incorporate an **LLM-assisted fallback mechanism** for unmapped operational anomalies rather than defaulting strictly to "healthy", allowing novel edge cases to be dynamically flagged for human triage.

---

## 📁 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
```