fix(mcp): harden tool output quality and coverage

[dodeja]

Summary

• add real MCP client-transport happy-path and redacted-error coverage for all 10 public tools, with realistic tool-specific fixture assertions
• exercise all prompts and resources through the transport; preserve m / ma carrier completions and full tool/prompt/resource surfaces on protocols 2026-07-28 and 2025-11-25
• distinguish three track_container outcomes without leaking internals: no request created, request created but details pending, and existing match temporarily unavailable
• sanitize exception messages before Sentry capture as well as in client responses/logs
• advertise only list filters the Terminal49 API actually honors: shipment number and tracking_stopped; container lists now state that server-side operational filters are unavailable
• reduce default list cost to 25 rows, omit shipment relationships from list results unless requested, and request raw-only route data
• enforce consistency between live titles/annotations and both store-listing files, including locked listing values and reviewer-case shape

Measurement

• default list response ceiling is now 25 rows instead of the upstream/default-dependent size (the explicit maximum remains 100)
• list_shipments no longer includes nested containers by default; callers can opt in with include_containers: true
• route calls request one raw representation instead of format: both, avoiding construction of a discarded mapped payload
• transport coverage calls every public tool on both a realistic happy path and a URL/token-bearing upstream failure path; each successful call is validated by the real MCP client against its advertised output schema
• unsupported container/shipment filters can no longer be selected from the public tool schema or counted as applied by _response_contract

Verification

• npm run test --workspace @terminal49/mcp -- --run — 15 files, 212 tests passed
• npm run build --workspace @terminal49/mcp — passed
• npm run lint --workspace @terminal49/mcp — passed under pinned Node 24.4.1
• npx tsc --noEmit -p tsconfig.json — API gateway typecheck passed
• git diff --check origin/cursor/fix-list-output-schema-0c41...HEAD — passed

Left unchanged

• stacked on fix(mcp): validate list tool SDK sidecars #336, which owns the unsupportedFilters schema correction for list_containers and list_shipments; this PR does not duplicate it
• carrier completions remain uncached because the production HTTP gateway is stateless; a per-server cache has no effect across requests, while a module-wide cache could contaminate separate account/backend clients
• preserves MCP SDK v2, OAuth behavior, the locked listing name/tagline/URL/ChatGPT one-liner, the 9-read/1-write annotation contract, and the tight 10-tool catalog
• no live reviewer fixture is assumed, no app-store submission is performed, and no production secrets are changed

Requirements verified against

• OpenAI plugin submission and MCP review requirements: titles; explicit readOnlyHint, destructiveHint, and openWorldHint; five positive and three negative cases
• Claude connector submission and review criteria: OAuth, titles, applicable annotations, tagline limit, graceful errors, tight catalog, and token-frugal output

  

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview	Aug 21, 2026 6:31am