AI-Native Commerce Operations MCP Server

This repository contains a Model Context Protocol (MCP) server built in TypeScript, acting as an operational agent for e-commerce exception handling (e.g., stuck packages, missing items, refund escalations).

Features

• MCP Tools: Exposes capabilities to check order details, tracking status, evaluate refund policies, and safely execute remediation actions.

• Safety First: Hardcoded safety guardrail where any refund action above $150 is automatically blocked and flagged for human approval (PENDING_APPROVAL).

• PostgreSQL Persistence: Complete operational schema including tracking order states, remediation actions, refunds with idempotency, and immutable audit logs.

• SSE Transport: Uses standard Express server with Server-Sent Events (SSE) for reliable MCP transport.

Related MCP server: commerce-ops-harness

Setup Instructions

Prerequisites

• Node.js (v18+)

• Docker & Docker Compose (for local PostgreSQL database)

Installation

1. Install dependencies:

   npm install

2. Start the local PostgreSQL database:

   docker-compose up -d

3. Run the database migrations and seed synthetic data:

   npm run db:migrate
   npm run db:seed

Running the Server

Start the MCP server in development mode:

npm run dev

The server will start on port 3000:

• SSE Endpoint: http://localhost:3000/sse

• Messages Endpoint: http://localhost:3000/messages

You can connect to this server using an MCP client (like Claude Desktop) by configuring it to use the SSE transport with the URL http://localhost:3000/sse.

Testing

Run the vitest test suite to verify the core safety boundaries and business logic:

npm test

Note: npm test uses an in-memory database (pg-mem) for zero-setup execution, while production connects to PostgreSQL via PGHOST / DATABASE_URL.

Product Decisions & Tradeoffs

• Direct PostgreSQL Client (pg) over ORMs: To prioritize a "small, coherent solution" and respect the provided raw SQL schema without abstracting it away, we used the standard pg driver instead of heavy ORMs (Prisma, Drizzle). This keeps the migration and execution path 1-to-1 with the schema.

• Express + SSE for Transport: Since the goal is a "remotely accessible" MCP server, Server-Sent Events (SSE) is chosen as it's the standard for remote MCP communication over HTTP, allowing a seamless connection with remote LLM clients without dealing with Stdio complexities over networks.

• Audit Logging Strategy: Audit logs are inserted synchronously alongside the remediation actions within a database transaction. A tradeoff here is slightly longer transaction times in exchange for guaranteed logging correctness.

• Exclusions: As requested by the assignment scope, this solution excludes authentication, frontend applications, and full CI/CD deployment pipelines. The focus is strictly on a robust MCP server and accurate backend database operations.

Available MCP Tools

• get_order_details: Fetch full order state, items, and customer risk score.

• check_tracking_status: Fetch carrier shipment logs and current status.

• evaluate_refund_policy: Checks refund eligibility based on SLA, customer risk, and tracking status.

• execute_remediation: Triggers an action (REFUND, REPLACEMENT, CARRIER_CLAIM). Safely catches high-value refunds and enforces an immutable audit trail.