PostEx MCP Server

This project implements a Model Context Protocol (MCP) server that provides tools for interacting with various endpoints of the PostEx Merchant API (v4.1.9).

Prerequisites

• Node.js (LTS version recommended)

• npm or yarn

• A valid PostEx Merchant API Token

Setup

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.

Available Tools

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

• getOperationalCities: Get a list of cities where PostEx operates.

• getMerchantAddress: Get the merchant's registered pickup addresses.

• createMerchantAddress: Create a new pickup address for the merchant.

• getOrderTypes: Get the types of orders supported (e.g., "Normal", "Reverse").

• createOrder: Create a new order in the PostEx system.

• getUnbookedOrders: List orders created but not yet booked for pickup within a date range.

• trackOrder: Track a single order using its tracking number.

• trackBulkOrder: Track multiple orders using a list of tracking numbers. (Note: API docs specify GET but require a body; implementation uses GET as per latest code change, which might not work as expected with a body).

• saveShipperAdvice: Provide advice (e.g., retry, return) for an attempted parcel.

• getShipperAdvice: Retrieve shipper 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 payment settlement status for an order.

• getOrderStatus: Get a list of all possible order statuses.

• listOrders: List orders within a date range, optionally filtered by status ID.

Note: Tools corresponding to API endpoints that return PDF files (generate-load-sheet, get-invoice) are not implemented in this version.

Development Notes

• The server uses node-fetch for making HTTP requests to the PostEx API.

• zod is used for input validation for the tool parameters.

• The API token is passed securely as a command-line argument and used in the Authorization header for API calls.

• Error handling is basic; check console output for potential issues during API calls.

• Graceful shutdown is handled for SIGINT and SIGTERM signals.