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）在此版本中尚未實現。