Lviv Public Transport

io.github.vbhjckfd由 GitHub 帳號 vbhjckfd 發布v1.8.13更新於 Nov 7, 2026

Lviv public transport MCP: stops, timetables, routes, and live vehicle positions. No API key.

已驗證Streamable HTTP可網頁執行位置與生活資料與分析

概覽

AI 產生的概覽

利沃夫大眾運輸唯讀 MCP 端點:查詢站點、規劃行程、時刻表、即時到站、車輛位置與營運調整。

可以做什麼
  • 依名稱搜尋站點,或依地址、座標尋找附近站點
  • 查詢站點即時到站資訊,可篩選無障礙低地板車輛
  • 規劃兩地之間的直達或一次轉乘路線,含即時發車與時刻表估算
  • 查看路線詳情:雙向站點清單、首站時刻表,以及路線上的即時車輛與班距
  • 追蹤單一車輛,並列出某位置附近的車輛
  • 列出當日公告的停駛、改道與站點遷移
適用情境
適合讓助理回答利沃夫電車、無軌電車與公車的交通問題:下一班何時到、從 A 到 B 怎麼走、某路線或車輛現在在哪、道路施工是否影響某條路線。
執行需求
遠端 Streamable HTTP 端點,不需帳號、API 金鑰或請求標頭。用戶端須同時接受 application/json 與 text/event-stream。服務為無狀態,並依 IP 限流。
安裝前請注意
唯讀,不提供寫入類工具。即時位置與到站時間來自上游資料來源,可能缺漏或過時;標記為 scheduled 的到站是時刻表項目,並非實際車輛。改道與停駛不在 GTFS 資料中,需另行確認。行程時刻為估算值。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Lviv Public Transport,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.vbhjckfd%2Ftimetable-api-node/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "mcpServers": {
    "lviv-public-transport": {
      "type": "http",
      "url": "https://api.lad.lviv.ua/mcp"
    }
  }
}

README

Timetable API Node

[CI] [Node.js] [License: WTFPL] [MCP Registry]

Express-based API for Lviv transport timetable data with a read-only MCP endpoint.

[smithery badge] [vbhjckfd/timetable-api-node MCP server]

[timetable-api-node MCP server]

Requirements

  • Node.js 26 (see .nvmrc)

Run locally

bash
nvm usenpm installcp .env.dist .envmake import   # first run, and whenever the GTFS feed changesmake start

make import downloads the static GTFS feed (gtfs-import-config.json) and writes the two stores the server reads: database/Timetable (LokiJS: stops, routes, shapes, first-stop schedules) and database/gtfs (SQLite: trips and calendars). Both are gitignored, so a fresh clone has no data until it runs. make import-slim re-imports only the light tables into SQLite and leaves database/Timetable alone.

Configuration

All variables are optional; see .env.dist.

VariableDefaultPurpose
PORT8080HTTP port.
VEHICLES_LOCATION_URLhttps://track.ua-gis.com/gtfs/lviv/vehicle_positionGTFS-RT vehicle positions feed.
TRIP_UDPDATES_URLhttps://track.ua-gis.com/gtfs/lviv/trip_updatesGTFS-RT trip updates feed (the misspelling is the real name).
MCP_PUBLIC_BASE_URLhttps://api.lad.lviv.uaBase URL used in MCP metadata (icon URL).
NEW_RELIC_LICENSE_KEY—Enables New Relic APM (see Monitoring).
NEW_RELIC_APP_NAME, NEW_RELIC_LOG_LEVELtimetable-api-node, infoNew Relic agent settings.
PULSE_WORKER_URL, PULSE_SIGNAL_SECRET—Signal a Pulse worker on each /stops/:code/timetable request; both must be set.
MCP_URLhttps://api.lad.lviv.ua/mcpOnly for the timetable-mcp stdio proxy: the remote endpoint it forwards to.

Test

bash
nvm use && make test

TypeScript

The code is TypeScript and runs straight from the .ts sources under Node's built-in type stripping — there is no build step for the server, the GTFS import or the scripts. That means only erasable syntax (no enum, namespace or parameter properties), import type for type-only imports, and relative imports that name the .ts file; tsconfig.json enforces all three.

