MCP 服务器

Commerce Operations MCP Server

Enables AI agents to independently investigate and resolve e-commerce order issues, particularly refund processing, with tools for order search, refund eligibility checks, and safe refund execution.

README

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:

Order Investigation: Search and retrieve order details
Refund Eligibility: Check if orders qualify for refunds based on business rules
Safe Refund Processing: Execute refunds with built-in safety checks
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

Search for customer orders:

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

Get order details:

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

Check refund eligibility:

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

Process refund (if eligible):

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

Verify refund:

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

Deployment

Railway Deployment

Create Railway project:
```
railway init
```
Add start command to Procfile or use npm start
Deploy:
```
railway up
```
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

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