transit-mcp-server

511.org SF Bay Open Data のトランジットAPI用MCPサーバー。LLMにベイエリアのリアルタイム交通データ（事業者、路線、停留所、リアルタイムの発車情報、車両位置、運行障害情報）を提供します。BART、Muni、AC Transit、Caltrain、VTA、その他511に報告しているすべての事業者に対応しています。

ツールは6つ、すべて読み取り専用です。

要件

• Node.js 18+

• https://511.org/open-data/token から取得できる無料の511 APIトークン

Related MCP server: Bay Wheels MCP Server

インストール

npm install
npm run build

設定

{
  "mcpServers": {
    "transit": {
      "command": "node",
      "args": ["/absolute/path/to/transit-mcp-server/dist/index.js"],
      "env": { "TRANSIT_511_API_KEY": "your-token-here" }
    }
  }
}

クォータが主な制約です

511ではキーごとに毎時60リクエストが許可されており、すべてのエンドポイントで共有されます。これは、これらのツールの使い方を左右するほど低い値です。

• 事業者コードと停留所コードは一度解決したら再利用してください。これらは変わりません。

• operator_id を指定しない transit_list_service_alerts を優先してください。1回の呼び出しで全事業者をカバーします。

• transit_next_departures をループでポーリングしないでください。通勤中に10回チェックすると、時間あたりの予算の6分の1を消費します。

transit_list_operators は、511がすべてのレスポンスで返す RateLimit-Remaining ヘッダーから、残りの予算を報告します。クォータを超えると429が返ります。増量をリクエストするには transitdata@511.org に連絡してください。

デプロイ（Claude mobile / claude.ai コネクタ用）

ホスト型MCPサーバーと同じ構成です。openssl rand -hex 32 でパスシークレットを生成し、プラットフォームのダッシュボードで TRANSIT_511_API_KEY と MCP_PATH_SECRET を設定します。同梱の Dockerfile と railway.json は、Railway、Render、Flyでそのまま動作します。サーバーはシークレットなしではパブリックインターフェースでの起動を拒否します。/healthz は認証不要の死活監視エンドポイントです。

その後、ブラウザで claude.ai で: Customize → Connectors → Add custom connector を選択し、URL に https://your-app.up.railway.app/mcp/<secret> を指定します。

ツール

ネットワーク — transit_list_operators、transit_list_lines、transit_find_stops

リアルタイム — transit_next_departures、transit_list_vehicles

アラート — transit_list_service_alerts

すべてのツールは response_format: "markdown" | "json" を受け取ります。Markdownがデフォルトで、LLMが読むのに最適化されています。JSONは完全な構造化ペイロードです。structuredContent はフォーマットに関係なく常に設定されます。

例

「次のNジュダはいつ？」 → operator_id="SF"、query="judah" で transit_find_stops を呼び出して停留所コードを取得し、そのコードと line="N" で transit_next_departures を呼び出します。

「BARTは正常に動いてる？」 → operator_id="BA" で transit_list_service_alerts を呼び出します。

「通勤経路で何か問題ある？」 → オペレーターを指定せずに transit_list_service_alerts を呼び出します。1回の呼び出しでベイエリアの全事業者をスキャンします。

「今、電車はどこにいる？」 → operator_id="BA" で transit_list_vehicles を呼び出します。

設計メモ

構造的に読み取り専用。 511には書き込みエンドポイントがなく、すべてのツールに readOnlyHint: true が付いています。テストでこれを検証しています。

エンドポイントごとに1つの operator_id をマッピング。 511は静的エンドポイントではこのパラメータを operator_id と呼び、リアルタイムエンドポイントでは同じ値に対して agency と呼びます。ここではすべてのツールが operator_id を受け取り、クライアントがそれをマッピングします。この分割は511側の問題であり、呼び出し側の問題ではありません。

2つのリアルタイムエンドポイントは実際には異なるエンベロープを持ちます。 StopMonitoring には Siri ルートラッパーがありません。VehicleMonitoring にはあります。公開されている仕様では両方に1つあるとされていますが、仕様が間違っており、文書化された形で解析すると発車情報がまったく返りません。両方とも実際のAPIが出力する形で解析され、それぞれを固定するテストがあります。

