Lviv Public Transport MCP server

Timetable API Node

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

Requirements

• Node.js 26 (see .nvmrc)

Run locally

nvm use
npm install
cp .env.dist .env
make import   # first run, and whenever the GTFS feed changes
make 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.

Variable	Default	Purpose
PORT	8080	HTTP port.
VEHICLES_LOCATION_URL	https://track.ua-gis.com/gtfs/lviv/vehicle_position	GTFS-RT vehicle positions feed.
TRIP_UDPDATES_URL	https://track.ua-gis.com/gtfs/lviv/trip_updates	GTFS-RT trip updates feed (the misspelling is the real name).
MCP_PUBLIC_BASE_URL	https://api.lad.lviv.ua	Base URL used in MCP metadata (icon URL).
NEW_RELIC_LICENSE_KEY	—	Enables New Relic APM (see Monitoring).
NEW_RELIC_APP_NAME, NEW_RELIC_LOG_LEVEL	timetable-api-node, info	New Relic agent settings.
PULSE_WORKER_URL, PULSE_SIGNAL_SECRET	—	Signal a Pulse worker on each /stops/:code/timetable request; both must be set.
MCP_URL	https://api.lad.lviv.ua/mcp	Only for the timetable-mcp stdio proxy: the remote endpoint it forwards to.

Test

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.

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:

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:

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).

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

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.

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:

{
  "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:

{
  "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.

Tool	Arguments	Returns
search_stops	query (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_location	latitude, longitude, radius_meters (50–3000, default 1000)	Stops near a point, nearest first, with distance_meters and routes.
get_stop_realtime	stop_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_between	from_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_static	route_name, include_shapes (default false)	Name, type, colour, stop lists for both directions, first-stop timetable; polylines only on request.
get_route_realtime	route_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_vehicles	latitude, 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_info	vehicle_id	One vehicle: position, route, destination, plate, upcoming stops (id, name, ISO times) not yet passed.
get_disruptions	route, 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.

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

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.

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

{
  "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.

{
  "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".

{
  "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.

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

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.

Prompt	Arguments	Use case
plan-trip	from, to	Routes between two named places (or stop IDs), direct or with one transfer, with live departures from the boarding stop.
route-status	route_name	Where a route's vehicles are right now, by direction. route_name supports completion.
transit-map-view	stop_id	Map-first rendering of live vehicles for a stop.
transit-arrival-list	stop_id	Arrival list for a stop, sorted by ETA and grouped by route.
transit-hybrid-view	stop_id	Map 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:

URI	Description
timetable://about	Scope, usage, and data caveats for this server (Markdown)
timetable://reference/tools	Tools reference table (Markdown)
timetable://reference/prompts	Prompt 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.)