Commerce Operations MCP Server

AI-native solution for commerce operations teams to independently investigate and resolve order issues, particularly refund processing.

Problem Statement

Operations teams in e-commerce businesses frequently depend on engineers to:

• Investigate order issues across multiple systems
• Determine refund eligibility
• Process refunds safely without risking duplicate refunds or fraud

This MCP server makes ops teams more independent by providing AI agents with safe, structured access to commerce operations.

Solution Overview

An MCP server that exposes commerce operations tools for AI agents:

1. Order Investigation: Search and retrieve order details
2. Refund Eligibility: Check if orders qualify for refunds based on business rules
3. Safe Refund Processing: Execute refunds with built-in safety checks
4. Audit Trail: Track all refund operations

Architecture

AI Agent (Claude/Gemini)
    ↓
MCP Protocol (stdio/SSE)
    ↓
TypeScript MCP Server
    ↓
SQLite Database (mock commerce data)

Key Design Decisions

MCP as Core Architecture: The MCP server is the primary interface for all operations. It's not a wrapper - it implements:

• Business logic for refund eligibility
• Safety checks and validation
• Audit logging
• Transactional integrity

Tool Design: Five focused tools that map to real operations workflows:

• search_orders - Find orders by various criteria
• get_order_details - Retrieve complete order information
• check_refund_eligibility - Validate refund eligibility before processing
• process_refund - Execute refund with safety checks
• get_refund_history - Audit trail for refunds

Safety First:

• Prevents duplicate refunds
• Validates refund amounts don't exceed order total
• Enforces 90-day refund window
• Requires detailed reasons (audit trail)
• Read-only tools for investigation, single destructive tool with guards

Setup

Prerequisites

• Node.js 18+
• npm or yarn

Installation

npm install
npm run build

Running Locally

npm run dev

The server runs on stdio and communicates via MCP protocol.

Running Tests

npm run build
node dist/test.js

Tests verify:

• Order search and retrieval
• Refund eligibility rules
• Refund processing safety checks
• Multiple partial refunds
• Audit logging

MCP Tools

1. search_orders

Search for orders with filters:

• email: Customer email
• orderId: Specific order ID
• status: Order status (pending, confirmed, shipped, delivered, cancelled)
• paymentStatus: Payment status (pending, paid, failed, refunded, partially_refunded)

2. get_order_details

Retrieve complete order information including items, shipping, payment, and refund history.

Input: orderId

3. check_refund_eligibility

Validate if an order qualifies for refund.

Business Rules:

• Payment must be completed (paid status)
• Not already fully refunded
• Within 90 days of purchase
• Returns max refundable amount

Input: orderId

4. process_refund

Execute a refund with safety checks.

Safety Checks:

• Validates eligibility first
• Prevents duplicate full refunds
• Prevents excess refunds
• Requires detailed reason (min 10 characters)
• Creates audit log

Input:

• orderId: Order to refund
• amount: Refund amount (supports partial refunds)
• reason: Detailed reason for audit trail

5. get_refund_history

Retrieve all refund transactions for an order.

Input: orderId

Example Workflow

Scenario: Customer reports they received a damaged laptop

1. Search for customer orders:

   search_orders({ email: "alice@example.com" })
   

2. Get order details:

   get_order_details({ orderId: "ORD-2024-001" })
   

3. Check refund eligibility:

   check_refund_eligibility({ orderId: "ORD-2024-001" })
   

4. Process refund (if eligible):

   process_refund({ 
     orderId: "ORD-2024-001",
     amount: 1299.99,
     reason: "Customer received damaged laptop, verified with photos"
   })
   

5. Verify refund:

   get_refund_history({ orderId: "ORD-2024-001" })
   

Deployment

Railway Deployment

1. Create Railway project:

   railway init
   

2. Add start command to Procfile or use npm start

3. Deploy:

   railway up
   

4. Expose via SSE transport for remote access

Environment Variables

For production deployment:

• NODE_ENV=production
• PORT - Railway will set automatically

Sample Data

The system includes 6 sample orders with various states:

• Delivered paid orders (eligible for refund)
• Already refunded order (not eligible)
• Pending payment order (not eligible)
• Shipped orders
• Various payment methods

Safety Considerations

Implemented

• ✅ No duplicate full refunds
• ✅ Amount validation (positive, <= remaining)
• ✅ Eligibility checks before processing
• ✅ Audit logging for all refunds
• ✅ Transaction atomicity
• ✅ Required refund reasons

Production Requirements (Out of Scope)

• Authentication/authorization
• Rate limiting
• Fraud detection
• Payment gateway integration
• Multi-currency support
• Role-based access control

Assumptions

1. Data: Using synthetic SQLite data; real systems would connect to production databases via read replicas
2. Payments: Mock refund processing; real systems integrate with Stripe/PayPal/etc.
3. Authentication: Assumes trusted environment; production needs auth
4. Single-tenant: One database; real system would be multi-tenant
5. Business Rules: 90-day refund window is configurable; simplified from real-world policies

Limitations & Future Work

Current Limitations

• No actual payment gateway integration
• No email notifications
• No approval workflows
• Single database (no scaling)
• No fraud detection

Next Steps (Priority Order)

1. Add SSE transport for remote hosting
2. Implement authentication using API keys or OAuth
3. Add approval workflows for refunds over threshold
4. Integrate payment gateway (Stripe API)
5. Add notification system (email customers)
6. Implement rate limiting and fraud detection
7. Add analytics tools (refund metrics, trends)
8. Multi-tenant support with organization isolation

Trade-offs

Why SQLite? Fast to set up, no external dependencies, perfect for demo. Production would use PostgreSQL with read replicas.

Why stdio transport? Simplest MCP transport for initial development. SSE transport needed for remote hosting.

Why synchronous processing? Simpler to implement and test. Production would use async job queues for refunds.

Why embedded business logic? Keeps MCP server as single source of truth. Alternative would be separate service layer.

Tech Stack

• TypeScript - Type safety and better developer experience
• @modelcontextprotocol/sdk - MCP protocol implementation
• better-sqlite3 - Fast embedded database
• zod - Runtime type validation for tool inputs
• Railway/Render - Hosting platform

License

MIT