Postman / curl: call a tool on production

\n\n`POST https://api.lad.lviv.ua/mcp` with `Content-Type: application/json`. The Streamable HTTP transport may require additional headers your MCP client sets automatically; for a quick manual test, follow the same sequence your MCP SDK uses (session `initialize`, then `tools/call`). Example **`tools/call`** body shape:\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"get_stop_realtime\",\n \"arguments\": { \"stop_id\": 101 }\n }\n}\n```\n\nSuccessful tool responses return a **natural-language text summary** inside MCP `content` items (`type: \"text\"`) — e.g. *\"Stop «Opera»: 3 arrivals. Next: T01 → «Rynok» in 2 min.\"* The full structured payload is in the `structuredContent` field (for schema-aware clients). Each `structuredContent` payload follows a strict UI contract:\n\n```json\n{\n \"view\": \"transit_realtime\",\n \"data\": { \"...\": \"tool-specific source data\" },\n \"ui_blocks\": [\n { \"type\": \"map\", \"data\": { \"...\": \"map renderer input\" } },\n { \"type\": \"arrival_list\", \"data\": { \"...\": \"arrival list renderer input\" } }\n ]\n}\n```\n\nConsistency rule: each vehicle rendered on map must either have a matching ETA in list data or `eta_status: \"unassigned\"`.\n\n

\n\n### Exposed tools\n\n- `get_stop_realtime`\n- `get_route_static`\n- `get_route_realtime`\n- `get_stop_geometry`\n- `get_stops_around_location`\n- `get_nearby_vehicles`\n- `get_vehicle_info`\n\n

get_stop_realtime — input & example

\n\n**Arguments (JSON):**\n\n| Field | Type | Required |\n|-------|------|----------|\n| `stop_id` | positive integer or digits-only string | yes |\n\n**Example result** (shape only; values from upstream):\n\n```json\n{\n \"view\": \"transit_realtime\",\n \"data\": {\n \"stop\": { \"id\": \"707\", \"name\": \"Стадіон Сільмаш\", \"lat\": 49.84, \"lng\": 24.03 },\n \"arrivals\": [\n {\n \"route\": \"T30\",\n \"direction\": \"Рясівська\",\n \"vehicle_type\": \"tram\",\n \"arrival_minutes\": 4,\n \"vehicle_id\": \"tram_123\",\n \"lat\": 49.83,\n \"lng\": 24.02,\n \"bearing\": 120\n }\n ],\n \"updated_at\": \"2026-01-23T12:00:00Z\"\n },\n \"ui_blocks\": [\n {\n \"type\": \"map\",\n \"data\": { \"center\": [49.84, 24.03], \"vehicles\": [] }\n },\n {\n \"type\": \"arrival_list\",\n \"data\": { \"arrivals\": [] }\n }\n ]\n}\n```\n\n

\n\n

get_route_static — input & example

\n\n**Arguments (JSON):**\n\n| Field | Type | Required |\n|-------|------|----------|\n| `route_name` | route short name (e.g. `\"T30\"`, `\"32A\"`) or numeric external ID | yes |\n\n**Example result** (shape only; stops truncated for brevity):\n\n```json\n{\n \"view\": \"transit_realtime\",\n \"data\": {\n \"route\": {\n \"name\": \"T30\",\n \"long_name\": \"Рясне-2 — Сихів\",\n \"color\": \"#e81717\",\n \"type\": \"tram\"\n },\n \"stops\": [\n [\n {\n \"id\": \"101\", \"name\": \"Головний вокзал\", \"lat\": 49.841, \"lng\": 24.003,\n \"departures\": [\"05:30\", \"05:52\"],\n \"schedule\": { \"workday\": [\"05:30\", \"05:52\", \"06:10\"], \"weekend\": [\"07:00\", \"07:30\"] }\n },\n { \"id\": \"707\", \"name\": \"Стадіон Сільмаш\", \"lat\": 49.838, \"lng\": 24.021, \"departures\": [], \"schedule\": { \"workday\": [], \"weekend\": [] } }\n ],\n [\n { \"id\": \"707\", \"name\": \"Стадіон Сільмаш\", \"lat\": 49.838, \"lng\": 24.021, \"departures\": [], \"schedule\": { \"workday\": [], \"weekend\": [] } },\n { \"id\": \"101\", \"name\": \"Головний вокзал\", \"lat\": 49.841, \"lng\": 24.003, \"departures\": [], \"schedule\": { \"workday\": [], \"weekend\": [] } }\n ]\n ],\n \"shapes\": [\n [[49.841, 24.003], [49.839, 24.012], [49.838, 24.021]],\n [[49.838, 24.021], [49.839, 24.012], [49.841, 24.003]]\n ],\n \"updated_at\": \"2026-01-23T12:00:00Z\"\n },\n \"ui_blocks\": [\n {\n \"type\": \"map\",\n \"data\": {\n \"center\": [49.841, 24.003],\n \"zoom\": 13,\n \"polylines\": [[[49.841, 24.003], [49.839, 24.012], [49.838, 24.021]]],\n \"stops\": [\n { \"id\": \"101\", \"name\": \"Головний вокзал\", \"lat\": 49.841, \"lng\": 24.003 },\n { \"id\": \"707\", \"name\": \"Стадіон Сільмаш\", \"lat\": 49.838, \"lng\": 24.021 }\n ],\n \"vehicles\": []\n }\n }\n ]\n}\n```\n\n`stops[0]` is direction 0 (outbound), `stops[1]` is direction 1 (return). `departures` and `schedule` are populated only for the **first stop of direction 0**; all other stops have empty arrays. `schedule.workday` contains Monday–Friday departure times; `schedule.weekend` contains Saturday–Sunday departure times. `departures` keeps today's schedule for backward compatibility. `shapes` follows the same two-element order. The map block uses direction-0 polyline and all unique stops as markers.\n\n

