Terminal49

Terminal49 MCP 服务（TypeScript）

原生支持 Vercel 的 Terminal49 API 模型上下文协议服务，使用 TypeScript 和官方 MCP SDK 构建。

🚀 快速部署到 Vercel

1. 点击上方的“部署”
2. 添加环境变量：T49_API_TOKEN=your_token_here
3. 部署！
4. MCP 服务将在此处提供：https://your-deployment.vercel.app/api/mcp

---

📦 包含内容

🛠️ 工具（30 个可用）

工具	描述	主要功能
search_container	按集装箱号、提单、订舱号或参考号搜索	快速模糊搜索
track_container	创建跟踪请求并获取集装箱数据	SCAC 自动补全 ✨
identify_tracking_number	预测号码类型和承运人，并检查是否已在跟踪	不会创建任何内容
get_container	获取集装箱详细信息，支持灵活加载数据	可选自定义字段和参与方角色
get_shipment_details	获取货运路线、提单、集装箱和港口信息	可选自定义字段和参与方角色
get_container_transport_events	获取集装箱的完整事件时间线	里程碑历史记录
get_supported_shipping_lines	列出 40 多家主要承运人及其 SCAC 代码	可按名称或代码筛选
get_container_route	按路线顺序获取港口、预计到达时间和当前船舶	高级功能
get_location	获取港口、码头或都市区信息	FIRMS 代码、地址、时区
get_vessel	获取船舶位置，以及（可选）其前往港口的预计航线	航线预测为高级功能
list_shipments	使用筛选条件和分页列出货运	查看整个船队
list_containers	使用筛选条件和分页列出集装箱	返回 ResourceLinks ✨
summarize_containers	按码头、状态、承运人、港口、扣留状态或日期对集装箱计数分组	与 list_containers 使用相同的筛选条件
list_parties	按公司名称查找参与方，或通过 ID 读取参与方信息	为 advanced_filters.parties 提供数据
list_custom_field_definitions	列出账户的自定义字段、字段类型和枚举选项	需要已登录用户
list_tracking_requests	列出跟踪请求及其状态	审计和监控
get_tracking_request	获取单个跟踪请求的状态、失败原因和货运信息	跟踪后的后续查询
list_documents	按文件名、参考号或类型查找文档	不会返回提取的数据或文件链接
get_document	获取单份文档，并可选择获取提取的数据、源邮件和下载链接	不可信内容会标注出来
search_docs	搜索 Terminal49 公开文档	返回可供引用的链接
whoami	识别凭据、所属账户、可用功能以及会话的工具集	说明结果为空或未经授权的原因
set_party_role	在集装箱或货运上关联、替换或解除参与方（如货运承运人）	破坏性写入操作，仅在请求时执行
set_custom_field	在集装箱或货运上设置或清除账户的某个自定义字段	破坏性写入操作，仅在请求时执行
search_importers	按名称、进口商品或两者查找美国进口商	贸易情报，按账户提供
get_importer_profile	获取单个进口商的总量、月度序列、港口、原产地、承运人和产品	贸易情报，按账户提供
search_commodities	将产品描述或 HS 前缀转换为四位 HS 编码	贸易情报，按账户提供
rank_importers	按某种产品、美国港口或原产国的集装箱数量对进口商排名	贸易情报，按账户提供
get_trade_trends	集装箱数量、TEU 或估算价值的时间序列	贸易情报，按账户提供
get_trade_breakdown	按一至三个维度呈现嵌套总量	贸易情报，按账户提供
get_trade_data_coverage	查询贸易数据的起始时间、最新月份和最近完整月份	贸易情报，按账户提供

🎯 提示词（3 个工作流）

提示词	描述	用例
track-shipment	跟踪集装箱，可选承运商	快速开始跟踪（支持 SCAC 自动补全 ✨）
check-demurrage	分析滞期费／滞箱费风险	LFD 计算
analyze-delays	识别延误及根本原因	时间线分析

track-shipment 提示词的 carrier 参数支持 MCP 补全（completion/complete）：建议实时取自 get_supported_shipping_lines，根据用户已输入的内容进行筛选，并以 SCAC 代码形式返回。

📚 资源

• ✅ terminal49://docs/milestone-glossary - 完整的里程碑参考指南
• ✅ terminal49://docs/mcp-query-guidance - 内部工具路由提示
• ✅ terminal49://container/{id} - 动态集装箱数据访问（也是 list_containers ResourceLinks 的目标）

🧭 服务说明

服务会在初始化时公布 MCP instructions（服务级操作指南）：说明海运集装箱／货运跟踪领域、关键术语（SCAC、BOL／订舱、POL／POD、LFD、滞期费、扣留），只读工具与唯一写入工具（track_container），以及标准的工具链调用顺序。

