Lviv Public Transport

Timetable API Node

リヴィウの交通機関の時刻表データを提供する、読み取り専用 MCP エンドポイント付きの Express ベース API です。

要件

• Node.js 26（.nvmrcを参照）

ローカルで実行

nvm use
npm install
cp .env.dist .env
make import   # first run, and whenever the GTFS feed changes
make start

make importは静的GTFSフィード（gtfs-import-config.json）をダウンロードし、サーバーが読み込む2つのストアを書き込みます。database/Timetable（LokiJS：停留所、路線、形状、始発停留所の時刻表）とdatabase/gtfs（SQLite：便とカレンダー）です。どちらもGitの追跡対象外のため、新規にクローンした直後は実行するまでデータがありません。 make import-slimはSQLiteの軽量テーブルのみを再インポートし、database/Timetableには変更を加えません。

設定

すべての変数は省略可能です。.env.distを参照してください。

テスト

nvm use && make test

TypeScript

コードはTypeScriptで書かれており、Node組み込みの型ストリッピング機能を使って.tsソースから直接実行されます。サーバー、GTFSインポート、スクリプトのいずれにもビルド手順はありません。そのため、消去可能な構文のみを使用し（enum、namespace、パラメータープロパティは不可）、型のみのインポートにはimport typeを使い、相対インポートでは.tsファイルを指定します。tsconfig.jsonがこれら3つすべてを適用します。

npm run typecheck   # tsc, no emit

npm run buildは、公開対象のbinであるmcp/stdio.jsだけを出力します。Nodeはnode_modules内の型をストリッピングしないため、npmパッケージにはJavaScriptを含める必要があります。この処理はnpm pack／npm publishで実行され、出力ファイルはコミットされません。

public/stopOverrides.jsはブラウザーにそのまま配信されるため、JavaScriptのままにして、JSDocを使って型チェックします。

監視

New Relic APM は、NEW_RELIC_LICENSE_KEY が設定されていない場合は無効です。エラーと、utils/metrics.ts を通じて記録されるカスタムメトリクスも送信します。

New Relic はプリロードされたエージェントとして実行されるため、npm start には次のフラグが含まれます。

node -r dotenv/config -r newrelic --import newrelic/esm-loader.mjs index.ts

エージェントが設定を読み込む前に .env を読み込めるよう、dotenv/config を最初にプリロードします。設定ファイルは newrelic.cjs です（エージェントは CommonJS ですが、このプロジェクトは ESM です）。このファイルにシークレットは含まれず、キーは環境変数から取得します。rules.ignore により、/health はトランザクションから除外されます。

アカウントは EU リージョンにあります。ライセンスキーは eu01xx で始まり、エージェントはこのプレフィックスからコレクターを選択します。NRAK-... ユーザー API キーではなく、40 文字の取り込み用ライセンスキーを使用してください。

Cloud Run は Secret Manager からキーを読み込みます。

gcloud run services update timetable-api-node --region=europe-north1 --project=timetable-252615 --set-secrets=NEW_RELIC_LICENSE_KEY=new-relic-license-key:latest

MCP サーバー

このサービスは、Streamable HTTP 経由で読み取り専用の公開 MCP エンドポイントを提供します。

• MCP エンドポイント：/mcp
• サーバーカード：/.well-known/mcp/server-card.json
• 検出ヒント：/robots.txt（非標準のコメントヒント）

本番環境へのデプロイ（Cloud Run については cloudbuild.yaml を参照）では、api.lad.lviv.ua から REST と MCP を提供します。メインサイトの lad.lviv.ua は公共交通機関のウェブサイトです（このリポジトリでは、API ホスト用ではなく人向けに、HTML サイトマップとテーブルから引き続きリンクしています）。ローカルで実行する場合は、独自のオリジンを使用してください。

LLM と /mcp のフロー

MCP クライアント（Claude、Cursor、または MCP SDK）は、Streamable HTTP 経由で POST /mcp に JSON-RPC リクエストを送信します。ツールハンドラーは、REST API と同じ Express アクションを再利用し、LokiJS の時刻表データ、GTFS SQLite（gtfs 経由）、および ライブ GTFS-RT フィード（例：track.ua-gis.com）を利用します。

graph LR;
  Client[LLM or MCP client] -->|JSON-RPC Streamable HTTP| Mcp["POST /mcp"];
  Mcp --> Tools[Tool handlers];
  Tools --> Actions[Express actions];
  Actions --> Loki[(LokiJS)];
  Actions --> Gtfs[(GTFS SQLite)];
  Actions --> Rt[GTFS-RT upstream];
  Loki --> Actions;
  Gtfs --> Actions;
  Rt --> Actions;
  Actions --> Tools;
  Tools --> Mcp;
  Mcp -->|MCP tool result| Client;

