PostEx MCP 服务器

该项目实现了一个 Model Context Protocol (MCP) 服务器，提供了与 PostEx 商家 API（v4.1.9）的各种端点交互的工具。

先决条件

• Node.js（推荐使用 LTS 版本）
• npm 或 yarn
• 一个有效的 PostEx 商家 API令牌

设置

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

   npm install @modelcontextprotocol/sdk zod node-fetch@2 # 使用 v2 版本以兼容 require 语法
   # 或者
   yarn add @modelcontextprotocol/sdk zod node-fetch@2
   

3. 获取你的 PostEx API 令牌 从你的 PostEx 商家账户或代表那里。

运行服务器

使用 Node.js 执行服务器，提供你的 PostEx API 令牌作为命令行参数：

node index.js <YOUR_POSTEX_API_TOKEN>

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

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

可用工具

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

• getOperationalCities：获取 PostEx 运营的城市列表。
• getMerchantAddress：获取商家的注册提货地址。
• createMerchantAddress：为商家创建一个新的提货地址。
• getOrderTypes：获取支持的订单类型（例如“正常”、“反向”）。
• createOrder：在 PostEx 系统中创建新订单。
• getUnbookedOrders：列出在指定日期范围内尚未预约提货的订单。
• trackOrder：使用跟踪编号追踪单个订单。
• trackBulkOrder：使用跟踪编号列表追踪多个订单。（注意：API 文档指定为 GET 但需要一个正文；实现中使用 GET 作为最新代码更改，这可能与预期不符）。
• saveShipperAdvice：提供建议（例如重试、退回）针对尝试的包裹。
• getShipperAdvice：检索跟踪编号的船长建议历史记录。
• cancelOrder：使用跟踪编号取消订单。（注意：实现为 PUT 并带有 JSON 正文）。
• getPaymentStatus：检查订单的结算支付状态。
• getOrderStatus：获取所有可能的订单状态列表。
• listOrders：在指定日期范围内列出订单，可选按状态 ID 筛选。

注意： 生成装载单和获取发票等返回 PDF 文件的工具（generate-load-sheet、get-invoice）在此版本中尚未实现。