PostEx MCP Server

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.