From 7a2c52f992d54446316c1fc07e0d665c08e4c786 Mon Sep 17 00:00:00 2001 From: Akshay Dodeja Date: Wed, 22 Jul 2026 14:11:03 -0700 Subject: [PATCH 1/2] refactor: rename skill terminal49-mcp to container-tracking The skill name should describe the capability, not the transport, and the plugin namespace already carries the Terminal49 branding. Renamed before first publish so nothing user-visible breaks. Co-Authored-By: Claude Fable 5 --- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- README.md | 4 ++-- plugins/terminal49/README.md | 2 +- .../skills/{terminal49-mcp => container-tracking}/SKILL.md | 2 +- scripts/validate.mjs | 4 ++-- 6 files changed, 8 insertions(+), 8 deletions(-) rename plugins/terminal49/skills/{terminal49-mcp => container-tracking}/SKILL.md (99%) diff --git a/AGENTS.md b/AGENTS.md index c0fd10e..d35733e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ This is a public, cross-platform plugin marketplace for Terminal49. ## Shared source of truth -- `plugins/terminal49/skills/terminal49-mcp/SKILL.md` is the shared behavioral +- `plugins/terminal49/skills/container-tracking/SKILL.md` is the shared behavioral guidance for all clients. - `plugins/terminal49/.mcp.json` and `plugins/terminal49/mcp.json` are the MCP adapters for Claude/Codex and Cursor respectively. Keep their server entries diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 80a8beb..a222061 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,4 +20,4 @@ Thanks for improving the Terminal49 agent plugins. 4. Test installation in any client affected by the change. Platform-specific behavior belongs in its adapter. Guidance that applies to all -clients belongs in `plugins/terminal49/skills/terminal49-mcp/SKILL.md`. +clients belongs in `plugins/terminal49/skills/container-tracking/SKILL.md`. diff --git a/README.md b/README.md index 1894f16..6f3c9d8 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ This marketplace currently publishes one plugin: ## What the plugin provides - OAuth connection to `https://mcp.terminal49.com` -- A shared `terminal49-mcp` skill for choosing and sequencing MCP tools +- A shared `container-tracking` skill for choosing and sequencing MCP tools - Guidance for status, pickup readiness, holds, ETAs, routes, delays, and demurrage-risk questions - Guardrails around tracking-request creation, credentials, dates, and missing @@ -84,7 +84,7 @@ to the authenticated Terminal49 account. ├── mcp.json # Cursor MCP adapter ├── README.md ├── assets/logo.svg # Referenced by the Cursor manifest - └── skills/terminal49-mcp/SKILL.md + └── skills/container-tracking/SKILL.md ``` The skill is shared. Each platform-specific manifest and MCP file is a thin diff --git a/plugins/terminal49/README.md b/plugins/terminal49/README.md index 83abcde..07b9037 100644 --- a/plugins/terminal49/README.md +++ b/plugins/terminal49/README.md @@ -13,7 +13,7 @@ API keys, access tokens, or one-time codes into chat. ## Included skill -`terminal49-mcp` covers: +`container-tracking` covers: - finding an existing container or shipment from a business identifier - starting a new tracking request when the user intends to do so diff --git a/plugins/terminal49/skills/terminal49-mcp/SKILL.md b/plugins/terminal49/skills/container-tracking/SKILL.md similarity index 99% rename from plugins/terminal49/skills/terminal49-mcp/SKILL.md rename to plugins/terminal49/skills/container-tracking/SKILL.md index f17421d..36bbd63 100644 --- a/plugins/terminal49/skills/terminal49-mcp/SKILL.md +++ b/plugins/terminal49/skills/container-tracking/SKILL.md @@ -1,5 +1,5 @@ --- -name: terminal49-mcp +name: container-tracking description: Use Terminal49 MCP tools to find, track, and investigate ocean container shipments. Use when a user asks about container status, shipment details, pickup readiness, terminal holds, ETAs, transport events, routes, delays, tracking requests, carrier support, or demurrage risk. --- diff --git a/scripts/validate.mjs b/scripts/validate.mjs index 2975eec..7ae705c 100644 --- a/scripts/validate.mjs +++ b/scripts/validate.mjs @@ -15,7 +15,7 @@ const paths = { codexPlugin: "plugins/terminal49/.codex-plugin/plugin.json", mcp: "plugins/terminal49/.mcp.json", cursorMcp: "plugins/terminal49/mcp.json", - skill: "plugins/terminal49/skills/terminal49-mcp/SKILL.md", + skill: "plugins/terminal49/skills/container-tracking/SKILL.md", }; async function readJson(relativePath) { @@ -153,7 +153,7 @@ for (const docPath of ["README.md", "CONTRIBUTING.md", "AGENTS.md", "plugins/ter try { const skill = await readFile(resolve(root, paths.skill), "utf8"); if (!skill.startsWith("---\n")) errors.push("skill must start with YAML frontmatter"); - if (!/^name: terminal49-mcp$/m.test(skill)) errors.push("skill name must be terminal49-mcp"); + if (!/^name: container-tracking$/m.test(skill)) errors.push("skill name must be container-tracking"); if (!/^description: .+$/m.test(skill)) errors.push("skill must have a description"); if (!skill.includes("search_container")) errors.push("skill must explain search_container"); if (!skill.includes("track_container")) errors.push("skill must explain track_container"); From 1bd2be96c9d6c68df6c838864a5fdd830b1fa3b1 Mon Sep 17 00:00:00 2001 From: Akshay Dodeja Date: Wed, 22 Jul 2026 14:14:36 -0700 Subject: [PATCH 2/2] feat: rewrite container-tracking skill for operators - Operator-first framing: bare identifier means status request, plain operational language, lead with what needs attention - State-dependent guidance: which attributes matter at each lifecycle stage from booking through empty return - Risk signals: ETA drift, 3+ day terminal dwell, LFD pressure, active holds, rolls, detention - Pickup-location logic: POD terminal vs inland rail ramp/destination - Fleet queries rank by risk; richer trigger description Co-Authored-By: Claude Fable 5 --- plugins/terminal49/README.md | 8 +- .../skills/container-tracking/SKILL.md | 86 ++++++++++++++++--- 2 files changed, 81 insertions(+), 13 deletions(-) diff --git a/plugins/terminal49/README.md b/plugins/terminal49/README.md index 07b9037..724b195 100644 --- a/plugins/terminal49/README.md +++ b/plugins/terminal49/README.md @@ -13,11 +13,17 @@ API keys, access tokens, or one-time codes into chat. ## Included skill -`container-tracking` covers: +`container-tracking` is written for logistics operators and covers: - finding an existing container or shipment from a business identifier - starting a new tracking request when the user intends to do so - inspecting container, shipment, terminal, event, and route details +- state-dependent answers: which attributes matter at each lifecycle stage, + from booking through empty return +- surfacing risk signals: ETA changes, long terminal dwell, last-free-day + pressure, active holds, rolls, and detention +- determining where pickup happens — the discharge port or an inland rail + destination - querying fleets with filters and pagination - presenting dates, holds, missing information, and paid-feature boundaries diff --git a/plugins/terminal49/skills/container-tracking/SKILL.md b/plugins/terminal49/skills/container-tracking/SKILL.md index 36bbd63..277233d 100644 --- a/plugins/terminal49/skills/container-tracking/SKILL.md +++ b/plugins/terminal49/skills/container-tracking/SKILL.md @@ -1,13 +1,18 @@ --- name: container-tracking -description: Use Terminal49 MCP tools to find, track, and investigate ocean container shipments. Use when a user asks about container status, shipment details, pickup readiness, terminal holds, ETAs, transport events, routes, delays, tracking requests, carrier support, or demurrage risk. +description: Find, track, and investigate ocean container shipments with Terminal49 MCP tools, written for logistics operators. Use when a user provides a container number, bill of lading, booking, or reference number, or asks about container status, location, pickup readiness, terminal holds, last free day, ETAs or ETA changes, dwell time, rail moves, inland destinations, transport events, routes, delays, tracking requests, carrier support, or demurrage and detention risk. --- -# Terminal49 MCP +# Container tracking (Terminal49 MCP) -Use the Terminal49 MCP server for container and shipment questions. Prefer the -smallest tool sequence that answers the question, and preserve the difference -between observed data and inference. +Use the Terminal49 MCP server for container and shipment questions. The user is +usually a logistics operator, not a developer: answer in plain operational +language, lead with what they should do or know, and prefer the smallest tool +sequence that answers the question. Preserve the difference between observed +data and inference. + +A bare identifier with no question ("CAIU1234567", "where is MSCU…") means: +find it and report current status, location, and anything that needs attention. ## Before using tools @@ -57,7 +62,7 @@ reference number. Detail tools require a Terminal49 UUID. | Pickup readiness, terminal availability, holds, or LFD | `search_container`, then `get_container` with `shipment` and `pod_terminal` | | What happened, where it moved, or delay analysis | `search_container`, then `get_container_transport_events` | | Full shipment and its containers | `search_container`, then `get_shipment_details` | -| Multi-leg route, transshipment, vessels, or itinerary | `search_container`, then `get_container_route` | +| Multi-leg route, rail leg, transshipment, or itinerary | `search_container`, then `get_container_route` | | Containers or shipments matching operational filters | `list_containers` or `list_shipments` | | Tracking-request status or audit | `list_tracking_requests` | | Supported carrier or SCAC lookup | `get_supported_shipping_lines` | @@ -66,6 +71,57 @@ Use the `terminal49://docs/mcp-query-guidance` resource when available for the server's current intent-to-tool playbooks. Use `terminal49://docs/milestone-glossary` when event terminology needs explanation. +## What matters at each state + +Which attributes are worth reporting depends on where the container is in its +lifecycle. Lead with the fields for the current state; skip fields that are not +yet meaningful. + +| State | Lead with | +| --- | --- | +| Booked, before departure | ETD, POL, vessel and voyage, whether carrier data has started flowing | +| On the water | POD ETA and any change to it, current vessel, transshipment ports | +| Arrived at POD, not yet discharged | Actual arrival vs the last ETA, discharge status, holds already visible | +| Discharged at the POD terminal | Availability, holds, last free day, days since discharge, terminal name | +| Moving inland by rail | Rail departure and arrival events, destination ramp and its ETA, that pickup happens inland | +| Available for pickup | Pickup location, LFD and remaining free days, confirmation that holds are cleared | +| Picked up (full out) | Delivery status, empty-return deadline, whether the empty has been returned | + +## Risk signals to surface + +Check for these whenever the data is already in hand, and lead the answer with +any that apply — even if the user only asked "where is it": + +- **ETA change** — the current ETA differs from earlier estimates in the + transport events. Report old vs new and the cumulative drift. +- **Long dwell** — discharged 3 or more days ago and not picked up. State the + day count; treat it as urgent when the LFD is past or unknown. +- **LFD pressure** — last free day is today, tomorrow, or past. This outranks + everything else in the summary. +- **Active holds** — customs, freight, or terminal holds block pickup even when + the container shows as available. Name each hold type. +- **Rolled or transshipped** — events show discharge and reload at an + intermediate port, or the vessel changed mid-route. +- **Detention risk** — picked up but the empty has not been returned and the + return deadline is near or past. + +Label anything inferred (for example, dwell computed from a discharge date) as +computed, and never present a risk as a confirmed charge. + +## Where pickup happens + +Do not assume pickup is at the port of discharge. Check the shipment +destination and route: + +- If the shipment has an inland destination or the route/events show a rail + leg, pickup happens at the inland ramp or destination terminal — report that + location and the rail arrival ETA, not the POD availability. +- If the container terminates at the POD, use `pod_terminal` data for + availability, holds, and LFD. +- When it is unclear which applies, say so and check + `get_container_route` or the transport events for rail milestones before + answering. + ## Efficient detail loading For `get_container`, request only the related data needed: @@ -88,10 +144,13 @@ leaves a material question unanswered. and `updated_after` in ISO 8601 form. - Use pagination instead of silently assuming the first page is complete. - State the filters and time boundary used in the answer. +- For "what needs attention" requests, rank results by the risk signals above: + LFD pressure first, then holds, then dwell, then ETA changes. ## Interpret and present results -1. Lead with the current answer: status, location, readiness, or risk. +1. Lead with the operational answer: status, location, readiness, or risk — + then supporting detail. 2. Separate actual timestamps from estimated timestamps and label each clearly. 3. Preserve source time zones. If converting a time, state the target time zone. 4. Call out terminal holds, customs issues, and pickup blockers explicitly. @@ -110,8 +169,10 @@ leaves a material question unanswered. 1. Resolve the identifier with `search_container`. 2. Call `get_container` with `shipment` and `pod_terminal`. -3. Summarize current status, terminal, availability, holds, and relevant dates. -4. If the state is unclear, call `get_container_transport_events` for context. +3. Determine the lifecycle state and where pickup happens (POD or inland). +4. Summarize status, location, availability, holds, relevant dates, and any + risk signals. +5. If the state is unclear, call `get_container_transport_events` for context. ### Delay investigation @@ -124,8 +185,9 @@ leaves a material question unanswered. ### Demurrage-risk review 1. Use `list_containers` with the narrowest known operational filters. -2. Fetch `get_container` with `pod_terminal` for the candidates that need detail. -3. Prioritize known pickup LFDs, active terminal holds, discharge state, and - availability. +2. Fetch `get_container` with `pod_terminal` for the candidates that need + detail. +3. Prioritize known pickup LFDs, active terminal holds, discharge state, + availability, and dwell days since discharge. 4. Do not calculate fees unless the required tariff and timing inputs are present. Label any risk assessment separately from an actual charge.