🔗 ResourceLinks（减少上下文）

list_containers 会返回 MCP resource_link 内容块，每个集装箱行对应一个，并指向已注册的 terminal49://container/{id} 资源。客户端可以呈现紧凑列表，并按需通过 resources/read 获取每个集装箱的完整详情，而无需一开始就加载所有集装箱的完整数据。

🙈 内容受众注释

工具结果将面向用户的回答与引导 Agent 的元数据分开。引导内容块（呈现指南和建议的后续工具，源自 _response_contract）带有 annotations: { audience: ['assistant'] } 标签，因此支持规范的客户端可以向最终用户隐藏该内容块，同时让回答内容块对用户可见。

✨ 当前功能（v1.0.0 - 第 1 阶段和第 2.1 阶段已完成）

✅ 现代化的 McpServer API

• 高级 registerTool()、registerPrompt()、registerResource() 模式
• 所有工具输入均使用类型安全的 Zod 架构
• 代码更简洁、更易维护（HTTP 处理程序的代码量减少了 71%）
• MCP SDK：@modelcontextprotocol/sdk ^1.29.0
• Terminal49 SDK：@terminal49/sdk 0.2.0

✅ 生产环境传输支持

• HTTP（可流式传输）：POST /api/mcp - 无状态，返回 JSON 响应
• 托管部署路径已移除 SSE，改用 Streamable HTTP 传输。

✅ Sentry MCP 监控

• 使用 @sentry/node ^10.55.0 进行可选的监测
• 设置 SENTRY_DSN 后，记录 MCP 连接、工具调用、资源、提示词、性能跨度和错误
• 默认禁用工具输入／输出记录；仅在审查数据处理要求后启用

✅ 3 个工作流提示词

• track-shipment：快速跟踪集装箱，可选承运商
• check-demurrage：滞期费／滞箱费风险分析
• analyze-delays：识别航程延误及根本原因

✅ 遵循 MCP 规范

• 服务说明：初始化时公布服务级操作指南
• SCAC 代码补全：track-shipment 提示词的 carrier 参数支持 completion/complete，建议取自 get_supported_shipping_lines
• ResourceLinks：list_containers 的各行均链接到 terminal49://container/{id} 资源
• 内容受众注释：引导元数据带有 audience: ['assistant'] 标签

🚧 暂缓（未来 RFC — 需要有状态传输）

• 资源订阅、进度通知、服务日志记录、信息征询和采样都需要有状态（非无状态 HTTP）传输，因此不在此范围内。
• 货运 ResourceLinks 尚待专用的 terminal49://shipment/{id} 资源模板（目前仅注册了集装箱模板）。

---

🏗️ 架构

/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

MCP 默认使用已发布的 @terminal49/sdk，贡献者也可以选择使用本地覆盖版本。

传输方式：

• HTTP：位于 /api/mcp 的 Vercel 无服务器函数（用于托管）
• stdio：用于 Claude Desktop 的本地二进制文件（通过 npm run mcp:stdio 运行）

---

提交到商店

公开连接器 URL 为 https://mcp.terminal49.com。商店资源和提交元数据已存入仓库根目录：

• chatgpt-app-submission.json — 已锁定的 ChatGPT 列表文案和审核用例
• claude-connector-submission.json — 需在 Claude 提交门户中填写的值
• server.json — 用于 Copilot 发现的官方 MCP Registry 元数据
• public/store-icons/terminal49-{light,dark}.png — 512×512 品牌图标

为 ChatGPT 验证域名

OpenAI 会在提交期间生成一个唯一的域名验证令牌。请将该准确值添加到现有的 MCP Vercel 项目中：

vercel env add OPENAI_APPS_CHALLENGE

项目重新部署后，请验证 well-known 端点仅返回你粘贴的令牌：

curl --fail --silent \
  https://mcp.terminal49.com/.well-known/openai-apps-challenge

请勿提交该令牌。未设置 OPENAI_APPS_CHALLENGE 时，端点会返回空的 404 响应。通过 OpenAI 插件提交流程提交连接器和 chatgpt-app-submission.json 中的值。

提交到 Claude

使用 Claude Connectors Directory 门户，并填写 claude-connector-submission.json 中的值。上传 public/store-icons/terminal49-light.png 中的浅色图标；支持按主题使用不同资源的客户端可使用深色版本。

发布以供 Copilot 发现

GitHub 的 Copilot 注册表是经过筛选的下游发现平台。将 server.json 发布到官方 MCP Registry，即可让 Terminal49 有资格出现在该平台上：

mcp-publisher validate server.json
mcp-publisher login github
mcp-publisher publish server.json

