# 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.

## Setup Instructions

### Prerequisites
- Node.js (v18+)
- Docker & Docker Compose (for local PostgreSQL database)

### Installation
1. Install dependencies:
   ```bash
   npm install
   ```
2. Start the local PostgreSQL database:
   ```bash
   docker-compose up -d
   ```
3. Run the database migrations and seed synthetic data:
   ```bash
   npm run db:migrate
   npm run db:seed
   ```

### Running the Server
Start the MCP server in development mode:
```bash
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:
```bash
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.