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

Replace `` 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.