Tools Reference

The Aphelios MCP server exposes two tools. Both return data in markdown (default, token-efficient) or JSON format.

list_shipments_summary

Search and filter shipments with pagination. Use this for broad queries like "show me delayed shipments" or "what's arriving at LAX this week".

Parameters

Parameter	Type	Default	Description
search_text	string	null	Partial match on tracking reference
shipment_status	string	null	Filter by status: in_transit, delivered, exception, etc.
eta_after	string	null	ISO 8601 datetime -- shipments arriving after this date
eta_before	string	null	ISO 8601 datetime -- shipments arriving before this date
created_after	string	null	ISO 8601 datetime
created_before	string	null	ISO 8601 datetime
origin_port	string	null	UN/LOCODE (e.g. CNSHA for Shanghai)
destination_port	string	null	UN/LOCODE (e.g. USLAX for Los Angeles)
carrier_code	string	null	SCAC code (e.g. MAEU for Maersk)
last_free_day_within_days	integer	null	Containers with LFD expiring within N days
last_free_day_expired	boolean	null	Containers past their last free day
containers_ready_for_pickup	boolean	null	Containers available for pickup
page	integer	1	Page number
results_per_page	integer	20	Results per page (max: 100)
output_format	string	"markdown"	"markdown" or "json"

Example

{
  "name": "list_shipments_summary",
  "arguments": {
    "shipment_status": "exception",
    "destination_port": "USLAX",
    "results_per_page": 10
  }
}

Response (markdown)

Found 3 shipments (page 1 of 1):

| Tracking # | Status | Carrier | Route | ETA |
|------------|--------|---------|-------|-----|
| MAEU123456789 | exception | Maersk | CNSHA → USLAX | 2026-02-25 |
| CMDU987654321 | exception | CMA CGM | KRPUS → USLAX | 2026-02-27 |
| ONEY111222333 | exception | ONE | JPYOK → USLAX | 2026-03-01 |

---

get_shipment_details

Fetch complete shipment details including containers, tracking events, and milestones. Use this when you have a specific identifier and need the full picture.

At least one identifier parameter is required.

Parameters

Parameter	Type	Default	Description
shipment_ids	string[]	null	Aphelios shipment UUIDs
bills_of_lading	string[]	null	Master bill of lading numbers
air_waybills	string[]	null	Air waybill numbers
container_numbers	string[]	null	Container IDs
output_format	string	"markdown"	"markdown" or "json"

Example

{
  "name": "get_shipment_details",
  "arguments": {
    "bills_of_lading": ["MAEU123456789"]
  }
}

Response (markdown)

## Shipment: MAEU123456789

- **Status:** in_transit
- **Route:** Shanghai (CNSHA) → Los Angeles (USLAX)
- **Carrier:** Maersk (MAEU)
- **ETA:** 2026-02-25 14:30 UTC

### Containers

| Container | Size | Status | Last Free Day |
|-----------|------|--------|---------------|
| MSKU1234567 | 40HC | loaded_on_vessel | 2026-03-05 |

### Tracking Events

| Datetime | Event | Location | Notes |
|----------|-------|----------|-------|
| 2026-02-10 08:00 | DEPARTURE | Shanghai | Vessel departed |
| 2026-02-18 12:30 | IN_TRANSIT | Pacific | Vessel in transit |

### Milestones

| Milestone | Expected | Actual |
|-----------|----------|--------|
| Port of Loading | 2026-02-10 | 2026-02-10 |
| Port of Discharge | 2026-02-25 | -- |

Output formats

Markdown (default)

Token-efficient for LLM consumption. Tables and structured text that models can easily parse without wasting context on JSON syntax.

JSON

Structured format for programmatic consumption:

{
  "data": [...],
  "meta": {
    "total": 3,
    "page": 1,
    "results_per_page": 20,
    "total_pages": 1
  }
}

Use "output_format": "json" when your agent needs to process results programmatically rather than summarize them.