onebusaway-mcp-server

---

概要

Puget Sound（King County Metro、Sound Transit、Pierce Transit、Community Transit など）向けに設定され、あらゆる OneBusAway インスタンスに対応した、OneBusAway のリアルタイム交通情報です。停留所や路線を検索し、リアルタイムの到着情報や車両の位置を追跡して、時刻表や運行アラートを取得できます。

ツール

ツール	説明
onebusaway_list_agencies	インスタンス上の交通機関を、ID、連絡先、サービスエリアとともに一覧表示します
onebusaway_find_stops	緯度／経度の近くにある停留所を検索します。任意で停留所コードによる絞り込みもできます
onebusaway_search_stops	停留所名またはコードから停留所 ID を特定します
onebusaway_get_stop	ID を指定して停留所を取得します
onebusaway_find_routes	緯度／経度の近くにある路線を検索します。任意で名前または番号による絞り込みもできます
onebusaway_search_routes	路線名または番号から路線 ID を特定します
onebusaway_get_route	ID を指定して路線を取得します
onebusaway_list_routes_for_agency	交通機関が運行するすべての路線を一覧表示します
onebusaway_get_arrivals	停留所のリアルタイム到着・出発情報を、ダイヤとの差、車両位置、有効なアラートとともに取得します
onebusaway_get_stop_context	1 回の上流リクエストで、停留所の詳細、リアルタイム到着情報、停留所に関連するすべてのアラートの詳細を取得します
onebusaway_get_alert	状況 ID を指定して、サービスアラートの詳細を取得します
onebusaway_get_trip	運行便のリアルタイム状況と停留所の順序を取得します
onebusaway_get_block	1 台の車両が運行日に運行するすべての運行便を、停車時刻とともに順番に取得します
onebusaway_get_vehicles	交通機関の運行中の車両のリアルタイム位置を取得します。任意で路線を 1 つ指定できます
onebusaway_get_schedule_for_stop	停留所の終日出発時刻表を、路線と方向別に取得します
onebusaway_get_schedule_for_route	路線の終日ダイヤを、すべての運行便と停留所の順序とともに取得します

リソース

リソース	説明
onebusaway://stop/{stopId}	停留所のメタデータ：名称、座標、停車する路線、車椅子での利用可否
onebusaway://route/{routeId}	路線のメタデータ：略称、説明、交通機関、ダイヤ URL

同じデータは、ツールのみを利用するクライアントでも onebusaway_get_stop と onebusaway_get_route を通じて利用できます。

機能リファレンス

onebusaway_list_agencies _ツール

• 入力は不要です。id、連絡先、timezone、coverageCenter／coverageSpan を含むすべての交通機関を返します
• limitExceeded は、上流で上限が適用された一覧であることを示します。残りを取得するページネーション機能はありません

---

onebusaway_find_stops _ツール

• lat／lon は必須です。radius はメートル単位で、デフォルトは 300、最大は 1600 です。任意の query で標識に表示された停留所コードに一致する停留所を検索できます
• 各停留所には id、code、direction、routeIds、wheelchairBoarding（ACCESSIBLE／NOT_ACCESSIBLE／UNKNOWN）が含まれます。limitExceeded は、範囲内にほかの停留所があることを示します

---

onebusaway_search_stops _ツール

• query（停留所名の一部または停留所コード）は必須です。maxCount は最大 100、デフォルトは 10 です
• onebusaway_find_stops と同じ停留所形式を返します。limitExceeded は、maxCount を超える数の停留所が一致したことを示します

---

onebusaway_get_stop _ツール

• stopId を 1 つ指定します。name、code、座標、direction、routeIds、wheelchairBoarding を返します
• 不明な ID は stop_not_found エラーになります。onebusaway_find_stops または onebusaway_search_stops を使って再試行できます

---

onebusaway_find_routes _ツール

• lat／lon は必須です。radius はメートル単位で、デフォルトは 500、最大は 1600 です。代わりに latSpan と lonSpan の両方を指定して範囲を設定することもできます。任意の query で路線名または番号を検索できます
• 各路線には shortName、longName、agencyId、GTFS の type（0=路面電車 … 5=ケーブルカー）、color、ダイヤの url が含まれます。limitExceeded は、範囲内にほかの路線があることを示します

---

onebusaway_search_routes _ツール

