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
4 changes: 2 additions & 2 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@
},
"metadata": {
"description": "Terminal49 MCP server and agent skills for container tracking and trade intelligence",
"version": "0.3.3"
"version": "0.3.4"
},
"plugins": [
{
"name": "terminal49",
"source": "./plugins/terminal49",
"description": "Container and shipment lookups, starting tracking, and US import trade intelligence from the Terminal49 MCP server, with agent skills",
"version": "0.3.3"
"version": "0.3.4"
}
]
}
4 changes: 2 additions & 2 deletions .cursor-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@
},
"metadata": {
"description": "Terminal49 MCP server and agent skills for container tracking and trade intelligence",
"version": "0.3.3"
"version": "0.3.4"
},
"plugins": [
{
"name": "terminal49",
"source": "./plugins/terminal49",
"description": "Container and shipment lookups, starting tracking, and US import trade intelligence from the Terminal49 MCP server, with agent skills",
"version": "0.3.3"
"version": "0.3.4"
}
]
}
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
.DS_Store
node_modules/
npm-debug.log*
plugins/terminal49/evals/results/
evals/terminal49/results/
.eval-stage/
dist/
7 changes: 6 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,12 @@ files for every release. Keep releases small and document user-visible changes.
- Anthropic's directory reads `plugins/terminal49` from this repository and
publishes each new commit on the tracked branch after its checks. Keep
`plugins/terminal49` free of symbolic links, binary files other than images,
and files over 256 KiB.
and files over 256 KiB. It accepts only Markdown, text, JSON, YAML, and PNG,
JPEG, GIF, or WebP images there, so keep scripts and SVG files out.
- The directory holds a plugin for review when any shipped file mentions a
credential or something shaped like an environment variable, even in prose
(`$schema` counts). Keep evals in `evals/terminal49/` and run them with
`node scripts/eval.mjs`. `npm run validate` enforces both rules.
- The OpenAI plugin directory takes a ZIP. Build it with
`npm run build:openai-zip`, which writes `dist/terminal49-openai-<version>.zip`
from the Codex manifest, the skills, and the icon. Upload a new ZIP whenever
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,11 @@ account with trade intelligence enabled.
├── .cursor-plugin/marketplace.json # Cursor marketplace
├── openai/review.json # OpenAI directory review cases, merged into the ZIP
├── openai/listing.json # OpenAI package name, version, category, and MCP URL for the existing plugin
├── evals/terminal49/ # Mocked behavioral evals, kept out of the shipped plugin
├── scripts/
│ ├── build-openai-zip.mjs # Builds the OpenAI directory ZIP
│ ├── check-eval-delta.mjs # Checks that every eval case has a positive delta
│ ├── eval.mjs # Runs the evals against a staged copy of the plugin
│ └── validate.mjs
└── plugins/terminal49/
├── .claude-plugin/plugin.json
Expand All @@ -113,9 +115,8 @@ account with trade intelligence enabled.
├── mcp.json # Cursor MCP adapter
├── README.md
├── assets/
│ ├── icon.svg # Square icon for the directories
│ └── logo.svg # Referenced by the Cursor manifest
├── evals/ # Mocked behavioral evals
│ ├── icon.png # Square icon for Codex and the OpenAI directory
│ └── logo.png # Referenced by the Cursor manifest
└── skills/
├── container-tracking/
│ ├── SKILL.md
Expand Down
33 changes: 20 additions & 13 deletions plugins/terminal49/evals/README.md → evals/terminal49/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,38 +28,45 @@ descriptions and input schemas. Refresh it when the server's tools change:

```sh
gh api repos/Terminal49/API/contents/packages/mcp/src/__snapshots__/tools-list.json \
-H "Accept: application/vnd.github.raw" | jq -c '.result | walk(if type == "object" then del(."$schema", .outputSchema) else . end)' > evals/mocks/terminal49/_tools.json
-H "Accept: application/vnd.github.raw" | jq -c '.result | walk(if type == "object" then del(."$schema", .outputSchema) else . end)' > evals/terminal49/mocks/terminal49/_tools.json
```

## Prerequisites

- Claude Code 2.1.269 or newer
- Claude Code authentication for the model under test

From this plugin directory, first validate the plugin:
These evals live outside `plugins/terminal49` on purpose. The Anthropic
directory reviews every file in the plugin folder, and it holds a plugin whose
files mention credentials, which the guardrail cases must do.
`claude plugin eval` reads cases only from inside the plugin folder, so
`scripts/eval.mjs` copies the plugin and these evals into `.eval-stage/` and runs
them there. It passes its options to `claude plugin eval` and copies the results
back to `evals/terminal49/results/`.

Run every command from the repository root. First validate the plugin:

```sh
cd plugins/terminal49
claude plugin validate .
claude plugin validate plugins/terminal49
```

## Run with mocks

Use the checked-in mocks for every MCP call:

```sh
claude plugin eval . --mocks record --no-publish
node scripts/eval.mjs --mocks record --no-publish
```