ライブ API を試す

MCP Inspector（ローカル）： npx @modelcontextprotocol/inspector を実行し、トランスポートとサーバー URL があらかじめ入力された UI を開きます（Inspector README より）。

http://localhost:6274/?transport=streamable-http&serverUrl=https%3A%2F%2Fapi.lad.lviv.ua%2Fmcp

curl -s https://api.lad.lviv.ua/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_stop_realtime","arguments":{"stop_id":101}}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_stop_realtime",
    "arguments": { "stop_id": 101 }
  }
}

{
  "view": "transit_realtime",
  "data": { "...": "tool-specific payload" },
  "ui_blocks": [
    { "type": "map", "data": { "center": [49.84, 24.03], "zoom": 14, "layers": { "stops": "data.stop", "vehicles": "data.arrivals" } } },
    { "type": "arrival_list", "data": { "source": "data.arrivals" } }
  ]
}

公開されているツール

すべてのツールは読み取り専用です。停留所 ID は停留所標識に記載された数値コードで、文字列（"707"）として返されます。路線名は車両に表示された短縮名（"Т30"、"А1"）です。ラテン文字の "T30"／"A01" も使えます。数字だけを指定すると、内部路線 ID として扱われます。不明な路線または車両を指定すると、代わりに何を渡すべきかを示すヒントとともに isError: true が返されます。

{
  "view": "transit_realtime",
  "data": {
    "stop": { "id": "61", "name": "Площа Ринок", "lat": 49.84146, "lng": 24.03227 },
    "arrivals": [
      {
        "route": "Т02",
        "direction": "Пасічна",
        "vehicle_type": "tram",
        "arrival_minutes": 3,
        "vehicle_id": "2393",
        "lat": 49.83461,
        "lng": 24.01672,
        "bearing": 60
      }
    ],
    "updated_at": "2026-09-23T09:01:21Z"
  },
  "ui_blocks": [
    {
      "type": "map",
      "data": { "center": [49.84146, 24.03227], "zoom": 14, "layers": { "stops": "data.stop", "vehicles": "data.arrivals" } }
    },
    { "type": "arrival_list", "data": { "source": "data.arrivals" } }
  ]
}

{
  "view": "transit_realtime",
  "data": {
    "query": "rynok",
    "stops": [
      {
        "id": "61",
        "name": "Площа Ринок",
        "lat": 49.84146,
        "lng": 24.03227,
        "eng_name": "Rynok square",
        "routes": ["Т01", "Т02"]
      }
    ],
    "updated_at": "2026-09-23T09:36:53Z"
  },
  "ui_blocks": [
    { "type": "map", "data": { "center": [49.84146, 24.03227], "zoom": 14, "layers": { "stops": "data.stops" } } }
  ]
}

{
  "view": "transit_realtime",
  "data": {
    "from": { "id": "61", "name": "Площа Ринок", "stop_ids": ["10", "57", "58", "59", "61", "63", "855"] },
    "to": { "id": "118", "name": "Залізничний вокзал", "stop_ids": ["117", "118", "188", "189", "190", "191"] },
    "options": [
      {
        "route": "Т01",
        "vehicle_type": "tram",
        "direction": 0,
        "destination": "Залізничний вокзал",
        "board_stop": { "id": "58", "name": "Руська", "lat": 49.84186, "lng": 24.03408 },
        "alight_stop": { "id": "118", "name": "Залізничний вокзал", "lat": 49.839, "lng": 23.99677 },
        "stops_count": 8,
        "walk_to_board_meters": 137,
        "walk_from_alight_meters": 0
      }
    ],
    "transfer_options": [],
    "map_stops": [
      { "id": "58", "name": "Руська", "lat": 49.84186, "lng": 24.03408, "role": "board" },
      { "id": "118", "name": "Залізничний вокзал", "lat": 49.839, "lng": 23.99677, "role": "alight" }
    ],
    "updated_at": "2026-09-23T09:36:53Z"
  },
  "ui_blocks": [
    { "type": "map", "data": { "center": [49.84043, 24.01543], "zoom": 13, "layers": { "stops": "data.map_stops" } } }
  ]
}