• query（路線名または番号）は必須です。maxCount は最大 100、デフォルトは 10 です
• shortName、longName、agencyId、GTFS の type を返します。limitExceeded は、maxCount を超える数の路線が一致したことを示します
• Puget Sound を含む、路線検索エンドポイントが 404 を返すインスタンスでは endpoint_unavailable エラーになります。その場合は代わりに onebusaway_find_routes または onebusaway_list_routes_for_agency を使用してください

---

onebusaway_get_route _ツール

• 単一の routeId を指定します。shortName、longName、description、agency、GTFS の type、color、スケジュールの url を返します
• 不明な ID の場合は route_not_found エラーになり、onebusaway_find_routes または onebusaway_search_routes で再検索できます

---

onebusaway_list_routes_for_agency _ツール

• agencyId は必須です。不明な agency の場合は agency_not_found エラーになります
• shortName、longName、GTFS の type、color、url を含むすべてのルートを返します。limitExceeded は、ページネーションなしで上流によってリストが上限に達したことを示します

---

onebusaway_get_arrivals _ツール

• stopId は必須です。対象時間帯は minutesBefore（整数、0～60、デフォルトは5）／minutesAfter（整数、0～240、デフォルトは35）です。より長い時間範囲を調べるには onebusaway_get_schedule_for_stop を使用します。不明な停留所の場合は stop_not_found エラーになります
• 各到着情報には、predicted（false は時刻表のみ）、秒単位の scheduleDeviation（正の値は遅延を表し、predicted が true の場合のみ有効）、predictedArrivalTime、vehiclePosition、stopsAway、tripId が含まれます
• 有効なアラートは situations[] に含まれます。停留所自体に適用されるものと、各到着情報の situationIds から参照されるものが、それぞれ一度ずつ含まれます

---

onebusaway_get_stop_context _ツール

• 入力と stop_not_found／rate_limited エラーは onebusaway_get_arrivals と同じです。1回の呼び出しで上流リクエストを1回送信します
• stop（routeIds を除いた onebusaway_get_stop のフィールド）、onebusaway_get_arrivals と同じ形式の arrivals、onebusaway_get_alert と同じ形式の alerts を返します。アラートには、停留所に適用されるものと対象時間帯の到着情報に適用されるものがすべて含まれます。到着情報に含まれていなくても、停留所全体に適用されるアラートは含まれます
• 上流のレスポンスに停留所が含まれない場合、stop は null になります。参照されたアラートがレスポンスにない場合、そのアラートは省略されます。いずれの場合も、取得に使うツールを示す notice が含まれます

---

onebusaway_get_alert _ツール

• onebusaway_get_arrivals の situationId（situations[].id または arrivals[].situationIds）を1つ指定します。不明な ID の場合は situation_not_found エラーになります
• TPEG の reason コード、severity、consequenceMessage、affects（agency、route、stop、trip の適用範囲）、迂回先の停留所 ID を含む consequences、activeWindows を返します

---

onebusaway_get_trip _ツール

• tripId は必須です。serviceDateMs（負でない整数、現地時間の午前0時）は、前の運行日の便の場合にのみ指定します。includeSchedule（デフォルトは true）を指定すると、GTFS 時刻と distanceAlongTripMeters を含む停車順序が追加されます
• status には phase（例：in_progress、layover_before）、predicted、position、scheduleDeviation、nextStop が含まれます。blockId（該当便にブロックがない場合は null）は onebusaway_get_block に渡します
• 指定された運行日に便が運行中でない場合は trip_not_found エラーになります。運行を終えた便の時刻は onebusaway_get_schedule_for_route から取得します

---

onebusaway_get_block _ツール

• onebusaway_get_trip から取得した blockId を1つ指定します。不明な ID の場合は block_not_found エラーになります
• トップレベルの trips、activeServiceIds、inactiveServiceIds は、最初に返された設定を表します。alternateConfigurations には、残りのすべての設定が順番どおりに保持されます。Service ID はカレンダー上の条件を表すもので、今日その設定が運行されることを示すものではありません
• 各便には distanceAlongBlock、accumulatedSlackTime（停車時間を秒で表したもの）、blockStopTimes が含まれます。任意の tripId または departureFromSec／departureBeforeSec を指定すると、各設定内で完全な便を個別に選択し、該当便のない設定も空のまま保持します
• セレクターを指定した場合、selection.total／returned は各設定における便の出現回数を数えます。configurationCounts[0] はトップレベルの設定を表し、その後に代替設定ごとのエントリが続きます

