Postex MCP Server

🚀 PostEx MCP Server

This project implements a Model Context Protocol (MCP) server, offering tools to interact with various endpoints of the PostEx Merchant API (v4.1.9).

🚀 Quick Start

Prerequisites

• Node.js (LTS version recommended)
• npm or yarn
• A valid PostEx Merchant API token

Installation

1. Clone the repository (if applicable) or ensure you have the index.js file.
2. Install dependencies:

   npm install @modelcontextprotocol/sdk zod node-fetch@2 # Use v2 for require syntax compatibility
   # Or
   yarn add @modelcontextprotocol/sdk zod node-fetch@2
   

3. Obtain your PostEx API token from your PostEx merchant account or representative.

Running the Server

Execute the server using Node.js, providing your PostEx API token as a command-line argument:

node index.js <YOUR_POSTEX_API_TOKEN>

Replace <YOUR_POSTEX_API_TOKEN> with your actual token.

The server will connect via standard I/O and log status messages to standard error. It is now ready to receive MCP requests.

✨ Features

The server exposes the following tools, corresponding to endpoints of the PostEx API:

• getOperationalCities: Retrieve the list of cities where PostEx operates.
• getMerchantAddress: Get the registered pickup address of the merchant.
• createMerchantAddress: Create a new pickup address for the merchant.
• getOrderTypes: Get the supported order types (e.g., "normal", "reverse").
• createOrder: Create a new order in the PostEx system.
• getUnbookedOrders: List orders that have not been booked for pickup within a specified date range.
• trackOrder: Track a single order using its tracking number.
• trackBulkOrder: Track multiple orders using a list of tracking numbers. (Note: The API documentation specifies GET but requires a body; the implementation uses GET as per the latest code change, which may not match expectations).
• saveShipperAdvice: Provide advice (e.g., retry, return) for attempted packages.
• getShipperAdvice: Retrieve the captain's advice history for a tracking number.
• cancelOrder: Cancel an order using its tracking number. (Note: Implemented as PUT with a JSON body).
• getPaymentStatus: Check the settlement payment status of an order.
• getOrderStatus: Get the list of all possible order statuses.
• listOrders: List orders within a specified date range, optionally filtered by status ID.

⚠️ Important Note

Tools that return PDF files, such as generating a load sheet (generate-load-sheet) and getting an invoice (get-invoice), are not implemented in this version.