100kgforest/sf-express-mcp-server

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:

git clone https://github.com/100kgforest/sf-express-mcp-server.git
cd sf-express-mcp-server

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env

Edit .env and fill in your SF Express API credentials:

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:

npm run build

Usage

Running the MCP Server

Start the server directly:

npm start

Or run in development mode:

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

{
  "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):

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "serviceType": "warehouse",
  "locationCode": "010",
  "requirements": {
    "storageType": "general",
    "capacity": 1000
  }
}

Error Handling

The server provides comprehensive error handling with structured error responses:

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

npm run build

Development Mode

npm run dev

Linting

npm run lint

Configuration

Environment variables:

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:

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.