Terminal49

Terminal49 MCP サーバー（TypeScript）

Terminal49 の API 向けVercel ネイティブな Model Context Protocol サーバーです。TypeScript と公式の MCP SDK で構築されています。

🚀 Vercel へすばやくデプロイ

1. 上の「Deploy」をクリックします
2. 環境変数 T49_API_TOKEN=your_token_here を追加します
3. デプロイします！
4. MCP サーバーは次の場所で利用できます：https://your-deployment.vercel.app/api/mcp

---

📦 含まれる内容

🛠️ ツール（30 種類）

ツール	説明	主な機能
search_container	コンテナ番号、BL、予約番号、または参照番号で検索します	高速なあいまい検索
track_container	追跡リクエストを作成し、コンテナデータを取得します	SCAC の自動補完 ✨
identify_tracking_number	番号の種類と運送会社を予測し、すでに追跡されているか確認します	何も作成しません
get_container	柔軟なデータ読み込みでコンテナの詳細情報を取得します	カスタムフィールドと関係者の役割を任意で指定できます
get_shipment_details	輸送ルート、BOL、コンテナ、港の情報を取得します	カスタムフィールドと関係者の役割を任意で指定できます
get_container_transport_events	コンテナのイベント履歴全体を取得します	マイルストーン履歴
get_supported_shipping_lines	SCAC コード付きで、40 社以上の主要運送会社を一覧表示します	名前またはコードで絞り込み可能
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	追跡リクエスト 1 件のステータス、失敗理由、輸送情報を取得します	追跡後の確認
list_documents	ファイル名、参照番号、または種類でドキュメントを検索します	抽出データやファイルリンクは返しません
get_document	オプトインで抽出データ、元メール、ダウンロードリンクを含め、ドキュメント 1 件を取得します	信頼できないコンテンツにはラベルが付けられます
search_docs	公開されている Terminal49 のドキュメントを検索します	引用用リンクを返します
whoami	認証情報、そのアカウント、利用可能な機能、セッションのツールセットを特定します	結果が空、または権限がない理由を説明します
set_party_role	コンテナまたは輸送に関係者（ドレージ運送会社など）を追加、置換、または解除します	破壊的な書き込み操作。リクエストがあった場合のみ実行
set_custom_field	コンテナまたは輸送にアカウントのカスタムフィールドを設定、またはクリアします	破壊的な書き込み操作。リクエストがあった場合のみ実行
search_importers	名前、輸入品目、またはその両方で米国の輸入業者を検索します	貿易インテリジェンス。アカウントごと
get_importer_profile	輸入業者 1 社の合計、月次推移、港、原産地、運送会社、製品を取得します	貿易インテリジェンス。アカウントごと
search_commodities	製品の説明または HS コードのプレフィックスを 4 桁の HS コードに変換します	貿易インテリジェンス。アカウントごと
rank_importers	製品、米国の港、または原産国ごとに、コンテナ数で輸入業者をランク付けします	貿易インテリジェンス。アカウントごと
get_trade_trends	コンテナ数、TEU、または推定金額の時系列を取得します	貿易インテリジェンス。アカウントごと
get_trade_breakdown	1〜3 個のディメンションによる階層化された合計を取得します	貿易インテリジェンス。アカウントごと
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 コンテンツブロックを返します。各ブロックはコンテナの行ごとに 1 つあり、登録済みの terminal49://container/{id} リソースを指します。クライアントはコンパクトな一覧を表示し、必要に応じて resources/read でコンテナごとの詳細を取得できます。これにより、あらかじめすべてのコンテナの全ペイロードを取得する必要がなくなります。

🙈 コンテンツの対象者アノテーション

ツールの結果では、人間が読める回答とエージェント制御用のメタデータが分離されています。制御用ブロック（提示方法のガイダンスと、_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 コードの補完: get_supported_shipping_lines をソースとする、track-shipment プロンプトの carrier 引数に対する completion/complete
• 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 レスポンスを返します。コネクターと chatgpt-app-submission.json の値を OpenAI プラグイン申請フローから送信します。

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

レジストリ名が io.github.Terminal49 名前空間を使用するため、公開者は Terminal49 GitHub 組織のオーナーとして認証する必要があります。

---

🛠️ ローカル開発

前提条件

• 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	MCP ツール／プロンプトの入力を Sentry に記録します
SENTRY_MCP_RECORD_OUTPUTS	いいえ	false	MCP ツール／プロンプトの出力を Sentry に記録します
SENTRY_SEND_DEFAULT_PII	いいえ	false	Sentry のデフォルトの PII 動作を有効にします

SENTRY_MCP_RECORD_INPUTS または SENTRY_MCP_RECORD_OUTPUTS を有効にするのは、Sentry プロジェクトで出荷識別子、参照情報、顧客データの保存が承認されていることを確認してからにしてください。

認証情報を含むヘッダー（Authorization、Cookie、および名前に auth、token、secret、cookie、session、api-key、password、signature のいずれかを含むヘッダー）とリクエスト Cookie は、SENTRY_SEND_DEFAULT_PII の設定にかかわらず、すべてのエラーイベントとトランザクションイベントから削除してから送信されます。

get_document が返すドキュメントのダウンロードリンクなどの署名付き URL は、ログ、Sentry イベント、PostHog イベント内で [REDACTED_URL] に置き換えられます。これは、SENTRY_MCP_RECORD_OUTPUTS が有効な場合も同様です。

ツールセット

各ツールは src/tools/registry.ts 内のいずれか1つのツールセットに属します。ツールセットは 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

このリポジトリには、2 つの実装が含まれています。

機能	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」エラー

解決策： GET ではなく、POST メソッドを使用していることを確認してください。

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. リポジトリをフォークします
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 の問題
• ドキュメント： https://docs.terminal49.com
• メール： [email protected]

---

MCP TypeScript SDK で構築 🚀