\n\n

get_route_realtime — input & example

\n\n**Arguments (JSON):**\n\n| Field | Type | Required |\n|-------|------|----------|\n| `route_name` | route short name (e.g. `\"T30\"`, `\"32A\"`) or numeric external ID | yes |\n\n**Example result:**\n\n```json\n{\n \"view\": \"transit_realtime\",\n \"data\": {\n \"route_name\": \"T30\",\n \"vehicles\": [\n {\n \"id\": \"tram_123\",\n \"direction\": 0,\n \"lat\": 49.838,\n \"lng\": 24.021,\n \"bearing\": 120,\n \"lowfloor\": true\n }\n ],\n \"updated_at\": \"2026-01-23T12:00:00Z\"\n },\n \"ui_blocks\": [\n {\n \"type\": \"map\",\n \"data\": {\n \"center\": [49.838, 24.021],\n \"zoom\": 13,\n \"vehicles\": [\n {\n \"id\": \"tram_123\",\n \"direction\": 0,\n \"lat\": 49.838,\n \"lng\": 24.021,\n \"bearing\": 120,\n \"lowfloor\": true\n }\n ]\n }\n }\n ]\n}\n```\n\n`direction` matches the index into `get_route_static`'s `stops` array (0 = outbound, 1 = return). `lowfloor: true` indicates a low-floor vehicle. Returns an empty `vehicles` array when no vehicles are currently active on the route.\n\n

\n\n

get_stop_geometry — input & example

\n\n**Arguments:**\n\n| Field | Type | Required |\n|-------|------|----------|\n| `stop_id` | positive integer or digits-only string | yes |\n\n**Example result:**\n\n```json\n{\n \"view\": \"transit_realtime\",\n \"data\": {\n \"stop\": { \"id\": \"707\", \"name\": \"Стадіон Сільмаш\", \"lat\": 49.84, \"lng\": 24.03 },\n \"routes\": [\n {\n \"route\": \"T30\",\n \"polyline\": [[49.84, 24.03], [49.83, 24.02]]\n }\n ]\n },\n \"ui_blocks\": [{ \"type\": \"map\", \"data\": { \"routes\": [] } }]\n}\n```\n\n

\n\n

get_stops_around_location — input & example

\n\nReturns stops near a map point (numeric **code**, name, coordinates, distance). Intended for hosts that render **`map`** UI blocks (for example ChatGPT): one block with **multiple stop markers** and the search center. Uses the same backend as **`GET /closest`** (see below).\n\n**Arguments (JSON):**\n\n| Field | Type | Required |\n|-------|------|----------|\n| `latitude` | number, −90…90 | yes |\n| `longitude` | number, −180…180 | yes |\n| `radius_meters` | integer, 50…3000 | no (default **1000**) |\n\n**Example result** (shape only):\n\n```json\n{\n \"view\": \"transit_realtime\",\n \"data\": {\n \"center_lat\": 49.84,\n \"center_lng\": 24.03,\n \"radius_meters\": 1000,\n \"stops\": [\n {\n \"id\": \"707\",\n \"name\": \"Стадіон Сільмаш\",\n \"lat\": 49.841,\n \"lng\": 24.031,\n \"distance_meters\": 120\n }\n ],\n \"updated_at\": \"2026-01-23T12:00:00Z\"\n },\n \"ui_blocks\": [\n {\n \"type\": \"map\",\n \"data\": {\n \"center\": [49.84, 24.03],\n \"zoom\": 15,\n \"stops\": [\n {\n \"id\": \"707\",\n \"name\": \"Стадіон Сільмаш\",\n \"lat\": 49.841,\n \"lng\": 24.031,\n \"distance_meters\": 120\n }\n ],\n \"vehicles\": []\n }\n }\n ]\n}\n```\n\nMap zoom is **15** for radius ≤ 1500 m and **14** for larger radii (up to 3000 m).\n\n

