# 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](https://nodejs.org/) (LTS version recommended)
*   [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/)
*   A valid PostEx Merchant API Token

## Setup

1.  **Clone the repository (if applicable) or ensure you have the `index.js` file.**
2.  **Install dependencies:**
    ```bash
    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:

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