bash
npm run typecheck   # tsc, no emit

npm run build emits just mcp/stdio.js, the published bin: Node does not strip types inside node_modules, so the npm package has to ship JavaScript. It runs on npm pack/npm publish; the output is not committed.

public/stopOverrides.js is served to browsers as-is, so it stays JavaScript and is type-checked from its JSDoc.

Monitoring

New Relic APM, off unless NEW_RELIC_LICENSE_KEY is set. It also carries errors and the custom metrics recorded through utils/metrics.ts.

New Relic runs as a preloaded agent, so npm start carries the flags:

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

dotenv/config is preloaded first so .env is populated before the agent reads its configuration. The config file is newrelic.cjs (the agent is CommonJS and this project is ESM) and holds no secrets — the key comes from the environment. /health is excluded from transactions via rules.ignore.

The account is in the EU region; its license key starts with eu01xx and the agent picks the collector from that prefix. Use the 40-character ingest license key, not an NRAK-... user API key.

Cloud Run reads the key from Secret Manager:

bash
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 Server

This service exposes a public read-only MCP endpoint over Streamable HTTP. It speaks MCP revision 2026-07-28 (stateless: server/discover, a per-request _meta envelope, cacheable list results) and still serves 2025-era clients that open with initialize (2025-11-25 back to 2024-11-05).

  • MCP endpoint: /mcp
  • Server card: /.well-known/mcp/server-card.json
  • Discovery hint: /robots.txt (non-standard comment hint)

Production deployment (see cloudbuild.yaml for Cloud Run) serves REST and MCP from api.lad.lviv.ua. The main site lad.lviv.ua is the public transport website (this repo still links there in HTML sitemap and tables for people, not for the API host). Use your own origin when running locally.

LLM and /mcp flow

An MCP client (Claude, Cursor, or the MCP SDK) talks JSON-RPC over Streamable HTTP to POST /mcp. Tool handlers reuse the same Express actions as the REST API, backed by LokiJS timetable data, GTFS SQLite (via gtfs), and live GTFS-RT feeds (for example track.ua-gis.com).

mermaid
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;

Try the live API

[MCP server card] [REST stops.json] [REST routes.json]

MCP Inspector (local): run npx @modelcontextprotocol/inspector, then open the UI with transport and server URL prefilled (from the inspector README):

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

Postman / curl: call a tool on production

POST https://api.lad.lviv.ua/mcp with Content-Type: application/json and Accept: application/json, text/event-stream — the Streamable HTTP transport rejects a request that does not accept both. The server is stateless: there is no session, so tools/call works on its own without an initialize first. The response arrives as a single SSE event: message frame carrying the JSON-RPC result. This is the 2025-era request shape; a 2026-07-28 request also sends MCP-Protocol-Version: 2026-07-28 and Mcp-Method headers, plus io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in params._meta.

bash
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}}}'

Example tools/call body shape:

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

Successful tool responses return a natural-language text summary inside MCP content items (type: "text") — e.g. "Stop «Площа Ринок»: 6 arrivals. Next: Т02 → «Пасічна» in 3 min." The full structured payload is in the structuredContent field (for schema-aware clients). Each structuredContent payload follows one contract:

json
{  "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" } }  ]}

ui_blocks point into data instead of repeating it. A map block gives the centre and zoom, and layers maps stops, vehicles and polylines to a dot path in the result; every stop and vehicle there has lat/lng, vehicles also bearing. An arrival_list block names the arrivals array to render, already sorted by arrival_minutes (null = no ETA).

Exposed tools

All tools are read-only. Stop IDs are the numeric codes on stop signs, returned as strings ("707"). Route names are the short names on vehicles ("Т30", "А1"); Latin "T30"/"A01" work too, and a bare number is read as an internal route ID. An unknown route or vehicle returns isError: true with a hint on what to pass instead.