transfer_optionsには、乗り換えがちょうど1回の経路が含まれます。2回以上の乗り換えはありません。各候補は2つのlegs（直通候補と同じフィールドですが、徒歩距離を除きます）とtransfer_walk_metersを持ちます。乗り換えは同じ停留所（0 m）でも、第1区間の終点から300 m以内にある任意の停留所でも可能です。そのため、広場や交差点周辺に停留所が集まっている場合、それらを1か所の乗り換え地点として利用できます。目的地まで直通する路線は、どちらの区間にも使われません。また、順位付けでは乗り換え1回につき停留所5つ分までの追加コストがかかります。直通経路がない場合、または直通経路の最良候補より優れている場合に、乗り換え候補を（最大5件）表示します。両方のリストが空の場合、移動には2回以上の乗り換えが必要です。

map_stopsには、最良の経路の停留所が乗車順に並びます（乗り換え候補が表示される場合は、その経路の停留所です。直通経路のどの候補よりも優れている場合にのみ表示されるためです）。各停留所にはroleがあり、board、transfer（同じ停留所での乗り換え）、transfer_alight + transfer_board（徒歩での乗り換え）、alightのいずれかです。mapブロックではこれらの停留所をプロットし、すべての停留所（乗り換え地点を含む）を囲む範囲を中心に表示します。範囲の大きさに応じてズームレベルは14～11です。

{
  "view": "transit_realtime",
  "data": {
    "route": { "name": "Т30", "long_name": "Університет - Городоцька - вул. Ряшівська", "color": "#EF88AA", "type": "trolleybus" },
    "stops": [
      [
        {
          "id": "101", "name": "Університет", "lat": 49.841, "lng": 24.003,
          "departures": ["05:30", "05:52"],
          "schedule": { "workday": ["05:30", "05:52", "06:10"], "saturday": ["07:00", "07:30"], "sunday": ["07:00"], "weekend": ["07:00", "07:30"] }
        },
        { "id": "707", "name": "Стадіон Сільмаш", "lat": 49.838, "lng": 24.021, "departures": [], "schedule": { "workday": [], "saturday": [], "sunday": [], "weekend": [] } }
      ],
      [
        { "id": "707", "name": "Стадіон Сільмаш", "lat": 49.838, "lng": 24.021, "departures": ["06:00"], "schedule": { "workday": ["06:00"], "saturday": [], "sunday": [], "weekend": [] } }
      ]
    ],
    "updated_at": "2026-09-23T09:01:12Z"
  },
  "ui_blocks": [
    { "type": "map", "data": { "center": [49.841, 24.003], "zoom": 13, "layers": { "stops": "data.stops" } } }
  ]
}

{
  "view": "transit_realtime",
  "data": {
    "route_name": "Т01",
    "destinations": ["Залізничний вокзал", "Погулянка"],
    "vehicles": [
      {
        "id": "5907",
        "direction": 0,
        "destination": "Залізничний вокзал",
        "next_stop": { "id": "118", "name": "Залізничний вокзал", "arrival": "2026-09-23T09:35:00.000Z" },
        "lat": 49.83947,
        "lng": 23.99566,
        "bearing": 126,
        "lowfloor": true
      }
    ],
    "updated_at": "2026-09-23T09:32:10Z"
  },
  "ui_blocks": [
    { "type": "map", "data": { "center": [49.83947, 23.99566], "zoom": 13, "layers": { "vehicles": "data.vehicles" } } }
  ]
}

{
  "view": "transit_realtime",
  "data": {
    "center_lat": 49.8419,
    "center_lng": 24.0316,
    "radius_meters": 500,
    "total": 18,
    "vehicles": [
      {
        "id": "3422",
        "route": "Т01",
        "vehicle_type": "tram",
        "direction": 0,
        "destination": "Залізничний вокзал",
        "lat": 49.84154,
        "lng": 24.03364,
        "bearing": 258,
        "lowfloor": false,
        "distance_meters": 152
      }
    ],
    "updated_at": "2026-09-23T09:32:10Z"
  },
  "ui_blocks": [
    { "type": "map", "data": { "center": [49.8419, 24.0316], "zoom": 15, "layers": { "vehicles": "data.vehicles" } } }
  ]
}

{
  "view": "transit_realtime",
  "data": {
    "vehicle_id": "5907",
    "route": "Т01",
    "license_plate": "1238",
    "lat": 49.83947,
    "lng": 23.99566,
    "bearing": 126,
    "direction": 0,
    "destination": "Залізничний вокзал",
    "upcoming_stops": [
      { "id": "118", "name": "Залізничний вокзал", "arrival": null, "departure": "2026-09-23T09:35:00.000Z" },
      { "id": "188", "name": "Приміський вокзал", "arrival": "2026-09-23T09:35:49.000Z", "departure": null }
    ],
    "updated_at": "2026-09-23T09:32:10Z"
  },
  "ui_blocks": [
    { "type": "map", "data": { "center": [49.83947, 23.99566], "zoom": 15, "layers": { "vehicles": "data" } } }
  ]
}

