PostEx-MCP-Server

PostEx-MCP-Server

0
developer_toolscommunication

The PostEx MCP Server is designed to manage interactions with PostEx Merchant API by providing endpoint tools for managing orders, addresses, and tracking. It requires Node.js and an API token for setup.

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.