ToolArgumentsReturns
search_stopsquery (string, ≥ 2 chars), limit (1–25, default 10)Stops whose Ukrainian or English name contains every query word (inflection-tolerant: "опера" finds «Театр опери та балету»; punctuation and Latin look-alike letters are ignored, so "пл. ринок" and "Cихiв" match), with routes.
get_stops_around_locationlatitude, longitude, radius_meters (50–3000, default 1000)Stops near a point, nearest first, with distance_meters and routes.
get_stop_realtimestop_id, lowfloor_only (default false)Live arrivals: route, direction (destination), vehicle_type, arrival_minutes, vehicle position, lowfloor; scheduled: true marks timetable entries shown when no vehicle is predicted.
find_routes_betweenfrom_stop_id or from_lat + from_lng; to_stop_id or to_lat + to_lng; depart_at or arrive_by ("HH:MM" Lviv time or ISO 8601, default now)Routes within a 300 m walk of each stop end (600 m of a point), best first: direct options (board_stop, alight_stop, destination, stops_count, walk at each end) and transfer_options with exactly one interchange inside a 300 m stop cluster. Each option carries schedule (timetable estimate: leave_at, per-leg board_at/alight_at, arrive_at, total_minutes) and, when planning for now, next_departures (live, from the boarding stop). Suspended routes and stops a detour skips are left out; walk_meters when the ends are a short walk apart.
get_route_staticroute_name, include_shapes (default false)Name, type, colour, stop lists for both directions, first-stop timetable; polylines only on request.
get_route_realtimeroute_name, direction (0 or 1, optional)Vehicles on the route with destination and next_stop (id, name, ISO arrival); headways per direction: vehicle count, live gaps_minutes front to back, scheduled_headway_minutes.
get_nearby_vehicleslatitude, longitude, radius_meters (100–1000, default 500), route, limit (1–50, default 15), lowfloor_only (default false)Live vehicles nearest first, with destination and distance_meters; total counts all in range.
get_vehicle_infovehicle_idOne vehicle: position, route, destination, plate, upcoming stops (id, name, ISO times) not yet passed.
get_disruptionsroute, stop_id (both optional)Announced closures, detours (detour.via streets) and moved stops in force today. get_stop_realtime, get_route_static, get_route_realtime and find_routes_between also add a disruptions array when one touches their routes or stops.
get_stop_realtime — example
json
{  "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" } }  ]}
search_stops — example
json
{  "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" } } }  ]}

One stop name usually covers both sides of the street under different IDs; each is returned, and routes tells them apart. get_stops_around_location returns the same stop objects plus distance_meters.

find_routes_between — example

Text summary: "3 direct routes «Площа Ринок» → «Залізничний вокзал». Best: Т01 towards «Залізничний вокзал», 8 stops, board at «Руська» (137m walk)."

json
{  "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" } } }  ]}

Each end covers every stop within a 300 m walk (stop_ids): a line's two directions often stop on opposite sides of a street under different names, as here, where Т01 towards the station leaves from «Руська», not «Площа Ринок». Options are ranked by stops plus walking (150 m of walking weighs as one stop), one per route and direction. A direction's last stop counts as a place to get off, not to board.

transfer_options hold trips with exactly one interchange, never more. Each has two legs (same fields as a direct option, minus the walks) and transfer_walk_meters: the interchange may be the same stop (0) or any stop within 300 m of where the first leg ends, so a cluster of stops around a square or junction works as one interchange. A line that already reaches the destination directly is never used as either leg, and a transfer costs as much as 5 extra stops in the ranking. Transfer options are listed (up to 5) when there is no direct route, or when they beat the best direct one. Both lists empty means the trip needs two or more transfers.

map_stops is the best trip's stops in riding order (a transfer option when one is listed, since those only appear when they beat every direct one), each with a role: board, transfer (same-stop interchange) or transfer_alight + transfer_board (walking interchange), and alight. The map block plots them, centred on the box around all of them (interchange included) with zoom 14–11 by its size.

get_route_static — example
json
{  "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" } } }  ]}

stops[0] is direction 0 (outbound), stops[1] direction 1 (return). departures and schedule are populated for the first stop of each direction; other stops have empty arrays. schedule.workday is Monday–Friday, schedule.saturday / schedule.sunday the two weekend days (they can differ); schedule.weekend merges both and is kept for backward compatibility; departures keeps today's schedule for backward compatibility. With include_shapes: true, data.shapes holds one [lat, lng] polyline per direction and the map block adds "polylines": "data.shapes".

