PostEx-MCP-Server

🚀 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）在此版本中尚未实现。