Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion MCP_README.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,6 @@ Search for bill of lading 123456789
| `identify_tracking_number` | Predict a number's type and carrier without tracking it |
| `get_container` | Get detailed container information |
| `get_shipment_details` | Get complete shipment routing and containers |
| `get_container_transport_events` | Get full event timeline |
| `get_container_route` | Get ports in route order with ETAs and the current vessel |
| `get_location` | Get a port, terminal, or metro area |
| `get_vessel` | Get a vessel's position and projected arrival |
Expand Down
12 changes: 0 additions & 12 deletions chatgpt-app-submission.json
Original file line number Diff line number Diff line change
Expand Up @@ -56,18 +56,6 @@
"destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
}
},
"get_container_transport_events": {
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
},
"justifications": {
"read_only_justification": "Retrieves the transport-event timeline without changing it.",
"open_world_justification": "Does not publish content or change public or third-party systems.",
"destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
}
},
"get_supported_shipping_lines": {
"annotations": {
"readOnlyHint": true,
Expand Down
1 change: 0 additions & 1 deletion claude-connector-submission.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,6 @@
"tool_names": [
"get_container",
"get_container_route",
"get_container_transport_events",
"get_document",
"get_importer_profile",
"get_location",
Expand Down
3 changes: 1 addition & 2 deletions docs/api-docs/in-depth-guides/mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ Once configured, verify everything works:
<Step title="Ask Claude to list tools">
> "List the tools available in the Terminal49 MCP server."

Claude should respond with a list of 31 tools including `search_container`, `track_container`, the list tools, and the trade intelligence tools.
Claude should respond with a list of 30 tools including `search_container`, `track_container`, the list tools, and the trade intelligence tools.
</Step>
<Step title="Search for a test container">
> "Using the Terminal49 MCP server, search for container TCLU1234567 and summarize its status."
Expand Down Expand Up @@ -220,7 +220,6 @@ printf '%s\n' \
| `identify_tracking_number` | Predict a number's type and carrier, and check whether it is already tracked, without tracking it | `number: string` |
| `get_container` | Get container with optional includes | `id: uuid`, `include?: ['shipment', 'pod_terminal', 'transport_events', 'custom_fields', 'party_roles']` |
| `get_shipment_details` | Get shipment and containers | `id: uuid`, `include_containers?: boolean`, `include_custom_fields?: boolean`, `include_party_roles?: boolean` |
| `get_container_transport_events` | Get event timeline | `id: uuid` |
| `get_supported_shipping_lines` | List carriers with SCAC codes | `search?: string` |
| `get_container_route` | Get ports in route order with ETAs and the current vessel (paid feature) | `id: uuid` |
| `get_location` | Get a port, terminal, or metro area | `kind` (`port`, `terminal`, or `metro_area`), `id` (UUID, or a UN/LOCODE for a port or metro area) |
Expand Down
2 changes: 1 addition & 1 deletion docs/api-docs/useful-info/entitlements.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Some Terminal49 features require account enablement beyond standard API access.
| Read endpoints (`GET /v2/shipments`, `GET /v2/containers`, `GET /v2/tracking_requests/{id}`, and other GETs) | Full API access (paid plan or 7-day API trial) | Open [Developers](https://app.terminal49.com/developers) and click **Start trial** for 7 days with the same 10-active-container limit, or see [Pricing](/api-docs/useful-info/pricing) for ongoing access | `401 Unauthorized` with `You do not have permissions for using the API, except for creating tracking requests. All other permissions require a paid plan. See https://app.terminal49.com/settings/billing`. `POST /v2/tracking_requests` still works. |
| Container Map GeoJSON API (`GET /v2/containers/{id}/map_geojson`) | Routing Data | Contact sales@terminal49.com | `403 Forbidden` with `Routing data feature is not enabled for this account` |
| Vessel endpoints (`GET /v2/vessels/{id}`, IMO lookup, position history, and future positions) | Routing Data | Contact sales@terminal49.com | `403 Forbidden` with `Routing data feature is not enabled for this account`. Vessels outside your actively tracked shipments return `404`. See [Vessel data access](#vessel-data-access). |
| MCP `get_container_route` tool | Routing Data | Contact sales@terminal49.com | The tool returns a feature-not-enabled response; use `get_container_transport_events` for historical milestones |
| MCP `get_container_route` tool | Routing Data | Contact sales@terminal49.com | The tool returns a feature-not-enabled response; use `get_container` (`events.timeline`) for historical milestones |
| Terminal49 Map Embed | Publishable map API key, plus Routing Data for vessel positions | Contact support@terminal49.com | The browser embed cannot authenticate without a valid publishable key. Without Routing Data, vessel requests from the embed return `403`. |
| Tracking Widget Embed | Publishable widget API key | Contact support@terminal49.com | The browser widget cannot authenticate without a valid publishable key |
| Container refresh (`PATCH /v2/containers/{id}/refresh`) | On-demand refresh | Contact sales@terminal49.com | `403 Forbidden`; the endpoint is also rate-limited to 10 requests per minute for entitled accounts |
Expand Down
93 changes: 3 additions & 90 deletions docs/mcp/home.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -302,7 +302,7 @@ Get detailed container information with flexible data loading. Choose what to in
- `include` *(string[], optional)* – what to load:
- `shipment` – routing, BOL, line, ref numbers (lightweight)
- `pod_terminal` – terminal name, location (lightweight)
- `transport_events` – adds `events.count`, `events.rail_events_count`, and `events.latest_event`; use `get_container_transport_events` for the full timeline
- `transport_events` – always loaded: `events.timeline` (every event, oldest first, with vessel, voyage, location, and `reported_at`; withdrawn events carry `invalidated_at`; when estimates conflict, the latest `reported_at` is current) plus the active `events.count` and `events.rail_events_count`
- `custom_fields` – account-defined fields such as PO number or project manager (lightweight; needs a signed-in user, not an API key)
- `party_roles` – companies assigned to the container by role, such as `customer` or `pickup_dray_carrier`. Each row has the party role `id`, `role`, `party_id`, and `party_name`. `party_name` is the company name, else the party's name, else its nickname. If the credential cannot read party roles, `party_roles` is `null` and `party_roles_note` explains why.

Expand Down Expand Up @@ -413,93 +413,6 @@ The response may also include `_metadata` with factual details such as `includes

---

### `get_container_transport_events`

Get the full event timeline for a container's journey. Each event has a `vessel_id`, or `null`, that you can pass to `get_vessel`.

**Parameters**
- `id` *(uuid, required)* – Terminal49 container UUID

<Accordion title="Example response">
```json
{
"total_events": 4,
"event_categories": {
"vessel_events": 4,
"rail_events": 0,
"truck_events": 0,
"terminal_events": 0,
"other_events": 0
},
"timeline": [
{
"event": "container.transport.vessel_loaded",
"timestamp": "2024-12-08T10:30:00.000Z",
"timezone": "Asia/Shanghai",
"voyage_number": "451E",
"location": {
"name": "Shanghai",
"code": "CNSHA",
"type": "port"
}
},
{
"event": "container.transport.vessel_departed",
"timestamp": "2024-12-09T14:00:00.000Z",
"timezone": "Asia/Shanghai",
"voyage_number": "451E",
"location": {
"name": "Shanghai",
"code": "CNSHA",
"type": "port"
}
},
{
"event": "container.transport.vessel_arrived",
"timestamp": "2024-12-22T08:30:00.000Z",
"timezone": "America/Los_Angeles",
"voyage_number": "451E",
"location": {
"name": "Los Angeles",
"code": "USLAX",
"type": "port"
}
},
{
"event": "container.transport.vessel_discharged",
"timestamp": "2024-12-23T11:15:00.000Z",
"timezone": "America/Los_Angeles",
"voyage_number": "451E",
"location": {
"name": "Los Angeles",
"code": "USLAX",
"type": "port"
}
}
],
"milestones": {
"vessel_loaded_at": "2024-12-08T10:30:00.000Z",
"vessel_departed_at": "2024-12-09T14:00:00.000Z",
"vessel_arrived_at": "2024-12-22T08:30:00.000Z",
"discharged_at": "2024-12-23T11:15:00.000Z"
},
"_metadata": {
"source": "transport_events_subresource",
"container_found": true
}
}
```
</Accordion>

**Good for**
- "Show me the journey timeline"
- "What happened to this container?"
- "How long was the rail portion?"

**REST equivalent**: [GET /containers/{id}/transport_events](/api-docs/api-reference/containers/get-a-containers-transport-events)

---

### `get_shipment_details`

Get shipment-level information including routing, BOL, and all containers.
Expand Down Expand Up @@ -546,7 +459,7 @@ The tool returns:
If Terminal49 has no route data for the container yet, the tool returns a `NoRouteData` result with a suggested alternative instead of an error.

<Warning>
This is a **paid feature**. If it is not enabled for your account, the tool returns a `FeatureNotEnabled` result. Use `get_container_transport_events` for historical movement data instead.
This is a **paid feature**. If it is not enabled for your account, the tool returns a `FeatureNotEnabled` result. Use `get_container`, whose `events.timeline` has the historical movement, instead.

See [Entitlements and Paid Features](/api-docs/useful-info/entitlements) for the related Routing Data entitlement.
</Warning>
Expand Down Expand Up @@ -818,7 +731,7 @@ Get a port, terminal, or metro area.
Get a vessel's name, IMO, MMSI, and last reported position. Optionally project its track to a port and estimate when it arrives.

**Parameters**
- `id` *(uuid, required)* – vessel UUID, such as `vessel_id` from `get_container_transport_events`
- `id` *(uuid, required)* – vessel UUID, such as a `vessel_id` from `get_container`'s `events.timeline`
- `eta_to` *(object, optional)* – project the track to a port:
- `port_id` *(uuid, required)* – the port the vessel is heading to
- `previous_port_id` *(uuid, required)* – the port it left before that
Expand Down
4 changes: 4 additions & 0 deletions packages/mcp/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]

### Changed
- `get_container` always returns every transport event in `events.timeline` (oldest first, with vessel, voyage, location, `invalidated_at`, and `reported_at`), instead of a count and the event with the largest timestamp. That event was often a far-out estimate on another voyage, so agents quoted a stale ETA. `events.latest_event` is gone; `include: ["transport_events"]` is accepted and changes nothing. When estimates for the same milestone conflict, the one with the latest `reported_at` is current.
- `set_party_role` and `set_custom_field` are tier C tools that ask for the user's approval only when a record in the call would lose a party or a value. `add`, a `replace` that detaches nobody, and filling empty fields run at once. `remove`, a `replace` that detaches another party, and overwriting or clearing a value return one preview of every record that changes in the batch, and write after the user approves it on either confirmation channel. The approval is bound to the state of every record read, so a change to any of them re-asks. A `remove` whose `party_id` matches no role while the record holds another party in that role fails with guidance instead of reporting `unchanged`; a `party_id` Terminal49 does not know stops the call as `party_not_found`.

### Removed
- `get_container_transport_events`. `get_container` returns the same timeline in `events.timeline`.

### Added
- Tier C write tools (`stop_shipment_tracking`, `cancel_tracking_request`) confirm with the user through MCP 2026-07-28 form elicitation when the request declares it: the first call returns `input_required` with the preview and a signed `requestState`, the client asks the user, and the write runs only on their accept. A `confirmation_token` on such a request is refused (`token_not_accepted`), and a decline returns `status: "declined"`. Other clients keep the preview-then-token flow. Tier C tools now carry `_meta["anthropic/requiresUserInteraction"]: true`, so Claude Code prompts on every call.
- Trade intelligence tools for US ocean import market data (US Customs bill-of-lading records, January 2022 onward): `search_importers`, `get_importer_profile`, `search_commodities`, `rank_importers`, `get_trade_trends`, `get_trade_breakdown`, and `get_trade_data_coverage`. All are read-only and gated per account; without the feature they reply that trade intelligence isn't enabled instead of failing. Responses are compacted (rounded numbers, capped lists, internal fields dropped), and the tool descriptions and server instructions carry the data caveats agents need. Record-level container and bill of lading lookups stay out of MCP.
Expand Down
3 changes: 1 addition & 2 deletions packages/mcp/DIRECTORY_PREFLIGHT.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,7 @@ ChatGPT directory.
Each known failure must identify its cause and next action; do not wrap
non-retryable failures in a generic retry message.
- [ ] Confirm `track_container.number` is required and `get_container`
`transport_events` returns only event counts plus the latest event. Use
`get_container_transport_events` for full history.
always returns the full `events.timeline`, each event with `reported_at`.
- [ ] Recheck the [privacy policy](https://terminal49.com/privacy) and MCP data
practices: tools access the authenticated private account, use only tool
arguments, and only `track_container`, `set_party_role`, and
Expand Down
3 changes: 1 addition & 2 deletions packages/mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@

## 📦 What's Included

### 🛠️ Tools (34 Available)
### 🛠️ Tools (33 Available)

The default toolsets, `core`, `documents`, `operations` and `trade`, serve these 31:

Expand All @@ -28,7 +28,6 @@ The default toolsets, `core`, `documents`, `operations` and `trade`, serve these
| **`identify_tracking_number`** | Predict a number's type and carrier and check whether it is already tracked | Creates nothing |
| **`get_container`** | Get detailed container info with flexible data loading | Optional custom fields and party roles |
| **`get_shipment_details`** | Get shipment routing, BOL, containers, ports | Optional custom fields and party roles |
| **`get_container_transport_events`** | Get full event timeline for a container | Milestone history |
| **`get_supported_shipping_lines`** | List 40+ major carriers with SCAC codes | Filterable by name/code |
| **`get_container_route`** | Get ports in route order with ETAs and the current vessel | Premium feature |
| **`get_location`** | Get a port, terminal, or metro area | FIRMS code, address, time zone |
Expand Down
Loading
Loading