get_route_realtime — example
json
{  "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" } } }  ]}

route_name is the canonical short name whatever form was passed. direction indexes get_route_static's stops (0 = outbound, 1 = return) and destinations. next_stop is null when the feed has no trip update for the vehicle.

get_nearby_vehicles — example
json
{  "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" } } }  ]}
get_vehicle_info — example
json
{  "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" } } }  ]}

route is the route short name, falling back to the opaque GTFS route ID only when the route is missing from the local data. Either value is accepted as route_name by get_route_static and get_route_realtime. license_plate is null when the feed has none.

Prompts

Reusable instruction templates. stop_id is a positive integer or digits-only string.

PromptArgumentsUse case
plan-tripfrom, toRoutes between two named places (or stop IDs), direct or with one transfer, with live departures from the boarding stop.
route-statusroute_nameWhere a route's vehicles are right now, by direction. route_name supports completion.
transit-map-viewstop_idMap-first rendering of live vehicles for a stop.
transit-arrival-liststop_idArrival list for a stop, sorted by ETA and grouped by route.
transit-hybrid-viewstop_idMap block first, arrival-list block second, with ETA values kept consistent across both.

Resources and resource templates

In addition to tools, the server exposes MCP resources for reference data that doesn't require a tool call:

URIDescription
timetable://aboutScope, usage, and data caveats for this server (Markdown)
timetable://reference/toolsTools reference table (Markdown)
timetable://reference/promptsPrompt templates catalog (Markdown)
timetable://stop/{code}Static info for a stop by numeric code — name, coordinates, serving routes (JSON)
timetable://route/{name}Static metadata for a route by short name — color, type, stop counts (JSON)

{name} in timetable://route/{name} supports completion/complete ("t3" → "Т30", "a1" → "А01"). Unknown stops or routes fail with JSON-RPC error -32602 and data.uri (resource not found, per MCP 2026-07-28).

Security model

  • Public read-only (no authentication).
  • No mutating tools are exposed.
  • POST /mcp is rate-limited to 60 requests/min per IP (in-memory, resets on restart). Excess requests receive HTTP 429 with a JSON-RPC error body.
  • Requests carrying X-Internal-Key equal to the INTERNAL_API_KEY env var (the lad.lviv.ua frontend server) skip every rate limit.
  • robots.txt is only a best-effort discovery hint and not a protocol contract.

REST API

All endpoints return JSON. :code is a numeric stop code; :name is a route short name (e.g. T1, 32A) or numeric external ID.

Stops

GET /stops.json

All stops as a JSON array, sorted by code.

  • Response: array of { code, name, eng_name, location: [lat, lng], routes, sign, sign_pdf }.

(GET /stops returns an HTML table instead.)

Per-stop route overrides

The upstream route list for a stop is sometimes behind reality. GET /stops applies a stored override to its Маршрути column — removed routes shown red and struck through, added ones green — and hangs the matching ?add=/?remove= on that row's SVG and PDF links in the Табличка (stop sign), Мапа (network poster, /:code/schema) and Панель (/:code/panel) columns, which offline.lad.lviv.ua and pdf.lad.lviv.ua both understand.

The route column is always clickable: click a route to drop or restore it, type one into the + box to add it.

Overrides live in the browser's own localStorage (see public/stopOverrides.js), not on a server — no account to edit through, no cache to purge, an edit applies at once. The trade is scope: an override is visible only in the browser that made it, not to anyone else who opens /stops.

/stops.json reports sign and sign_pdf without overrides applied.

GET /stops/:code

Single stop with live realtime timetable. Short-cached (5–10 s).

  • Optional: skipTimetableData=1 — omit live arrivals (long-cached response).
  • Response: { code, name, eng_name, latitude, longitude, transfers, timetable }.
GET /stops/:code/timetable

Live timetable only for a stop. Short-cached (5–10 s).

  • Response: array of timetable items.
GET /stops/:code/static

