# 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:**
```bash
cd mcp-server
npm install
# or
pnpm install
```

2. **Environment configuration:**
```bash
cp .env.example .env
# Edit .env with your API keys and configuration
```

3. **Required environment variables:**
```env
# 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

```bash
# Start the development server
npm run dev

# Run tests
npm test

# Build for production
npm run build
```

### Production

```bash
# 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

```json
{
  "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

```bash
# 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