PostEx MCP 服务器

本项目实现了一个模型上下文协议 (MCP) 服务器，该服务器提供与 PostEx 商户 API (v4.1.9) 的各种端点交互的工具。

前提条件

• Node.js (推荐 LTS 版本)
• npm 或 yarn
• 有效的 PostEx 商户 API Token

设置

1. 克隆存储库（如果适用）或确保您拥有 index.js 文件。
2. 安装依赖项：

   npm install @modelcontextprotocol/sdk zod node-fetch@2 # 使用 v2 以兼容 require 语法
   # 或
   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。

服务器将通过标准 I/O 连接，并将状态消息记录到标准错误输出。 现在可以接收 MCP 请求了。

可用工具

服务器公开了以下工具，对应于 PostEx API 端点：

• getOperationalCities: 获取 PostEx 运营的城市列表。
• getMerchantAddress: 获取商户注册的取件地址。
• createMerchantAddress: 为商户创建一个新的取件地址。
• getOrderTypes: 获取支持的订单类型（例如，“Normal”，“Reverse”）。
• createOrder: 在 PostEx 系统中创建一个新订单。
• getUnbookedOrders: 列出已创建但尚未在日期范围内预订取件的订单。
• trackOrder: 使用跟踪号跟踪单个订单。
• trackBulkOrder: 使用跟踪号列表跟踪多个订单。（注意：API 文档指定 GET，但需要 body；实现按照最新的代码更改使用 GET，这可能无法按预期与 body 一起使用）。
• saveShipperAdvice: 为尝试过的包裹提供建议（例如，重试，退回）。
• getShipperAdvice: 检索跟踪号的托运人建议历史记录。
• cancelOrder: 使用跟踪号取消订单。（注意：实现为带有 JSON body 的 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 信号。