Static stop info without live data. Long-cached (30 days).

  • Response: { code, name, eng_name, latitude, longitude, transfers }.
GET /closest?latitude={lat}&longitude={lng}

Nearby stops — same search as get_stops_around_location, for non-MCP clients.

  • Optional: radius — meters, clamped between 50 and 3000 (default 1000).
  • Response: JSON array of { code, name, latitude, longitude, distance_meters } (sorted by distance).

Routes

GET /routes.json

All routes as a JSON array, sorted by short name.

  • Optional: full=1 — raw route objects from the timetable store (trip maps, shapes, departure maps; ~9 MB) instead of the list fields.
  • Response: array of { external_id, short_name, long_name, color, type, stops_by_shape } (~20 KB). stops_by_shape holds stop codes per direction, keyed "0" and "1".

(GET /routes returns an HTML table.)

GET /routes/static/:name

Route shape, stop list, and metadata. Long-cached (30 days).

  • Response: { id, color, type, route_short_name, route_long_name, stops: [[dir0…], [dir1…]], shapes }.
  • Each stop object: { code, name, loc, transfers, departures, schedule }.
    • departures — today's departure times (HH:MM), populated only for direction 0 first stop. Kept for backward compatibility.
    • schedule — { workday: string[], saturday: string[], sunday: string[], weekend: string[] } departure times by day type (weekend = Saturday ∪ Sunday, deprecated), populated only for direction 0 first stop.
GET /routes/dynamic/:name

Live vehicle positions for a route. Short-cached (10 s).

  • Response: array of { id, direction, location: [lat, lng], bearing, speed, lowfloor }. speed is m/s from the GPS unit, or null when not reported.

Vehicles

GET /vehicle/:vehicleId

Live position and upcoming stop arrivals for one vehicle. Short-cached (5 s).

  • Response: { location: [lat, lng], routeId, bearing, speed, direction, licensePlate, arrivals }. speed is m/s from the GPS unit, or null when not reported.
GET /vehicle-by-plate/:plate

Look up a vehicle ID by its license plate. Short-cached (5 s).

  • The plate is matched case-insensitively with spaces and dashes ignored (BC-1234-AA, bc 1234 aa, and bc1234aa are all equivalent).
  • Response: { vehicleId } — use the returned ID with GET /vehicle/:vehicleId.
GET /transport?latitude={lat}&longitude={lng}

Vehicles within 1 km of a point. Short-cached (10 s).

  • Response: array of { id, route, routeId, direction, vehicle_type, color, location: [lat, lng], bearing, speed, lowfloor }. routeId is usable as :name in /routes/static/:name; direction matches the index into stops/shapes (0 = outbound, 1 = return, null if unknown). speed is m/s or null.
GET /disruptions?route={name}&stop={code}

Closures, detours and moved stops the city announced that are in force today. The GTFS feed carries none of them. Cached 5 min at the CDN.

  • Hand-curated in data/disruptions.json, checked against a schema at startup and in tests; add or edit an entry there and deploy. An entry is served from its since day through its until day (Kyiv time), so a stale one hides itself.
  • route (Cyrillic or Latin short name) and stop (numeric code) are optional filters; with either, only entries touching it are listed.
  • Response: { disruptions, updated_at }. Each item: { id, kind, reason, since, until, until_text, routes, stops, alternatives, detour, note, source, url }. kind is suspended, detour, stop_moved or stop_closed; routes and alternatives are { name, id } (name like Т33, id the Latin form used in lad.lviv.ua URLs); detour is { via: [streets], skipped_stops: [codes] } or null.

Service and discovery

EndpointReturns
GET /health{ status: "ok" }, or 503 while the timetable store is not loaded. Does not probe the upstream feed.
GET /ping{}
GET /openapi.yaml (also /.well-known/openapi.yaml)OpenAPI 3.0 description of the REST API.
GET /llms.txt, GET /INTEGRATION.mdLLM-oriented overview and the integration guide.
GET /.well-known/ai-plugin.json, GET /.well-known/agent.jsonOpenAI plugin manifest and A2A agent card.
GET /server.json, GET /smithery.jsonMCP Registry and Smithery manifests.
GET /sitemap.xmlSitemap of the public lad.lviv.ua pages.

