README.md•6.45 kB
# 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