发布者必须以 Terminal49 GitHub 组织所有者的身份进行身份验证，因为注册表名称使用其 io.github.Terminal49 命名空间。

---

🛠️ 本地开发

前提条件

• Node.js 24.x
• Terminal49 API 令牌（在此获取）

设置

cd packages/mcp
npm install
T49_SDK_SOURCE=published npm run sdk:setup
cp .env.example .env
# Add your T49_API_TOKEN to .env

开发 MCP 时使用本地 SDK 构建版本：

cd packages/mcp
T49_SDK_SOURCE=local npm run sdk:setup

本地运行

# Stdio mode (for Claude Desktop testing)
npm run mcp:stdio

# Development mode with auto-reload
npm run dev

测试 API

# List tools
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npm run mcp:stdio

# Get container
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_container","arguments":{"id":"123e4567-e89b-12d3-a456-426614174000"}},"id":2}' | npm run mcp:stdio

---

🌐 使用 Vercel 部署

部署

# Install Vercel CLI
npm i -g vercel

# Deploy to Vercel
vercel

# Set environment variable
vercel env add T49_API_TOKEN

配置 MCP 客户端

部署完成后，你的 MCP 服务地址为：https://your-deployment.vercel.app/api/mcp

用于 Claude Desktop 或其他 MCP 客户端：

{
  "mcpServers": {
    "terminal49": {
      "url": "https://your-deployment.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Token your_api_token_here"
      }
    }
  }
}

用于 Cursor IDE：

{
  "mcp": {
    "servers": {
      "terminal49": {
        "url": "https://your-deployment.vercel.app/api/mcp",
        "headers": {
          "Authorization": "Token your_api_token_here"
        }
      }
    }
  }
}

---

🔧 API 参考

HTTP 端点

URL： POST /api/mcp

请求头：

Authorization: Token your_api_token_here
Content-Type: application/json

请求（JSON-RPC）：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_container",
    "arguments": {
      "id": "123e4567-e89b-12d3-a456-426614174000"
    }
  },
  "id": 1
}

响应：

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"...\",\"container_number\":\"...\", ...}"
      }
    ]
  },
  "id": 1
}

可用方法

方法	描述
initialize	初始化 MCP 连接
tools/list	列出可用工具
tools/call	执行工具
resources/list	列出可用资源
resources/read	读取资源

---

🔐 身份验证

用于 Vercel 部署（HTTP）

在 Vercel 控制面板中设置为环境变量：

T49_API_TOKEN=your_token_here

或者在请求头中包含：

Authorization: Token your_token_here

Token 是首选方案。为向后兼容，也接受 Bearer your_token_here。

用于本地 stdio

在环境中设置：

export T49_API_TOKEN=your_token_here

---

🧪 测试

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

---

📝 环境变量

变量	必填	默认值	说明
T49_API_TOKEN	✅ 是	-	Terminal49 API 令牌
T49_API_BASE_URL	否	https://api.terminal49.com/v2	API 基础 URL
T49_MCP_TOOLSETS	否	core,documents,operations,trade	此部署提供的工具集，以逗号分隔。参见工具集。
T49_MCP_READ_ONLY	否	false	仅提供 readOnlyHint 为 true 的工具。接受任意大小写形式的 true、false、1 或 0。
T49_MCP_ALLOW_SHARED_TOKEN_WRITES	否	false	当调用方共用 T49_API_TOKEN 时，提供 core 和 trade 以外的工具集
OPENAI_APPS_CHALLENGE	仅用于提交到 ChatGPT	-	OpenAI 提交门户颁发的确切域名验证令牌
NODE_ENV	否	development	环境
LOG_LEVEL	否	info	日志级别
REDACT_LOGS	否	true	在日志中隐藏令牌
SENTRY_ENABLED	否	true	配置 DSN 后启用或禁用 Sentry
SENTRY_DSN	否	-	设置后启用 Sentry MCP Monitoring
SENTRY_ENVIRONMENT	否	NODE_ENV	Sentry 环境名称
SENTRY_RELEASE	否	VERCEL_GIT_COMMIT_SHA	Sentry 版本标识符
SENTRY_TRACES_SAMPLE_RATE	否	1.0	跟踪采样率，范围为 0 至 1
SENTRY_MCP_RECORD_INPUTS	否	false	在 Sentry 中记录 MCP 工具/提示词输入
SENTRY_MCP_RECORD_OUTPUTS	否	false	在 Sentry 中记录 MCP 工具/提示词输出
SENTRY_SEND_DEFAULT_PII	否	false	启用 Sentry 默认的 PII 行为

只有在确认你的 Sentry 项目获准存储货运标识符、参考信息和客户数据后，才启用 SENTRY_MCP_RECORD_INPUTS 或 SENTRY_MCP_RECORD_OUTPUTS。