プロンプト

再利用可能な指示テンプレートです。stop_idは正の整数、または数字のみの文字列です。

リソースとリソーステンプレート

ツールに加えて、サーバーはツール呼び出しを必要としない参照データを リソース として公開しています。

timetable://route/{name} の {name} は completion/complete に対応しています（「t3」→「Т30」、「a1」→「А01」）。不明な停留所または路線を指定すると、JSON-RPC エラー -32002（リソースが見つかりません）が返されます。

セキュリティモデル

• 認証なしで公開読み取り専用です。
• データを変更するツールは公開されていません。
• POST /mcp は IP あたり毎分 60 リクエスト に制限されています（メモリ内で管理され、再起動時にリセットされます）。制限を超えたリクエストには、JSON-RPC エラーボディを伴う HTTP 429 が返されます。
• robots.txt はあくまで参考情報であり、プロトコル上の契約ではありません。

REST API

すべてのエンドポイントは JSON を返します。:code は数値の停留所コード、:name は路線の短縮名（例：T1、32A）または数値の外部 ID です。

停留所

GET /stops.json

すべての停留所をコード順に並べた JSON 配列です。

• レスポンス： { code, name, eng_name, location: [lat, lng], routes, sign, sign_pdf } の配列です。

（GET /stops は代わりに HTML テーブルを返します。）

停留所ごとの路線の上書き

停留所の上流データに含まれる路線一覧が、実際の状況と異なることがあります。GET /stops は、保存済みの上書きを Маршрути 列に適用します。削除された路線は赤色の取り消し線付きで、追加された路線は緑色で表示されます。また、その行の Табличка（停留所標識）列と Мапа（路線図ポスター、/:code/schema）列にある SVG および PDF のリンクには、対応する ?add=／?remove= が付加されます。offline.lad.lviv.ua と pdf.lad.lviv.ua はどちらもこの指定に対応しています。

路線列は常にクリックできます。路線をクリックすると削除または復元でき、「+」ボックスに路線を入力すると追加できます。

上書きはブラウザー自身の localStorage（public/stopOverrides.js を参照）に保存され、サーバーには保存されません。そのため、編集用アカウントもキャッシュの消去も必要なく、編集内容はただちに反映されます。ただし、その上書きが表示されるのは変更を行ったブラウザーだけであり、ほかの人が /stops を開いても表示されません。

/stops.json では、上書きを適用せずに sign と sign_pdf を返します。

GET /stops/:code

リアルタイムの時刻表を含む、単一の停留所の情報です。短時間キャッシュされます（5～10 秒）。

• 省略可能： skipTimetableData=1 — リアルタイムの到着情報を省略します（長時間キャッシュされるレスポンス）。
• レスポンス： { code, name, eng_name, latitude, longitude, transfers, timetable } です。

GET /stops/:code/timetable

停留所のリアルタイム時刻表のみを返します。短時間キャッシュされます（5～10 秒）。

• レスポンス： 時刻表アイテムの配列です。

GET /stops/:code/static

リアルタイムデータを含まない、停留所の静的情報です。長期間キャッシュされます（30 日）。

• レスポンス： { code, name, eng_name, latitude, longitude, transfers } です。

GET /closest?latitude={lat}&longitude={lng}

近隣の停留所を返します。MCP 以外のクライアント向けに、get_stops_around_location と同じ検索を行います。

• 省略可能： radius — メートル単位の半径です。50～3000 の範囲に制限されます（デフォルトは 1000）。
• レスポンス： { code, name, latitude, longitude, distance_meters } の JSON 配列です（距離順）。

路線

GET /routes.json

すべての路線を短縮名順に並べた JSON 配列です。

• 省略可能： full=1 — リスト項目の代わりに、時刻表ストア内の生の路線オブジェクト（運行データのマップ、経路形状、発車時刻のマップ。約 9 MB）を返します。
• レスポンス： { external_id, short_name, long_name, color, type, stops_by_shape } の配列です（約 20 KB）。stops_by_shape には、方向ごとの停留所コードが "0" と "1" をキーとして格納されています。

（GET /routes は HTML テーブルを返します。）

GET /routes/static/:name

路線の形状、停留所一覧、メタデータです。30日間の長期キャッシュが適用されます。