例：{"blockId":"<blockId from onebusaway_get_trip>","departureFromSec":86400,"departureBeforeSec":90000} は、24:00以上25:00未満に出発する便を選択し、完全な停車順序を保持します。

onebusaway_get_vehicles _ツール

• agencyId は必須です。不明な事業者を指定すると agency_not_found で失敗します。省略可能な routeId は、事業者の全車両を取得した後、クライアント側で絞り込みます
• 各車両には position、orientation、phase、scheduleDeviation、tripId、nextStop、predicted（リアルタイム GPS の報告）が含まれます。ページネーションがなく、上流でリストが上限に達した場合は limitExceeded で示されます
• tripId は運行中の便を優先し、路線と行先表示のメタデータはその便からのみ解決されます。orientation は東を 0 とする反時計回りの角度（0＝東、90＝北、180＝西、270＝南）を保持し、方位角ではありません
• 緯度または経度が欠落しているレコードはスキップされます。omittedWithoutPosition は事業者全体で該当する件数を数え、路線で絞り込む場合の omittedWithoutPositionOnRoute は、路線との一致が解決されたレコードの件数を数えます。これらの件数は、上流での切り詰めとは独立しています

---

onebusaway_get_schedule_for_stop _ツール

• stopId は必須です。省略可能な date は実在する YYYY-MM-DD 形式の暦日で、省略または空欄の場合は事業者のタイムゾーンにおける今日が既定値です。不明な停留所を指定すると stop_not_found で失敗します
• 出発便は路線と方向ごとにグループ化され、それぞれに scheduledDepartureTime と tripId が含まれます
• serviceDateMs は上流のスケジュール日付マーカーを保持します。日付が省略または空欄の場合はクエリ時刻、明示的に日付を指定した場合はインスタンスのローカル時刻での午前0時です。運行日の境界に丸められることはありません
• 省略可能な routeId、departureFromMs、departureBeforeMs は AND 条件で組み合わされます。時刻の境界は 0 以上の整数の Unix ミリ秒で、下限は含み、上限は含みません。選択後の結果では、出発便がない方向／路線は省略されます。selection.total ／ returned は、選択前／選択後の出発便数を示します
• 静的な時刻表のみを対象とします。リアルタイムの予測は onebusaway_get_arrivals から取得できます

例：{"stopId":"1_75403","routeId":"1_100259","departureFromMs":1792882800000,"departureBeforeMs":1792886400000} は、指定された Unix 時刻の範囲内にあるその路線の出発便を選択します。

---

onebusaway_get_schedule_for_route _ツール

• routeId は必須です。date は省略可能で、実在する YYYY-MM-DD 形式の暦日を指定します。省略または空欄の場合は今日がデフォルトです。不明なルートは route_not_found として失敗します
• 当日のすべての便について、tripId、tripHeadsign、serviceId と停車順序を返します
• serviceDateMs は上流のルートの scheduleDate を保持し、スケジュールの運行日を示します
• ルート、停留所、行先表示、運行メタデータは、まず参照情報から解決します。参照フィールドがない場合や空の場合は、従来のメタデータおよびグループ化によるフォールバックを使用します
• 省略可能な tripId、または departureFromSec／departureBeforeSec を指定すると、時間区間内に出発時刻が含まれる便全体を選択します。境界値は、午前0時からの GTFS 秒数を表す0以上の整数で、86400を超える値も指定できます。下限は含み、上限は含みません。selection.total／returned は選択前／選択後の便数を示します
• 静的なスケジュールのみを対象とします。リアルタイムの予測は、停留所で onebusaway_get_arrivals を使用して取得します

例：{"routeId":"1_100259","departureFromSec":28800,"departureBeforeSec":32400} は、08:00以上09:00未満に出発時刻が含まれる便を選択します。

ルートおよびブロックのスケジュールでは、空白以外の tripId と出発時刻の境界値を同時に指定できません。省略可能なIDが空欄の場合は未指定として扱います。どちらの境界値も省略でき、両方を指定する場合は下限より上限を大きくする必要があります。セレクターを指定しない場合、3つのツールはすべて、選択メタデータやデフォルトの上限を設けず、マッピング済みの応答全体を返します。選択件数は上流から返された応答のみを対象とし、上流で省略された運行分は含みません。一致件数が0件の場合も成功として扱い、通知を返します。