在发送之前，所有错误和事务事件中的凭据标头（Authorization、Cookie，以及名称包含 auth、token、secret、cookie、session、api-key、password 或 signature 的任何标头）和请求 Cookie 都会被移除，不受 SENTRY_SEND_DEFAULT_PII 设置影响。

已签名的 URL（例如 get_document 返回的文档下载链接）会在日志、Sentry 事件和 PostHog 事件中替换为 [REDACTED_URL]。即使启用了 SENTRY_MCP_RECORD_OUTPUTS，也同样如此。

工具集

每个工具都属于 src/tools/registry.ts 中的一个工具集：core、documents、operations、documents_write、developer 或 trade。list_documents 和 get_document 属于 documents。set_party_role 和 set_custom_field 属于 operations。贸易情报工具属于 trade。目前所有其他工具都属于 core。whoami 会报告会话提供的工具集，以及会话是否包含写入工具。

• T49_MCP_TOOLSETS 列出服务器允许的工具集。stdio 和 HTTP 网关都会读取此变量。未知名称或仅由逗号组成的值会导致 stdio 停止运行，并显示包含变量名称的错误。HTTP 请求会失败并返回通用的 500 错误，网关会记录原因。
• X-T49-MCP-Toolsets 请求标头只能缩小此列表范围。服务器只提供同时出现在两者中的工具集。未知名称或仅由逗号组成的值会返回 400。
• X-T49-MCP-Read-Only: true 或 T49_MCP_READ_ONLY=true 会移除所有 readOnlyHint 为 false 的工具，包括 track_container。两者均接受任意大小写形式的 true、false、1 或 0。其他任何标头值都会返回 400。此标头无法关闭由环境变量启用的只读模式。
• 服务器说明只会列出该会话提供的工具。
• 当网关使用一个共享的 T49_API_TOKEN 时，除非设置 T49_MCP_ALLOW_SHARED_TOKEN_WRITES=true，否则只提供 core 和只读的 trade 工具集。
• 工具集绝不会从连接器 URL 中读取。OAuth 资源仍为根源站。

---

🆚 Ruby 与 TypeScript

此仓库包含 两种实现：

功能	Ruby（/mcp）	TypeScript（/packages/mcp + /api）
部署	Railway、Fly.io、Heroku	✅ Vercel（原生支持）
HTTP 传输	Rack/Puma	✅ Vercel Serverless
stdio 传输	✅ 支持	✅ 支持
状态	已完成	已完成
适用场景	独立服务	Vercel 部署

建议： 在 Vercel 上部署时使用 TypeScript（零配置、自动扩缩容）。

---

🚦 Vercel 配置

项目包含用于优化 Vercel 部署的 vercel.json：

{
  "functions": {
    "api/mcp.ts": {
      "runtime": "nodejs20.x",
      "maxDuration": 30,
      "memory": 1024
    }
  }
}

配置说明

• 运行时： Node.js 20.x
• 最长执行时间： 30 秒（可针对 Pro/Enterprise 调整）
• 内存： 1024 MB
• CORS： 对所有来源启用（Access-Control-Allow-Origin: *）

---

🐛 故障排除

“T49_API_TOKEN is required”错误

解决方案： 在 Vercel 控制面板或本地设置环境变量：

vercel env add T49_API_TOKEN

“Method not allowed”错误

解决方案： 确保使用 POST 方法，而不是 GET：

curl -X POST https://your-deployment.vercel.app/api/mcp \
  -H "Authorization: Token your_token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

浏览器中的 CORS 错误

解决方案： CORS 已在 vercel.json 中配置。如果问题仍然存在，请查看 Vercel 部署日志：

vercel logs

超时错误

解决方案： 在 vercel.json 中增加 maxDuration（需要 Vercel Pro/Enterprise）：

{
  "functions": {
    "api/mcp.ts": {
      "maxDuration": 60
    }
  }
}

---

📚 文档

• MCP 协议： https://modelcontextprotocol.io/
• Terminal49 API： https://docs.terminal49.com
• Vercel Functions： https://vercel.com/docs/functions
• TypeScript MCP SDK： https://github.com/modelcontextprotocol/typescript-sdk

---

🤝 贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/my-tool
3. 在 /packages/mcp/src/ 中进行更改
4. 添加测试
5. 运行类型检查：npm run type-check
6. 提交 PR

---

📄 许可证

Copyright 2024 Terminal49. All rights reserved.

---

🆘 支持

• 问题： GitHub Issues
• 文档： https://docs.terminal49.com
• 电子邮件： [email protected]

---

使用 MCP TypeScript SDK 构建 🚀