`record` is the default mock mode. It reads the fixed responses under
`evals/mocks/` and each case's `mocks/` directory; it does not start the real
`mocks/` and each case's `mocks/` directory; it does not start the real
Terminal49 MCP server. Do not add `--allow-real-servers` or use `--mocks off`
for this suite.

For a cheaper one-run check while editing a case:

```sh
claude plugin eval . \
node scripts/eval.mjs \
--case where-is-container \
--runs 1 \
--ablation none \
Expand All @@ -70,7 +77,7 @@ claude plugin eval . \
Run one bank tier with its tag:

```sh
claude plugin eval . \
node scripts/eval.mjs \
--tag tier-b \
--runs 1 \
--ablation none \
Expand All @@ -81,7 +88,7 @@ claude plugin eval . \
Run only the exact MarketingBuddy wording:

```sh
claude plugin eval . \
node scripts/eval.mjs \
--tag marketingbuddy \
--mocks record \
--no-publish
Expand All @@ -94,13 +101,13 @@ To save a machine-checkable full result and require positive delta for every
case:

```sh
claude plugin eval . \
node scripts/eval.mjs \
--mocks record \
--trust-plugin \
--no-publish \
--json /tmp/terminal49-plugin-evals.json

node ../../scripts/check-eval-delta.mjs /tmp/terminal49-plugin-evals.json
node scripts/check-eval-delta.mjs /tmp/terminal49-plugin-evals.json
```

## Reading the result
Expand All @@ -117,7 +124,7 @@ and `Δ` is `WITH - W/OUT`. Green for this plugin means:

Skill and MCP sequencing graders are marked `with-only`, so they are indicators
and do not artificially inflate `Δ`. Inspect failures in the generated HTML
report under `evals/results/`.
report under `evals/terminal49/results/`.

Follow question-bank-first iteration:

Expand All @@ -129,5 +136,5 @@ Follow question-bank-first iteration:
4. keep skill changes thin and rerun the same cases to verify improved `Δ`.

Submit this plugin to the Anthropic community marketplace only after
`claude plugin validate .` passes and the full mocked eval has a green,
`claude plugin validate plugins/terminal49` passes and the full mocked eval has a green,
positive `Δ` against the no-plugin baseline.
2 changes: 1 addition & 1 deletion gemini-extension.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "terminal49",
"version": "0.3.3",
"version": "0.3.4",
"description": "Terminal49 container and shipment tracking: look up containers by container, booking or bill of lading number, check status, milestones, ETAs, holds and last free day, and start new tracking.",
"contextFileName": "GEMINI.md",
"mcpServers": {
Expand Down
8 changes: 1 addition & 7 deletions plugins/terminal49/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "terminal49",
"displayName": "Terminal49",
"version": "0.3.3",
"version": "0.3.4",
"description": "Look up and investigate container shipments, start tracking, and research US ocean import markets with the Terminal49 MCP server.",
"author": {
"name": "Terminal49",
Expand All @@ -20,11 +19,6 @@
"supply-chain",
"trade-intelligence"
],
"icon": "./assets/icon.svg",
"documentationUrl": "https://terminal49.com/docs/mcp/home",
"supportUrl": "https://www.terminal49.com/contact",
"privacyPolicyUrl": "https://www.terminal49.com/privacy",
"termsOfServiceUrl": "https://www.terminal49.com/terms",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}
6 changes: 3 additions & 3 deletions plugins/terminal49/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "terminal49",
"version": "0.3.3",
"version": "0.3.4",
"description": "Look up and investigate container shipments, start tracking, and research US ocean import markets with the Terminal49 MCP server.",
"author": {
"name": "Terminal49",
Expand Down Expand Up @@ -39,7 +39,7 @@
"Which of my containers need attention today?",
"Who are the largest US importers of office chairs?"
],
"composerIcon": "./assets/icon.svg",
"logo": "./assets/icon.svg"
"composerIcon": "./assets/icon.png",
"logo": "./assets/icon.png"
}
}
4 changes: 2 additions & 2 deletions plugins/terminal49/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "terminal49",
"displayName": "Terminal49",
"version": "0.3.3",
"version": "0.3.4",
"description": "Look up and investigate container shipments, start tracking, and research US ocean import markets with the Terminal49 MCP server.",
"author": {
"name": "Terminal49",
Expand All @@ -11,7 +11,7 @@
"homepage": "https://terminal49.com",
"repository": "https://github.com/Terminal49/agent-plugins",
"license": "Apache-2.0",
"logo": "assets/logo.svg",
"logo": "assets/logo.png",
"keywords": [
"container-tracking",
"logistics",
Expand Down
14 changes: 7 additions & 7 deletions plugins/terminal49/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,13 @@ claude plugin install terminal49 --marketplace Terminal49/agent-plugins

## What the plugin connects to

The plugin declares one remote MCP server, `https://mcp.terminal49.com`. It runs
no local programs, hooks, or scripts, and it reads no files or environment
variables on your machine.
The plugin declares one remote MCP server, `https://mcp.terminal49.com`. It
holds only Markdown, JSON, and images. It runs no programs, hooks, or scripts
and reads nothing from your computer.

