SF Express MCP Server

顺丰速运MCP服务器

一种模型上下文协议（MCP）服务器，提供与SF Express航运和物流API的集成。此服务器使LLM应用程序能够与SF Express服务交互，以进行订单管理、货物跟踪、路线查询和物流服务。

特性

• 订单管理：使用全面的地址和货物信息创建新的发货订单
• 货物跟踪：使用带有详细路线历史的运单编号或订单ID跟踪包裹
• 路线查询：查找具有定价信息的地点之间的可用运输路线
• 服务咨询：检查各地点之间的服务可用性和限制
• 物流服务：查询仓储、配送、履行和退货服务

支持的顺丰速运API

此MCP服务器连接到以下SF Express API类别：

• 类别1，api分类1：订单创建(EXP_RECE_CREATE_ORDER)
• 第1类，第2类：发货跟踪(EXP_RECE_SEARCH_ORDER_RESP)
• 第1类，第3类：路线查询(EXP_RECE_SEARCH_ROUTES)
• 第1类，第4类：服务咨询(EXP_RECE_SEARCH_SERVICE)
• 第6类，api分类2：物流服务(EXP_RECE_SEARCH_LOGISTICS)

安装

先决条件

• Node.js 18.0.0或更高版本
• SF Express开发者帐户和API证书

设置

1. 克隆或下载此项目：

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

1. 安装依赖项：

npm install

1. 配置环境变量：

cp .env.example .env

编辑 .env 并填写您的SF Express API凭证：

SF_EXPRESS_PARTNER_ID=your_partner_id_here
SF_EXPRESS_REQUEST_ID=your_request_id_here
SF_EXPRESS_CHECK_WORD=your_check_word_here

1. 构建项目：

npm run build

用法

运行MCP服务器

直接启动服务器：

npm start

或者以开发模式运行：

npm run dev

使用Claude Desktop进行配置

将服务器添加到Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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"
      }
    }
  }
}

与npx一起使用

您还可以使用npx运行服务器（发布到npm后）：

npx sf-express-mcp-server

可用工具

1.sf_express_create_order

使用顺丰速运创建新的发货订单。

参数：

• orderId （string）：唯一的客户订单ID
• expressType （string）：服务类型（1-标准，2-次日，3-当日，4-经济，5-国际）
• payMethod （string）：付款方式（1-发送方付款，2-接收方付款，3-第三方付款）
• custId （string）：顺丰速运的客户ID
• consigneeInfo （object）：收件人联系方式和地址信息
• deliverInfo （object）：发件人联系方式和地址信息
• cargo （array）：要装运的物品清单，包括数量和重量
• addedService （数组，可选）：附加服务
• remark （字符串，可选）：特殊说明

例子：

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

跟踪装运状态和路线历史。

参数：

• trackingType （string）：跟踪类型（1-运单编号，2-订单ID）
• trackingNumber （array）：跟踪号列表
• methodType （字符串，可选）：查询方法

例子：

{
  "trackingType": "1",
  "trackingNumber": ["SF1234567890123"]
}

3.sf_express_query_routes

查询可用的运输路线和定价。

参数：

• originCode （string）：起始区号
• destCode （string）：目的地区号
• cargoWeight （数字，可选）：用于定价的货物重量

例子：

{
  "originCode": "010",
  "destCode": "021",
  "cargoWeight": 5.0
}

4.sf_express_service_inquiry

查询不同地点之间的服务可用性。

参数：

• originCode （string）：起始区号
• destCode （string）：目的地区号
• serviceType （字符串，可选）：特定服务类型

例子：

{
  "originCode": "010",
  "destCode": "021"
}

5.sf_express_logistics_services

查询仓储和履行等物流服务。

参数：

• serviceType （string）：服务类型（仓库、配送、履行、退货）
• locationCode （string）：位置代码
• requirements （对象，可选）：具体要求

例子：

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

错误处理

服务器通过结构化错误响应提供全面的错误处理：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": [...],
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

常见错误代码：

• VALIDATION_ERROR：输入参数无效
• AUTHENTICATION_ERROR：API凭据无效
• NETWORK_ERROR：网络连接问题
• SERVICE_ERROR：SF Express API错误
• TIMEOUT_ERROR：请求超时

发展

项目结构

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

建筑

npm run build

发展模式

npm run dev

代码检查

npm run lint

配置

环境变量：

安全说明

• 从不将API凭据提交到版本控制
• 使用环境变量进行敏感配置
• 在生产环境中实施适当的访问控制
• 监控API的使用情况以防止滥用

故障排除

常见问题

1. 认证失败：检查您的API证书
2. 网络超时：增加超时时间或检查网络连接
3. 服务代码无效：确保您使用的是正确的顺丰速运服务代码
4. 速率限制：实施适当的速率限制以避免API限制

调试模式

设置详细日志记录的环境变量：

DEBUG=sf-express-mcp npm start

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

对于SF Express API文档和开发人员支持：

• 开发者门户：https://open.sf-express.com
• API文件：https://open.sf-express.com/Api

对于MCP协议文件：

• MCP规范：https://modelcontextprotocol.io
• SDK文档：https://github.com/modelcontextprotocol

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

请确保所有测试都通过，并遵循现有的代码风格。