• レスポンス: { id, color, type, route_short_name, route_long_name, stops: [[dir0…], [dir1…]], shapes }。
• 各停留所オブジェクト: { code, name, loc, transfers, departures, schedule }。
  • departures — 本日の出発時刻（HH:MM）です。方向 0 の最初の停留所にのみ設定されます。後方互換性のために保持されています。
  • schedule — 日の種別ごとの出発時刻 { workday: string[], saturday: string[], sunday: string[], weekend: string[] } です（weekend = 土曜日 ∪ 日曜日、非推奨）。方向 0 の最初の停留所にのみ設定されます。

GET /routes/dynamic/:name

路線のリアルタイム車両位置です。10秒間の短期キャッシュが適用されます。

• レスポンス: { id, direction, location: [lat, lng], bearing, speed, lowfloor } の配列です。speed は GPS ユニットから取得した m/s 単位の速度で、報告されていない場合は null です。

車両

GET /vehicle/:vehicleId

車両1台のリアルタイム位置と、次の停留所への到着情報です。5秒間の短期キャッシュが適用されます。

• レスポンス: { location: [lat, lng], routeId, bearing, speed, direction, licensePlate, arrivals }。speed は GPS ユニットから取得した m/s 単位の速度で、報告されていない場合は null です。

GET /vehicle-by-plate/:plate

ナンバープレートから車両 ID を検索します。5秒間の短期キャッシュが適用されます。

• ナンバープレートの照合では大文字と小文字を区別せず、スペースとハイフンは無視されます（BC-1234-AA、bc 1234 aa、bc1234aa はすべて同じものとして扱われます）。
• レスポンス: { vehicleId } — 返された ID を GET /vehicle/:vehicleId で使用します。

GET /transport?latitude={lat}&longitude={lng}

指定地点から1 km以内の車両です。10秒間の短期キャッシュが適用されます。

• レスポンス: { id, route, routeId, direction, vehicle_type, color, location: [lat, lng], bearing, speed, lowfloor } の配列です。routeId は /routes/static/:name の :name として使用できます。direction は stops／shapes のインデックスに対応し（0 = 往路、1 = 復路、不明の場合は null）、speed は m/s 単位で、不明の場合は null です。

GET /disruptions?route={name}&stop={code}

市が発表した、本日有効な運休、迂回、停留所移設です。GTFS フィードには含まれていません。CDN で5分間キャッシュされます。

• data/disruptions.json で手動管理され、起動時とテスト時にスキーマとの照合が行われます。エントリの追加や編集はここで行い、デプロイしてください。エントリは since の日から until の日まで（キーウ時間）配信されるため、期限切れのエントリは自動的に非表示になります。
• route（キリル文字またはラテン文字の路線略称）と stop（数値のコード）は任意のフィルターです。いずれかを指定すると、それに該当するエントリのみが一覧表示されます。
• レスポンス: { disruptions, updated_at }。各項目: { id, kind, reason, since, until, until_text, routes, stops, alternatives, detour, note, source, url }。kind は suspended、detour、stop_moved、stop_closed のいずれかです。routes と alternatives は { name, id }（name は Т33 のような値、id は lad.lviv.ua の URL で使用されるラテン文字表記）です。detour は { via: [streets], skipped_stops: [codes] } または null です。

サービスとディスカバリー

デプロイ

本番環境は Cloudflare の背後にある Cloud Run（timetable-api-node、europe-north1、プロジェクト timetable-252615）で稼働しています。

• イメージ。 Dockerfile はビルド時に GTFS フィードをインポートします （gtfs-import.ts の後に scripts/slim-gtfs-db.ts が、サーバーが読み取らない SQLite テーブルを空にします）。そのため、各イメージには独自のデータスナップショットが含まれます。 last-modified.txt には、フィードの Last-Modified ヘッダーが記録されます。
• Cloud Build。 cloudbuild.yaml がイメージをビルド、プッシュ、デプロイします。 毎日のスケジュール実行では _DATA_REFRESH=1 を設定し、上流の static.zip がデプロイ済みリビジョン以降変更されていない場合は、ビルド全体をスキップします。
• 手動。 make deploy は linux/amd64 イメージをビルドしてプッシュし、デプロイします。make smoke は本番環境のエンドポイントをいくつか確認します。make clear-short-cache、 clear-long-cache、clear-all-cache は、キャッシュタグを使って Cloudflare のキャッシュを消去します。
• npm パッケージ。 make publish はパッチバージョンを上げ（server.json と openapi.yaml も同期します）、タグをプッシュします。そのタグによって .github/workflows/publish.yml が実行され、npm と MCP Registry に公開されます。 パッケージには timetable-mcp の stdio プロキシのみが含まれます。