Terminal49

Terminal49 MCP Server (TypeScript)

Vercel-native Model Context Protocol server for Terminal49's API, built with TypeScript and the official MCP SDK.

@terminal49/mcp is a private workspace in this repository. Connect a client to the hosted server at https://mcp.terminal49.com (Streamable HTTP). OAuth 2.1 needs no API key: the client discovers https://auth.terminal49.com and opens a browser sign-in. Clients that can't run that flow send Authorization: Token YOUR_API_KEY. Use the Token scheme for API keys. The Bearer scheme is used for OAuth access tokens. A local stdio process reads T49_API_TOKEN instead. Build steps are in Local Development.

🚀 Quick Deploy to Vercel

1. Click "Deploy" above
2. Add environment variable: T49_API_TOKEN=your_token_here
3. Deploy!
4. Your MCP server will be available at: https://your-deployment.vercel.app/api/mcp

---

📦 What's Included

🛠️ Tools (30 Available)

🎯 Prompts (3 Workflows)

The track-shipment prompt's carrier argument supports MCP completions (completion/complete): suggestions are sourced live from get_supported_shipping_lines, filtered by what the user has typed, and returned as SCAC codes.

📚 Resources

• ✅ `terminal49://docs/milestone-glossary` - Complete milestone reference guide
• ✅ `terminal49://docs/mcp-query-guidance` - Internal tool-routing hints
• ✅ `terminal49://container/{id}` - Dynamic container data access (also the target of list_containers ResourceLinks)

🧭 Server Instructions

The server advertises MCP instructions (a server-level operating guide) at initialize time: it explains the ocean container/shipment tracking domain, key vocabulary (SCAC, BOL/booking, POL/POD, LFD, demurrage, holds), the read tools vs the single write tool (track_container), and the canonical tool-chaining order.

🔗 ResourceLinks (context reduction)

list_containers returns MCP resource_link content blocks — one per container row — that point at the registered terminal49://container/{id} resource. Clients can render the compact list and resolve full per-container detail on demand via resources/read, instead of paying for every container's full payload up front.

🙈 Content Audience Annotations

Tool results separate the human-readable answer from agent-steering metadata. The steering block (presentation guidance + suggested follow-up tools, derived from the _response_contract) is tagged with annotations: { audience: ['assistant'] } so spec-aware clients can hide it from end users, while the answer block stays user-visible.

✨ Current Features (v1.0.0 - Phase 1 & 2.1 Complete)

✅ Modern McpServer API

• High-level registerTool(), registerPrompt(), registerResource() patterns
• Type-safe Zod schemas for all tool inputs
• Cleaner, maintainable code (71% code reduction in HTTP handler)
• MCP SDK: @modelcontextprotocol/sdk ^1.29.0
• Terminal49 SDK: @terminal49/sdk 0.6.0

✅ Production Transport Support

• HTTP (streamable): POST /api/mcp - stateless, JSON responses
• SSE was removed from the hosted deployment path in favor of Streamable HTTP transport.

✅ Sentry MCP Monitoring

• Optional instrumentation with @sentry/node ^10.55.0
• Captures MCP connections, tool calls, resources, prompts, performance spans, and errors when SENTRY_DSN is set
• Tool input/output recording is disabled by default; enable it only after reviewing data handling requirements

✅ 3 Workflow Prompts

• track-shipment: Quick container tracking with optional carrier
• check-demurrage: Demurrage/detention risk analysis
• analyze-delays: Journey delay identification and root cause

✅ MCP Spec Adherence

• Server instructions: server-level operating guide advertised at initialize
• SCAC code completions: completion/complete on the track-shipment prompt's carrier arg, sourced from get_supported_shipping_lines
• ResourceLinks: list_containers rows link to the terminal49://container/{id} resource
• Content audience annotations: steering metadata tagged audience: ['assistant']

🚧 Deferred (future RFC — needs a stateful transport)

• Resource subscriptions, progress notifications, server logging, elicitation, and sampling all require a stateful (non-stateless-HTTP) transport and are out of scope here.
• Shipment ResourceLinks await a dedicated terminal49://shipment/{id} resource template (only the container template is currently registered).

---

🏗️ Architecture

/api/mcp.ts                  # Vercel serverless function (HTTP)

/packages/mcp/ ├── src/ │ ├── server.ts # MCP server (stdio) │ ├── index.ts # Stdio entry point │ ├── tools/ # MCP tools │ └── resources/ # MCP resources └── package.json

The MCP server depends on the workspace package @terminal49/sdk. Build that package before you build packages/mcp.

Transport:

• HTTP: Vercel serverless function at /api/mcp (for hosted use)
• stdio: Local process for Claude Desktop (node packages/mcp/dist/index.js after the build in Local Development)

---

Store submission

The public connector URL is https://mcp.terminal49.com. Store assets and submission metadata are checked in at the repository root:

• chatgpt-app-submission.json — locked ChatGPT listing copy and review cases
• claude-connector-submission.json — values to enter in Claude's submission portal
• server.json — official MCP Registry metadata used for Copilot discovery
• public/store-icons/terminal49-{light,dark}.png — 512×512 brand icons

Cline and other clients that read a marketplace install guide from the server subfolder use packages/mcp/llms-install.md.

Verify the domain for ChatGPT

OpenAI generates a unique domain-verification token during submission. Add that exact value to the existing MCP Vercel project:

vercel env add OPENAI_APPS_CHALLENGE

After the project redeploys, verify that the well-known endpoint returns only the token you pasted:

curl --fail --silent \

https://mcp.terminal49.com/.well-known/openai-apps-challenge

Do not commit the token. The endpoint returns an empty 404 response while OPENAI_APPS_CHALLENGE is unset. Submit the connector and the values in chatgpt-app-submission.json through the OpenAI plugin submission flow.

Submit to Claude

Use the Claude Connectors Directory portal and enter the values in claude-connector-submission.json. Upload the light icon from public/store-icons/terminal49-light.png; the dark variant is available for clients that support theme-specific assets.

Publish for Copilot discovery

GitHub's Copilot registry is a curated downstream discovery surface. The root server.json is the official MCP Registry entry (io.github.Terminal49/terminal49).

.github/workflows/publish-mcp.yml publishes that file to https://registry.modelcontextprotocol.io. It runs when a push to main changes server.json, and a maintainer can start it with workflow_dispatch on main. The job authenticates with GitHub OIDC (mcp-publisher login github-oidc) and then runs mcp-publisher publish. The io.github.Terminal49 namespace is authorized for OIDC from this organization repository, so the workflow needs no registry secret.

Bump version in server.json for each metadata change. The registry keeps published versions, and a second publish of the same version is rejected.

---

🛠️ Local Development

Prerequisites

• Node.js 24.22.1 or a newer Node 24 release (`.tool-versi