到着情報、停留所のコンテキスト、便、車両、スケジュール、アラートには、検証済みの IANA timezone が含まれます。エポック時刻と日付見出しには、そのタイムゾーンが明示されます。停留所ツールでは照会した停留所の事業者名前空間を、車両では指定した事業者を、便／ルートのスケジュールでは参照先ルートの事業者を使用します。各アラートでは、それぞれの事業者、ルート、便、停留所のスコープを解決し、すべてのスコープが解決されて一致する場合にのみ、そのタイムゾーンを使用します。タイムゾーンがない場合、無効な場合、解決できない場合、または競合する場合は、追加リクエストを行わず UTC を使用します。エポック値と GTFS 秒数は、スケジュール時刻が 24:00 を超える場合も含め、変更しません。

---

onebusaway://stop/{stopId} _リソース

• application/json 形式の停留所レコードです。onebusaway_get_stop が返すものと同じ形です
• stopId は onebusaway_find_stops または onebusaway_search_stops から取得します

---

onebusaway://route/{routeId} _リソース

• application/json 形式のルートレコードです。onebusaway_get_route が返すものと同じ形です
• routeId は onebusaway_find_routes または onebusaway_search_routes から取得します

機能

@cyanheads/mcp-ts-core を基盤としており、stdio と Streamable HTTP のトランスポート、切り替え可能な認証（none／jwt／oauth）、入れ替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを備えています。

OneBusAway 固有の機能：

• onebusaway-sdk をラップし、型付きのエラー分類（NotFound、RateLimited、上流からの 400 に対する ValidationError、ServiceUnavailable）を提供します。
• Puget Sound インスタンス（api.pugetsound.onebusaway.org）をデフォルトで使用します。このインスタンスでは開発用に ONEBUSAWAY_API_KEY=TEST が利用できます。ONEBUSAWAY_BASE_URL を設定すると、ほかの OneBusAway インスタンスを指定できます。
• 停留所 ID と路線 ID は代理店 ID を接頭辞に付けた形式です（{agencyId}_{localId}。停留所 1_75403、路線 1_100259）。代理店 ID は接頭辞のみです（Metro Transit は 1、Sound Transit は 40）。
• ONEBUSAWAY_RATE_LIMIT_* で設定する単一のペーサーが、API キーの上限に対して上流へのすべてのリクエストをキューに入れます。待機上限時間内に枠を確保できなかった呼び出しは、どのツールでも再試行可能な rate_limited として失敗し、data.retryAfter が返されます。
• 乗換データのみを扱い、経路検索は行いません。サーバーレベルの指示により、エージェントは ID 形式と一般的な検索の流れを確認できます。

エージェントが扱いやすい出力：

• すべての到着情報、便、車両に含まれる predicted により、GPS 追跡データと時刻表のみの予測を区別できます。
• 機械可読な時刻：scheduleDeviation は秒単位、到着時刻、停留所の時刻表、更新時刻は Unix ミリ秒単位、便、路線の時刻表、ブロックの停車時刻は GTFS の午前0時からの秒数です。
• 連携可能な ID：停留所ツールの stopId は到着情報の取得に、tripId は onebusaway_get_trip に、blockId は onebusaway_get_block に、situationIds は onebusaway_get_alert に、agencyId は車両の取得と路線一覧に使用できます。
• 次に呼び出すツールを示す復旧ヒントを含む、型付きエラーコントラクトを提供します。また、結果が空または切り詰められた場合は notice が付与されます。

はじめに

公開ホストインスタンス

公開インスタンスは https://onebusaway.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を介して、任意の MCP クライアントから接続してください。