- **Authentication.** Your client opens the Terminal49 OAuth sign-in in the
browser when a Terminal49 tool is first used. Do not paste API keys, access
tokens, or one-time codes into chat.
- **Connecting.** The first time you use a Terminal49 tool, your client opens a
browser window where you connect your Terminal49 account. You finish
connecting in that window, not in the chat.
- **Data sent.** The tools send the identifiers, filters, and values in your
request (for example a container number or a company name) to the Terminal49
MCP server. The server reads the shipments, documents, and trade data that
Expand Down Expand Up @@ -80,7 +80,7 @@ API and MCP server live in [Terminal49/API](https://github.com/Terminal49/API).
## Plugin evals

Behavioral eval cases use checked-in MCP mocks and never call the live
Terminal49 service. See [`evals/README.md`](evals/README.md) for validation,
Terminal49 service. See [`evals/terminal49/README.md`](https://github.com/Terminal49/agent-plugins/blob/main/evals/terminal49/README.md) for validation,
mocked eval, and baseline guidance.

## License
Expand Down
Binary file added plugins/terminal49/assets/icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 0 additions & 6 deletions plugins/terminal49/assets/icon.svg

This file was deleted.

Binary file added plugins/terminal49/assets/logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 0 additions & 4 deletions plugins/terminal49/assets/logo.svg

This file was deleted.

10 changes: 5 additions & 5 deletions plugins/terminal49/skills/container-tracking/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,12 @@ find it and report current status, location, and anything that needs attention.
## Before using tools

1. Confirm that Terminal49 MCP tools are available.
2. If the client requests authentication, let it start the OAuth browser flow.
3. Sign-in happens in the browser, so never ask the user for sign-in details or
one-time codes in chat.
2. If the client asks to connect, let it open the Terminal49 browser window.
3. The user connects in that browser window, so never ask for connection
details in chat.
4. If the tools remain unavailable, say that the Terminal49 connection must be
enabled and authenticated. Do not invent shipment data.
5. If a lookup returns nothing or an authorization error, call `whoami` to
turned on and connected. Do not invent shipment data.
5. If a lookup returns nothing or an access error, call `whoami` to
confirm the connected account and which gated features it can use.

## Identifier rules
Expand Down
5 changes: 2 additions & 3 deletions plugins/terminal49/skills/trade-intelligence/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,8 @@ the answer and the few numbers that support it, not a data dump.

## Access

The trade tools use the same OAuth connection as the other Terminal49 tools.
Sign-in happens in the browser, so never ask the user for sign-in details in
chat.
The trade tools use the same browser connection as the other Terminal49
tools, so never ask for connection details in chat.

Trade intelligence is enabled per account. If a tool says it is not enabled,
tell the user to contact support@terminal49.com to turn it on. Don't retry, and
Expand Down
2 changes: 1 addition & 1 deletion scripts/build-openai-zip.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ const allowed = [
/^\.codex-plugin\/plugin\.json$/,
/^\.mcp\.json$/,
/^README\.md$/,
/^assets\/[^/]+\.svg$/,
/^assets\/[^/]+\.(svg|png)$/,
/^skills\/[a-z0-9-]+\/SKILL\.md$/,
/^skills\/[a-z0-9-]+\/references\/[^/]+\.md$/,
];
Expand Down
31 changes: 31 additions & 0 deletions scripts/eval.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
// Runs the plugin evals without shipping them in the plugin folder.
// `claude plugin eval` reads cases only from inside the plugin root, and the
// Anthropic directory reviews every file in plugins/terminal49. This script
// copies the plugin and evals/terminal49 into .eval-stage/terminal49, runs the
// evals there, and copies the results back to evals/terminal49/results.
//
// Usage: node scripts/eval.mjs [claude plugin eval options]
import { spawnSync } from "node:child_process";
import { cp, rm } from "node:fs/promises";
import { existsSync } from "node:fs";
import { resolve } from "node:path";
import process from "node:process";

const root = process.cwd();
const pluginDir = resolve(root, "plugins/terminal49");
const evalsDir = resolve(root, "evals/terminal49");
const stage = resolve(root, ".eval-stage/terminal49");

await rm(stage, { recursive: true, force: true });
await cp(pluginDir, stage, { recursive: true });
await cp(evalsDir, resolve(stage, "evals"), {
recursive: true,
filter: (source) => !source.startsWith(resolve(evalsDir, "results")),
});

const result = spawnSync("claude", ["plugin", "eval", stage, ...process.argv.slice(2)], { stdio: "inherit" });

const stagedResults = resolve(stage, "evals/results");
if (existsSync(stagedResults)) await cp(stagedResults, resolve(evalsDir, "results"), { recursive: true });

process.exit(result.status ?? 1);
Loading
Loading