\n\n

get_nearby_vehicles — input & example

\n\nReturns live positions for all transit vehicles within 1 km of given coordinates. Wraps the same backend as `GET /transport`.\n\n**Arguments (JSON):**\n\n| Field | Type | Required |\n|-------|------|----------|\n| `latitude` | number, −90…90 | yes |\n| `longitude` | number, −180…180 | yes |\n\n**Example result** (shape only):\n\n```json\n{\n \"view\": \"transit_realtime\",\n \"data\": {\n \"center_lat\": 49.84,\n \"center_lng\": 24.03,\n \"vehicles\": [\n {\n \"id\": \"tram_123\",\n \"route\": \"T01\",\n \"vehicle_type\": \"tram\",\n \"lat\": 49.841,\n \"lng\": 24.031,\n \"bearing\": 90,\n \"lowfloor\": true\n }\n ],\n \"updated_at\": \"2026-01-23T12:00:00Z\"\n },\n \"ui_blocks\": [\n {\n \"type\": \"map\",\n \"data\": {\n \"center\": [49.84, 24.03],\n \"zoom\": 14,\n \"vehicles\": [{ \"id\": \"tram_123\", \"route\": \"T01\", \"lat\": 49.841, \"lng\": 24.031, \"bearing\": 90, \"eta_status\": \"unassigned\" }]\n }\n }\n ]\n}\n```\n\n

\n\n

get_vehicle_info — input & example

\n\nFull details for one vehicle by its ID: position, route, license plate, direction, and upcoming stop arrival times. Vehicle IDs come from `get_route_realtime`, `get_nearby_vehicles`, or `get_stop_realtime`.\n\n**Arguments (JSON):**\n\n| Field | Type | Required |\n|-------|------|----------|\n| `vehicle_id` | string | yes |\n\n**Example result** (shape only):\n\n```json\n{\n \"view\": \"transit_realtime\",\n \"data\": {\n \"vehicle_id\": \"tram_123\",\n \"route\": \"route-ext-1\",\n \"license_plate\": \"BC-1234-AB\",\n \"lat\": 49.841,\n \"lng\": 24.031,\n \"bearing\": 90,\n \"direction\": 0,\n \"upcoming_stops\": [\n { \"code\": 707, \"arrival\": \"2026-01-23T12:05:00Z\", \"departure\": null },\n { \"code\": 708, \"arrival\": \"2026-01-23T12:08:00Z\", \"departure\": null }\n ],\n \"updated_at\": \"2026-01-23T12:00:00Z\"\n },\n \"ui_blocks\": [\n {\n \"type\": \"map\",\n \"data\": { \"center\": [49.841, 24.031], \"zoom\": 15, \"vehicles\": [{ \"id\": \"tram_123\", \"eta_status\": \"unassigned\" }] }\n }\n ]\n}\n```\n\n