{
  "mcpServers": {
    "onebusaway-mcp-server": {
      "type": "streamable-http",
      "url": "https://onebusaway.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。Puget Sound インスタンスでは、登録なしで ONEBUSAWAY_API_KEY=TEST を利用できます。

{
  "mcpServers": {
    "onebusaway-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/onebusaway-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "ONEBUSAWAY_API_KEY": "TEST"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "onebusaway-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/onebusaway-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "ONEBUSAWAY_API_KEY": "TEST"
      }
    }
  }
}

または Docker を使用します。

{
  "mcpServers": {
    "onebusaway-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "ONEBUSAWAY_API_KEY=TEST",
        "ghcr.io/cyanheads/onebusaway-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動してください。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 ONEBUSAWAY_API_KEY=TEST bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• OneBusAway API キー。開発用には Puget Sound インスタンスで TEST を利用できます。本番環境での使用やほかのインスタンスを利用する場合は、該当する代理店の開発者ポータルで登録してください。

インストール

1. リポジトリをクローンします。

git clone https://github.com/cyanheads/onebusaway-mcp-server.git

2. ディレクトリに移動します。

cd onebusaway-mcp-server

3. 依存関係をインストールします。

bun install

4. 環境を設定します。

cp .env.example .env
# edit .env — set ONEBUSAWAY_API_KEY if needed

設定

変数	説明	デフォルト
ONEBUSAWAY_API_KEY	OneBusAway API キーです。Puget Sound インスタンスでは TEST を使用できます。	TEST
ONEBUSAWAY_BASE_URL	OneBusAway インスタンスのベース URL です。	https://api.pugetsound.onebusaway.org
ONEBUSAWAY_RATE_LIMIT_REQUESTS	ウィンドウごとに許可される上流リクエスト数です。すべての呼び出し元で共有されます。	20
ONEBUSAWAY_RATE_LIMIT_WINDOW_MS	スライディングレートウィンドウの幅（ミリ秒）です。	60000
ONEBUSAWAY_RATE_LIMIT_MAX_WAIT_MS	rate_limited として失敗するまでに、呼び出しがスロットを待つ最長時間（ミリ秒）です。SDK の 60 秒のリクエストタイムアウト未満にしてください。	45000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http です。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto です。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth です。	none
MCP_LOG_LEVEL	ログレベル（debug、info、notice、warning、error）です。	info
LOGS_DIR	ログファイルのディレクトリです（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1 です。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

オプションの上書き設定の全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• チェックとテストを実行する：

  bun run devcheck       # Lint, format, typecheck, security, changelog sync
  bun run test           # Vitest test suite
  bun run test:coverage  # Test suite with coverage, held to the framework thresholds
  bun run lint:mcp       # Validate MCP definitions against spec
  

Docker

docker build -t onebusaway-mcp-server .
docker run --rm -e ONEBUSAWAY_API_KEY=TEST -p 3010:3010 onebusaway-mcp-server

Dockerfile のデフォルトは、HTTP トランスポート、ステートレスセッションモード、/var/log/onebusaway-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツールとリソースを登録し、サーバーの指示を設定して、OneBusAway サービスを初期化します。
src/config	Zod を使用した、サーバー固有の環境変数の解析と検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）と、それらが共有するスキーマおよびフォーマット用ヘルパーです。
src/mcp-server/resources	停留所とルートのリソース定義（*.resource.ts）です。
src/services/onebusaway	OneBusAway サービスです。onebusaway-sdk をラップし、上流リクエストのペース配分、エラー分類、ドメイン型の処理を行います。
tests/	ツール、リソース、サービス、設定を対象とする Vitest テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch を記述しないでください。
• リクエストスコープのログには ctx.log、テナントスコープのストレージには ctx.state を使用してください。
• src/index.ts の createApp() 配列に、新しいツールとリソースを登録してください。
• 外部 API 呼び出しをラップする際は、生データを検証し、ドメイン型に正規化してから、出力スキーマに従って返してください。不足しているフィールドを捏造しないでください。

コントリビューション

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。

デフォルトの Puget Sound OneBusAway API からの交通データは、Sound Transit と King County Metro が運営しており、Sound Transit Transit Data Terms of Use に準拠します。ホストされたエンドポイントの利用者も、これらの条件に基づいてデータを受け取ります。主な義務は次のとおりです。

• 条項 2：利用状況の指標は、請求に応じて提供されます。
• 条項 3：データは OneBusAway API からリアルタイムで取得され、リクエストサイクルを超えて変更またはキャッシュされることはありません。
• 条項 4：このデータを提供する利用者に対し、実質的に同様の条件を適用することに同意するものとします。
• 条項 7：このサーバーは、名称やブランディングに Sound Transit の商標を使用しません。