商户API协议服务器

PostEx MCP服务器

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

先决条件

• Node.js （推荐LTS版本）
• npm 或 纱线
• 有效的PostEx商户API代币

设置

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 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：使用订单的跟踪号取消订单。（注意：实现为带有JSON正文的PUT）。
• getPaymentStatus：检查订单的付款结算状态。
• getOrderStatus：获取所有可能订单状态的列表。
• listOrders：列出日期范围内的订单，可选择按状态ID筛选。

注： 与返回PDF文件的API端点对应的工具(generate-load-sheet, get-invoice)在此版本中未实现。

开发说明

• 服务器使用 node-fetch 用于向PostEx API发出HTTP请求。
• zod 用于工具参数的输入验证。
• API令牌作为命令行参数安全传递，并在 Authorization API调用的头。
• 错误处理是基本的；在API调用期间检查控制台输出是否存在潜在问题。
• 妥善处理停机 SIGINT 和 SIGTERM 信号。