Deployment

Production runs on Cloud Run (timetable-api-node, europe-north1, project timetable-252615) behind Cloudflare.

  • Image. The Dockerfile imports the GTFS feed at build time (gtfs-import.ts, then scripts/slim-gtfs-db.ts empties the SQLite tables the server never reads), so every image carries its own data snapshot. last-modified.txt records the feed's Last-Modified header.
  • Cloud Build. cloudbuild.yaml builds, pushes and deploys the image. A daily scheduled run sets _DATA_REFRESH=1 and skips the whole build when the upstream static.zip is unchanged since the deployed revision.
  • Manual. make deploy builds a linux/amd64 image, pushes it and deploys it. make smoke checks a few production endpoints; make clear-short-cache, clear-long-cache and clear-all-cache purge Cloudflare by cache tag.
  • npm package. make publish bumps the patch version (which also syncs server.json and openapi.yaml) and pushes the tag; the tag triggers .github/workflows/publish.yml, which publishes to npm and the MCP Registry. The package ships only the timetable-mcp stdio proxy.

來源:README.md,提交 c88d513

工具

9

get_stop_realtime

Get Stop Realtime

Returns live arrivals at a stop: route, destination, vehicle type, minutes until arrival, and each vehicle's position. Use this as the **default tool** when the user asks about arrivals, departures, or the next bus/tram at a specific stop. Requires a numeric stop ID (shown on stop signage); use `search_stops` when you have a stop name, or `get_stops_around_location` when you have coordinates.

輸入參數stop_id必填lowfloor_only

search_stops

Search Stops

Finds stops by name (Ukrainian or English transliteration, case-insensitive, partial match) and returns each stop's numeric ID, coordinates, and the routes serving it. Use this as the **first step** when the user names a stop or landmark stop (e.g. "Опера", "Rynok", "Головний вокзал") and you need a stop ID for `get_stop_realtime` or `find_routes_between`. One name usually covers both sides of the street under different IDs; each is returned, and the `routes` list tells them apart. Use `get_stops_around_location` instead when you have coordinates rather than a name.

輸入參數limitquery必填

find_routes_between

Find Routes Between Stops

Lists the routes from one place to another: which stop to board, where to get off, the direction's destination, stops in between, and the walk at each end — best first, walking counted. Each end is a stop ID (`from_stop_id`) or coordinates (`from_lat` + `from_lng`), e.g. an address the user gave; a point covers every stop within a 600 m walk of it. `options` are direct routes. `transfer_options` have exactly one interchange (never more): ride `legs[0]`, walk `transfer_walk_meters` (within a 300 m stop cluster, 0 when it is the same stop) to `legs[1].board_stop`, ride `legs[1]`. They are listed when there is no direct route or when they beat the best direct one. Every option carries `schedule`: by the timetable, when to leave, when each leg boards and alights, when you arrive, and `total_minutes` door to door. Plan for now by default, or pass `depart_at` or `arrive_by` ("HH:MM" Lviv time today, or ISO 8601). When planning for now, options also carry `next_departures`: the live next departures of the first leg from its boarding stop, so no separate `get_stop_realtime` call is needed. `map_stops` holds the best trip's stops in riding order, each with a `role` (board, transfer — or transfer_alight + transfer_board when the interchange is a walk — and alight). Use when the user asks how to get from A to B, which bus/tram goes from one place to another, how long it takes, or when to leave to be somewhere on time. A stop end covers every stop within a 300 m walk of it, since a line's two directions often stop on opposite sides of a street under different names; `board_stop` says where to actually wait. Routes the city has suspended, and stops a detour skips, are left out. `walk_meters` is set when the two ends are within a 300 m walk of each other: no ride is searched then, so tell the user to walk. Otherwise both lists empty means the trip needs two or more transfers. Get stop IDs with `search_stops` or `get_stops_around_location`.

輸入參數to_latto_lngfrom_latfrom_lngarrive_bydepart_atto_stop_idfrom_stop_id

get_route_static

Get Route Static