到着時刻にカウントダウンが含まれ、出発時刻には含まれません。 ExpectedDepartureTime は実質的にすべての実データでnullであるため、それに基づいてカウントダウンを行うと、サービスがない停留所として表示されます。ExpectedArrivalTime が信頼できるフィールドです。

UTF-8 BOMは解析前に除去されます。 511はJSONボディの先頭に U+FEFF を付けるため、単純な JSON.parse では有効なペイロードでも例外が発生します。認証失敗はBOMなしのプレーンテキストであるため、ステータスチェック後に除去が行われます。

数値やブール値に見える値は、実際にはそうでないことがよくあります。 座標と方位はJSON文字列として到着し、VehicleAtStop は文字列 "false" であり、nullを意図した場所では "" が使用されます。盲目的に変換すると、欠落した位置がアフリカ沖の有効な0,0に見えてしまうため、空文字列はゼロではなく欠落として扱われます。

エポックゼロのセンチネルはタイムスタンプではありません。 スケジュールされているが車両が割り当てられていない便は、RecordedAtTime が 1970-01-01T00:00:00Z と報告されます。これは「56年前に記録された」ではなく「まだ車両が割り当てられていません」と表示されます。

GTFS-Realtimeの列挙型はデコードされます。 511のJSONアラートレンダリングは "effect": 3 を出力しますが、XMLレンダリングでは SignificantDelays と表示されます。原因と影響の両方が単語にマッピングされます。

511内部の疑似事業者は除外されます。 5E、5F、5O、5S は511の緊急、フラップサイン、運用、スタッフであり、事業者リストにサービスデータなしで表示されます。

すべて太平洋時間です。 タイムスタンプはUTCで到着し、America/Los_Angeles でレンダリングされるため、夏時間はモデルが年に2回処理するのではなく、ここで一度処理されます。511自身の TimeZone フィールドは、ベイエリアのすべての事業者に対して America/Vancouver を報告することに注意してください。これは既知の上流のデータバグであり、意図的に無視されています。

切り捨ては常に明示されます。 511はページネーションを行わず、コレクション全体を返します。大規模な事業者には数千の停留所があります。ツールはクライアント側の limit を受け取り、切り詰められた結果はすべて、保留された量を明示します。黙って短縮されたリストは「それがすべてです」と読めるからです。

注意事項

• 時間あたりのクォータは全エンドポイントで60リクエストです。これはどのワークフローでも制約となります。

• 事業者コードは間違えやすいです。VTAは SC（VT ではない）、Capitol Corridorは AM（CC ではない）、Tri Deltaは 3D です。transit_list_operators はこれらの罠を出力に表示します。

• 停留所コードは1つの事業者に属し、事業者間で交換できません。

• transit_find_stops はこのサーバー上でフィルタリングするため、狭いクエリでもクォータは節約されません。完全な停留所リストはどちらにせよ取得されます。

• リアルタイム予測は約90分先までで、511は路線の最終到着専用停留所を発車情報フィードから除外します。

• tripupdates と vehiclepositions はprotobufのみでJSONオプションがないため、意図的に公開していません。サポートするには、SIRIエンドポイントがすでにカバーしているデータのためにprotobuf依存関係を追加する必要があります。

プロジェクト構成

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # enums, limits, operator-code traps
├── types.ts               # interfaces for every 511 entity
├── services/
│   └── transit-client.ts  # fetch wrapper, auth, BOM stripping, quota tracking, errors
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # limiting, truncation, Pacific-time rendering
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── network.ts         # operators, lines, stops
    ├── departures.ts      # real-time arrivals and vehicles
    └── alerts.ts          # service alerts

テスト

npm run build
npm test            # 42 checks: handshake, BOM, envelopes, quirks, errors (mocked API)
npm run test:http   # 17 checks: config validation, path-secret gating, method handling, origins

両方のスイートは、511の実際の癖（BOM、欠落した Siri ラッパー、文字列化されたブール値と座標、エポックセンチネル、プレーンテキストのエラーボディ）を意図的に再現するローカルモックに対して実行されます。これらはまさに、素朴なクライアントが間違える点だからです。