MCP Shipping Control Center

A comprehensive shipping and order management platform built with the Model Context Protocol (MCP), integrating EasyPost shipping services and Veeqo order management.

🚀 Features

Core Functionality

• Order Management: Create, update, and track orders through Veeqo integration
• Shipping Management: Generate labels, track shipments, and manage rates via EasyPost
• Unified Workflows: Cross-platform operations combining order and shipping data
• Real-time Dashboard: Web-based interface for monitoring operations
• Authentication: JWT-based security with role-based access control

Technical Features

• MCP Protocol: JSON-RPC 2.0 compliant API
• TypeScript: Full type safety throughout the application
• Error Handling: Comprehensive error management with retry logic
• Logging: Structured logging with correlation IDs
• Testing: Complete test coverage for all components
• Docker: Containerized deployment ready
• Kubernetes: Production-ready orchestration

📁 Project Structure

mcp-server/
├── src/
│   ├── clients/           # API client implementations
│   │   ├── easypostClient.ts
│   │   └── veeqoClient.ts
│   ├── methods/           # MCP method implementations
│   │   ├── easypost.ts
│   │   ├── veeqo.ts
│   │   ├── unified.ts
│   │   └── web.ts
│   ├── utils/             # Utility functions
│   │   ├── auth.ts
│   │   ├── errors.ts
│   │   ├── logger.ts
│   │   ├── middleware.ts
│   │   └── retry.ts
│   ├── web/               # Web interface components
│   │   ├── components/
│   │   ├── pages/
│   │   ├── services/
│   │   └── types/
│   ├── server.ts          # Main server implementation
│   └── schema.ts          # JSON-RPC schemas
├── tests/                 # Test suites
├── k8s/                   # Kubernetes manifests
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md

🛠️ Installation

Prerequisites

• Node.js 18+
• npm or pnpm
• Docker (optional)
• Kubernetes cluster (optional)

Setup

1. Clone and install dependencies:

cd mcp-server
npm install
# or
pnpm install

2. Environment configuration:

cp .env.example .env
# Edit .env with your API keys and configuration

3. Required environment variables:

# API Keys
EASYPOST_API_KEY=your_easypost_api_key
VEEQO_API_KEY=your_veeqo_api_key

# JWT Configuration
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=24h

# Default Admin User
DEFAULT_ADMIN_PASSWORD=admin123

# Logging
LOG_LEVEL=info

🚀 Usage

Development

# Start the development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

Production

# Using Docker
docker build -t mcp-server .
docker run -p 3000:3000 mcp-server

# Using Docker Compose
docker-compose up -d

# Using Kubernetes
kubectl apply -f k8s/

📡 API Reference

MCP Methods

Veeqo Methods

• veeqo.createOrder - Create a new order
• veeqo.getOrder - Retrieve order details
• veeqo.listOrders - List orders with pagination
• veeqo.updateOrder - Update existing order
• veeqo.deleteOrder - Delete an order
• veeqo.syncInventory - Sync inventory data

EasyPost Methods

• easypost.createShipment - Create a new shipment
• easypost.getRates - Get shipping rates
• easypost.buyLabel - Purchase shipping label
• easypost.trackShipment - Track shipment status

Unified Methods

• unified.createOrderWithShipping - Create order and shipping in one operation
• unified.processReturn - Handle return processing
• unified.bulkOperations - Batch operations

Web Methods

• web.login - User authentication
• web.getDashboardStats - Dashboard statistics
• web.searchOrders - Search orders

Example Request

{
  "jsonrpc": "2.0",
  "method": "veeqo.createOrder",
  "params": {
    "order": {
      "line_items_attributes": [
        {
          "product_id": "123",
          "quantity": 2
        }
      ],
      "deliver_to": {
        "first_name": "John",
        "last_name": "Doe",
        "address1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      }
    }
  },
  "id": 1
}

🔧 Configuration

Docker Configuration

The application includes Docker and Docker Compose configurations for easy deployment:

• Dockerfile: Multi-stage build for production optimization
• docker-compose.yml: Complete stack with all services
• k8s/: Kubernetes manifests for production deployment

Monitoring

• Prometheus: Metrics collection and monitoring
• Structured Logging: JSON-formatted logs with correlation IDs
• Health Checks: Built-in health check endpoints

🧪 Testing

# Run all tests
npm test

# Run specific test suites
npm test -- --testNamePattern="EasyPost"
npm test -- --testNamePattern="Veeqo"
npm test -- --testNamePattern="Unified"

# Run with coverage
npm run test:coverage

📊 Monitoring

The application includes comprehensive monitoring:

• Metrics: Prometheus metrics for all operations
• Logging: Structured logging with correlation IDs
• Health Checks: Built-in health check endpoints
• Error Tracking: Comprehensive error handling and reporting

🔒 Security

• JWT Authentication: Secure token-based authentication
• Role-based Access: Admin and user role permissions
• Input Validation: Comprehensive input validation
• Rate Limiting: Built-in rate limiting protection
• CORS: Configurable CORS policies

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Check the documentation
• Review the test examples

🔄 Version History

• v1.0.0 - Initial release with core functionality
• Complete MCP server implementation
• EasyPost and Veeqo integrations
• Web dashboard interface
• Docker and Kubernetes deployment ready