\n\n\n### Resources and resource templates\n\nIn addition to tools, the server exposes MCP **resources** for reference data that doesn't require a tool call:\n\n| URI | Description |\n|-----|-------------|\n| `timetable://about` | Scope, usage, and data caveats for this server (Markdown) |\n| `timetable://reference/tools` | Tools reference table (Markdown) |\n| `timetable://reference/prompts` | Prompt templates catalog (Markdown) |\n| `timetable://stop/{code}` | Static info for a stop by numeric code — name, coordinates, serving routes (JSON) |\n| `timetable://route/{name}` | Static metadata for a route by short name — color, type, stop counts (JSON) |\n\n### Security model\n\n- Public read-only (no authentication).\n- No mutating tools are exposed.\n- `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.\n- `robots.txt` is only a best-effort discovery hint and not a protocol contract.\n\n## REST API\n\nAll endpoints return JSON. `:code` is a numeric stop code; `:name` is a route short name (e.g. `T1`, `32A`) or numeric external ID.\n\n### Stops\n\n#### `GET /stops.json`\n\nAll stops as a JSON array, sorted by code.\n\n- **Response:** array of `{ code, name, eng_name, location: [lat, lng], routes, sign, sign_pdf }`.\n\n(`GET /stops` returns an HTML table instead.)\n\n#### Per-stop route overrides\n\nThe upstream route list for a stop is sometimes behind reality. `GET /stops`\napplies a stored override to its `Маршрути` column — removed routes shown red and\nstruck through, added ones green — and hangs the matching `?add=`/`?remove=` on\nthat row's SVG and PDF links, which `offline.lad.lviv.ua` and `pdf.lad.lviv.ua`\nboth understand.\n\nThe route column is always clickable: click a route to drop or restore it, type\none into the `+` box to add it.\n\nOverrides live in the browser's own `localStorage` (see\n[`public/stopOverrides.js`](https://github.com/vbhjckfd/timetable-api-node/blob/master/public/stopOverrides.js)), not on a server — no\naccount to edit through, no cache to purge, an edit applies at once. The trade\nis scope: an override is visible only in the browser that made it, not to\nanyone else who opens `/stops`.\n\n`/stops.json` reports `sign` and `sign_pdf` without overrides applied.\n\n#### `GET /stops/:code`\n\nSingle stop with live realtime timetable. Short-cached (5–10 s).\n\n- **Optional:** `skipTimetableData=1` — omit live arrivals (long-cached response).\n- **Response:** `{ code, name, eng_name, latitude, longitude, transfers, timetable }`.\n\n#### `GET /stops/:code/timetable`\n\nLive timetable only for a stop. Short-cached (5–10 s).\n\n- **Response:** array of timetable items.\n\n#### `GET /stops/:code/static`\n\nStatic stop info without live data. Long-cached (30 days).\n\n- **Response:** `{ code, name, eng_name, latitude, longitude, transfers }`.\n\n#### `GET /closest?latitude={lat}&longitude={lng}`\n\nNearby stops — same search as `get_stops_around_location`, for non-MCP clients.\n\n- **Optional:** `radius` — meters, clamped between **50** and **3000** (default **1000**).\n- **Response:** JSON array of `{ code, name, latitude, longitude, distance_meters }` (sorted by distance).\n\n### Routes\n\n#### `GET /routes.json`\n\nAll routes as a JSON array, sorted by short name.\n\n- **Response:** raw route objects from the timetable store.\n\n(`GET /routes` returns an HTML table.)\n\n#### `GET /routes/static/:name`\n\nRoute shape, stop list, and metadata. Long-cached (30 days).\n\n- **Response:** `{ id, color, type, route_short_name, route_long_name, stops: [[dir0…], [dir1…]], shapes }`.\n- Each stop object: `{ code, name, loc, transfers, departures, schedule }`.\n - `departures` — today's departure times (HH:MM), populated only for direction 0 first stop. Kept for backward compatibility.\n - `schedule` — `{ workday: string[], weekend: string[] }` departure times by day type, populated only for direction 0 first stop.\n\n#### `GET /routes/dynamic/:name`\n\nLive vehicle positions for a route. Short-cached (10 s).\n\n- **Response:** array of `{ id, direction, location: [lat, lng], bearing, speed, lowfloor }`. `speed` is m/s from the GPS unit, or `null` when not reported.\n\n### Vehicles\n\n#### `GET /vehicle/:vehicleId`\n\nLive position and upcoming stop arrivals for one vehicle. Short-cached (5 s).\n\n- **Response:** `{ location: [lat, lng], routeId, bearing, speed, direction, licensePlate, arrivals }`. `speed` is m/s from the GPS unit, or `null` when not reported.\n\n#### `GET /vehicle-by-plate/:plate`\n\nLook up a vehicle ID by its license plate. Short-cached (5 s).\n\n- The plate is matched case-insensitively with spaces and dashes ignored (`BC-1234-AA`, `bc 1234 aa`, and `bc1234aa` are all equivalent).\n- **Response:** `{ vehicleId }` — use the returned ID with `GET /vehicle/:vehicleId`.\n\n#### `GET /transport?latitude={lat}&longitude={lng}`\n\nVehicles within 1 km of a point. Short-cached (10 s).\n\n- **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`.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_102":103,"_104":105,"_106":107,"_108":109,"_110":111,"_112":113},"requiredSecrets",[],"tags",[99,100,101],"assets",[],"stats",{"_97":86,"_98":86},"ratingAvg","reviewCount","transit","transport","transport-api","topics",[99,100,101],"license","WTFPL","language","JavaScript","registryName","io.github.vbhjckfd/timetable-api-node","homepage","https://lad.lviv.ua","packages",[],"ENV",{"_116":117,"_118":119,"_120":121},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]

Lviv Public Transport