Returns static route data: name, long name, vehicle type, colour, the ordered stop list for both directions, and the timetable of departures from the first stop (workday, Saturday and Sunday). Use when the user asks which stops a route serves, where it goes, or its scheduled departure times. Set `include_shapes` only when you will draw the route on a map — the polylines are large and carry nothing a text answer needs. Do NOT use this for live vehicle positions — use `get_route_realtime` instead. Requires a route short name (e.g. "T30", "32A") or numeric external ID.

輸入參數route_name必填include_shapes

get_route_realtime

Get Route Realtime

Returns every vehicle currently running on a route: position, the destination it is heading to, and its next stop with estimated arrival. `headways` sums up each direction: how many vehicles run, the live gaps between consecutive vehicles in minutes (front to back), and how often the timetable says it should run right now. Use when the user asks "where is my tram/bus right now?", how many vehicles are running, how far the next one is, or how often a route runs. Pass `direction` (0 or 1, as in `get_route_static`'s `stops`) to get only one way. Prefer `get_stop_realtime` when the user is at a stop and wants arrival times there. Requires a route short name (e.g. "T30", "32A") or numeric external ID.

輸入參數directionroute_name必填

get_disruptions

Get Disruptions

Lists closures, detours and moved stops the city announced that are in force today: affected routes, the streets a detour uses, routes to take instead of a suspended one, reason, dates and source. The GTFS stop lists and timetables do not reflect any of this. Use when the user asks about road works, closures, detours, or why a route is not running or a vehicle is off its usual path. Pass `route` and/or `stop_id` to get only the entries touching them; omit both for the whole city.

輸入參數routestop_id

get_stops_around_location

Get Stops Around Location

Finds stops near a geographic point, returning each stop's numeric ID, name, coordinates, walking distance, and the routes serving it. Use this as the **first step** when the user gives an address or coordinates and you need stop IDs for `get_stop_realtime` or `find_routes_between`. Use `search_stops` instead when the user gives a stop name. Default radius is 1 000 m; narrow it (e.g. 300 m) for dense urban areas or widen it (up to 3 000 m) for rural locations.

輸入參數latitude必填longitude必填radius_meters

get_nearby_vehicles

Get Nearby Vehicles

Returns live vehicles near a point, nearest first, each with its route, destination, and distance. Use when the user asks "what transport is near me right now?" or wants a live map around a location. Narrow with `route` when the user cares about one line; prefer `get_route_realtime` for a whole route and `get_stop_realtime` for arrival times at a stop. Requires decimal latitude and longitude (WGS84).

輸入參數limitroutelatitude必填longitude必填lowfloor_onlyradius_meters

get_vehicle_info

Get Vehicle Info

Returns details for one vehicle by ID: position, route, destination, license plate, and its upcoming stops with names and estimated arrival times. Use when the user wants to follow a particular vehicle, e.g. "where does this tram go next?" or "when will it reach X?". Vehicle IDs come from `get_route_realtime`, `get_nearby_vehicles`, or `get_stop_realtime` results. Do NOT use this to get all vehicles on a route — use `get_route_realtime` instead.

輸入參數vehicle_id必填

版本歷史

21
  1. v1.8.13最新Nov 7, 2026
  2. v1.8.11Nov 4, 2026
  3. v1.8.10Nov 3, 2026
  4. v1.8.9Nov 3, 2026
  5. v1.8.7Nov 1, 2026
  6. v1.8.6Oct 29, 2026
  7. v1.8.5Oct 26, 2026
  8. v1.8.4Oct 26, 2026
  9. v1.8.0Oct 23, 2026
  10. v1.7.11Oct 22, 2026
  11. v1.7.10Oct 20, 2026
  12. v1.7.9Oct 19, 2026
  13. v1.7.7Oct 17, 2026
  14. v1.7.6Oct 14, 2026
  15. v1.7.4Oct 12, 2026
  16. v1.7.3Oct 9, 2026
  17. v1.7.1Oct 1, 2026
  18. v1.6.3Sep 30, 2026
  19. v1.5.0Sep 23, 2026
  20. v1.4.1Sep 18, 2026
  21. v1.4.0Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分