# SF Express MCP Server
A Model Context Protocol (MCP) server that provides integration with SF Express shipping and logistics APIs. This server enables LLM applications to interact with SF Express services for order management, shipment tracking, route queries, and logistics services.
## Features
- **Order Management**: Create new shipping orders with comprehensive address and cargo information
- **Shipment Tracking**: Track packages using waybill numbers or order IDs with detailed route history
- **Route Queries**: Find available shipping routes between locations with pricing information
- **Service Inquiry**: Check service availability and restrictions between locations
- **Logistics Services**: Query warehousing, distribution, fulfillment, and return services
## Supported SF Express APIs
This MCP server connects to the following SF Express API categories:
- **Category 1, apiClassify 1**: Order Creation (`EXP_RECE_CREATE_ORDER`)
- **Category 1, apiClassify 2**: Shipment Tracking (`EXP_RECE_SEARCH_ORDER_RESP`)
- **Category 1, apiClassify 3**: Route Queries (`EXP_RECE_SEARCH_ROUTES`)
- **Category 1, apiClassify 4**: Service Inquiry (`EXP_RECE_SEARCH_SERVICE`)
- **Category 6, apiClassify 2**: Logistics Services (`EXP_RECE_SEARCH_LOGISTICS`)
## Installation
### Prerequisites
- Node.js 18.0.0 or higher
- SF Express developer account and API credentials
### Setup
1. Clone or download this project:
```bash
git clone https://github.com/100kgforest/sf-express-mcp-server.git
cd sf-express-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Configure environment variables:
```bash
cp .env.example .env
```
Edit `.env` and fill in your SF Express API credentials:
```env
SF_EXPRESS_PARTNER_ID=your_partner_id_here
SF_EXPRESS_REQUEST_ID=your_request_id_here
SF_EXPRESS_CHECK_WORD=your_check_word_here
```
4. Build the project:
```bash
npm run build
```
## Usage
### Running the MCP Server
Start the server directly:
```bash
npm start
```
Or run in development mode:
```bash
npm run dev
```
### Configuring with Claude Desktop
Add the server to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"sf-express": {
"command": "node",
"args": ["/path/to/sf-express-mcp-server/dist/index.js"],
"env": {
"SF_EXPRESS_PARTNER_ID": "your_partner_id",
"SF_EXPRESS_REQUEST_ID": "your_request_id",
"SF_EXPRESS_CHECK_WORD": "your_check_word"
}
}
}
}
```
### Using with npx
You can also run the server using npx (after publishing to npm):
```bash
npx sf-express-mcp-server
```
## Available Tools
### 1. sf_express_create_order
Create a new shipping order with SF Express.
**Parameters:**
- `orderId` (string): Unique customer order ID
- `expressType` (string): Service type (1-Standard, 2-Next Day, 3-Same Day, 4-Economic, 5-International)
- `payMethod` (string): Payment method (1-Sender pays, 2-Receiver pays, 3-Third party pays)
- `custId` (string): Customer ID from SF Express
- `consigneeInfo` (object): Recipient contact and address information
- `deliverInfo` (object): Sender contact and address information
- `cargo` (array): List of items to ship with quantities and weights
- `addedService` (array, optional): Additional services
- `remark` (string, optional): Special instructions
**Example:**
```json
{
"orderId": "ORDER123456",
"expressType": "1",
"payMethod": "1",
"custId": "CUST001",
"consigneeInfo": {
"contact": {
"contact": "张三",
"tel": "13800138000",
"company": "ABC公司"
},
"address": {
"province": "广东省",
"city": "深圳市",
"county": "南山区",
"address": "科技园南区深南大道10000号"
}
},
"deliverInfo": {
"contact": {
"contact": "李四",
"tel": "13900139000",
"company": "XYZ公司"
},
"address": {
"province": "北京市",
"city": "北京市",
"county": "朝阳区",
"address": "建国门外大街1号"
}
},
"cargo": [
{
"name": "电子产品",
"count": 1,
"weight": 2.5,
"amount": 1000
}
]
}
```
### 2. sf_express_track_shipment
Track shipment status and route history.
**Parameters:**
- `trackingType` (string): Type of tracking (1-waybill number, 2-order ID)
- `trackingNumber` (array): List of tracking numbers
- `methodType` (string, optional): Query method
**Example:**
```json
{
"trackingType": "1",
"trackingNumber": ["SF1234567890123"]
}
```
### 3. sf_express_query_routes
Query available shipping routes and pricing.
**Parameters:**
- `originCode` (string): Origin area code
- `destCode` (string): Destination area code
- `cargoWeight` (number, optional): Cargo weight for pricing
**Example:**
```json
{
"originCode": "010",
"destCode": "021",
"cargoWeight": 5.0
}
```
### 4. sf_express_service_inquiry
Inquire about service availability between locations.
**Parameters:**
- `originCode` (string): Origin area code
- `destCode` (string): Destination area code
- `serviceType` (string, optional): Specific service type
**Example:**
```json
{
"originCode": "010",
"destCode": "021"
}
```
### 5. sf_express_logistics_services
Query logistics services like warehousing and fulfillment.
**Parameters:**
- `serviceType` (string): Service type (warehouse, distribution, fulfillment, return)
- `locationCode` (string): Location code
- `requirements` (object, optional): Specific requirements
**Example:**
```json
{
"serviceType": "warehouse",
"locationCode": "010",
"requirements": {
"storageType": "general",
"capacity": 1000
}
}
```
## Error Handling
The server provides comprehensive error handling with structured error responses:
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input parameters",
"details": [...],
"timestamp": "2024-01-01T00:00:00.000Z"
}
}
```
Common error codes:
- `VALIDATION_ERROR`: Invalid input parameters
- `AUTHENTICATION_ERROR`: Invalid API credentials
- `NETWORK_ERROR`: Network connectivity issues
- `SERVICE_ERROR`: SF Express API errors
- `TIMEOUT_ERROR`: Request timeout
## Development
### Project Structure
```
src/
├── index.ts # Main MCP server entry point
├── sf-express-client.ts # SF Express API client
├── types.ts # TypeScript type definitions
└── tools/ # MCP tool implementations
├── create-order.ts
├── track-shipment.ts
├── query-routes.ts
├── service-inquiry.ts
└── logistics-services.ts
```
### Building
```bash
npm run build
```
### Development Mode
```bash
npm run dev
```
### Linting
```bash
npm run lint
```
## Configuration
Environment variables:
| Variable | Required | Description |
|----------|----------|-------------|
| `SF_EXPRESS_API_URL` | No | API base URL (default: https://open.sf-express.com) |
| `SF_EXPRESS_PARTNER_ID` | Yes | Your SF Express Partner ID |
| `SF_EXPRESS_REQUEST_ID` | Yes | Your SF Express Request ID |
| `SF_EXPRESS_CHECK_WORD` | Yes | Your SF Express Check Word |
| `SF_EXPRESS_TIMEOUT` | No | Request timeout in milliseconds (default: 30000) |
## Security Notes
- Never commit API credentials to version control
- Use environment variables for sensitive configuration
- Implement proper access controls in production environments
- Monitor API usage to prevent abuse
## Troubleshooting
### Common Issues
1. **Authentication Failed**: Check your API credentials
2. **Network Timeout**: Increase timeout or check network connectivity
3. **Invalid Service Code**: Ensure you're using the correct SF Express service codes
4. **Rate Limiting**: Implement proper rate limiting to avoid API limits
### Debug Mode
Set environment variable for verbose logging:
```bash
DEBUG=sf-express-mcp npm start
```
## License
MIT License - see LICENSE file for details.
## Support
For SF Express API documentation and developer support:
- Developer Portal: https://open.sf-express.com
- API Documentation: https://open.sf-express.com/Api
For MCP protocol documentation:
- MCP Specification: https://modelcontextprotocol.io
- SDK Documentation: https://github.com/modelcontextprotocol
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
Please ensure all tests pass and follow the existing code style.
