PostEx MCP Server

PostEx MCP 服务

此项目实现了一个模型上下文协议（MCP）服务，提供用于与 PostEx Merchant API（v4.1.9）各个端点交互的工具。

先决条件

• Node.js（建议使用 LTS 版本）
• npm 或 yarn
• 有效的 PostEx Merchant API Token

设置

1. 克隆仓库（如适用），或确保你拥有 index.js 文件。
2. 安装依赖项：

   npm install @modelcontextprotocol/sdk zod node-fetch@2 # Use v2 for require syntax compatibility
   # or
   yarn add @modelcontextprotocol/sdk zod node-fetch@2
   

3. 从 PostEx 商家账户或代表处获取 PostEx API Token。

运行服务

使用 Node.js 执行服务，并将 PostEx API token 作为命令行参数提供：

node index.js <YOUR_POSTEX_API_TOKEN>

将 <YOUR_POSTEX_API_TOKEN> 替换为你的实际 token。

服务将通过标准输入/输出连接，并将状态消息记录到标准错误。现在已准备好接收 MCP 请求。

可用工具

服务提供以下工具，对应 PostEx API 端点：

• getOperationalCities：获取 PostEx 开展业务的城市列表。
• getMerchantAddress：获取商家已登记的取件地址。
• createMerchantAddress：为商家创建新的取件地址。
• getOrderTypes：获取支持的订单类型（例如，“Normal”和“Reverse”）。
• createOrder：在 PostEx 系统中创建新订单。
• getUnbookedOrders：列出在指定日期范围内已创建但尚未预约取件的订单。
• trackOrder：使用运单号追踪单个订单。
• trackBulkOrder：使用运单号列表追踪多个订单。（注意：API 文档规定使用 GET，但要求提供请求体；实现按最新代码更改使用 GET，这种方式与请求体配合时可能无法按预期工作。）
• saveShipperAdvice：为已尝试派送的包裹提供建议（例如，重试、退回）。
• getShipperAdvice：获取运单号对应的承运人建议历史记录。
• cancelOrder：使用运单号取消订单。（注意：使用带有 JSON 请求体的 PUT 实现。）
• getPaymentStatus：检查订单的付款结算状态。
• getOrderStatus：获取所有可能的订单状态列表。
• listOrders：列出指定日期范围内的订单，可选择按状态 ID 筛选。

注意： 对应返回 PDF 文件的 API 端点（generate-load-sheet、get-invoice）的工具在此版本中尚未实现。

开发说明

• 服务使用 node-fetch 向 PostEx API 发起 HTTP 请求。
• 使用 zod 对工具参数进行输入验证。
• API token 作为命令行参数安全传递，并在 API 调用的 Authorization 标头中使用。
• 错误处理较为基础；API 调用期间如遇问题，请检查控制台输出。
• 服务会针对 SIGINT 和 SIGTERM 信号执行平稳关闭。