LK Transit MCP

An offline first foundation for querying Sri Lankan transit through MCP. Part of AppKade Open.

Current status

Synthetic development prototype. No real operator, live feed, public endpoint or travel service is connected. All bundled stops, routes and arrivals are invented. Every result includes mode: synthetic_demo, production_ready: false, provenance and a warning. Do not use these results for travel decisions.

The original requirements and feasibility research describes the larger proposed platform. It is a plan, not a list of implemented features. Imported citation markers are research-export references, not independently verified repository evidence. See the implementation roadmap.

Related MCP server: Portfolio MCP

Run locally

Requires Node.js 22.18+ or 24. npm publishing is disabled.

git clone https://github.com/AppKade/lk-transit-mcp.git
cd lk-transit-mcp
npm ci --ignore-scripts
npm run check
npm test
npm start -- --demo

The last command waits for MCP messages on stdin. It is not an interactive terminal chat. Startup without --demo exits with usage instructions. No network connection or credentials are needed after dependency installation.

Connect an MCP host using an absolute path:

{
  "mcpServers": {
    "lk-transit-demo": {
      "command": "node",
      "args": ["/absolute/path/lk-transit-mcp/src/cli.ts", "--demo"]
    }
  }
}

The source runs with Node's TypeScript stripping. This private prototype has no compiled npm package or remote HTTP transport yet.

Available tools

transit://coverage exposes coverage as an MCP resource. All tools are read-only. Both legacy initialization and newer discovery are tested over the actual stdio executable.

Example arguments:

{"latitude":6.9271,"longitude":79.8612,"radius_m":1000,"limit":10}

{"stop_id":"demo:stop:A","at":"2026-10-21T07:30:00+05:30","limit":10}

The fixture timetable exists only on 21 October 2026. Later queries return no arrivals rather than shifting old schedules to today. Calendars, service-day rollover, GTFS times beyond midnight, live predictions and transfers are not implemented.

Data foundation

• Strict snapshots, unique IDs and route/stop reference checks.

• Atomic activation: invalid candidates leave the last known-good snapshot intact in memory.

• Provider-scoped IDs preserve original source identifiers, including leading zeros.

• A separate freshness utility uses observation timestamps, marks old observations stale and rejects future or invalid observations. Demo results always remain labeled synthetic.

• Bounded query radius, result count and snapshot collections; no coordinate logging or persistence.

The snapshot schema is an internal synthetic fixture format, not a GTFS importer. No provider data is bundled. Source access and licensing are prerequisites for a real adapter.

Remaining work

GTFS ZIP/CSV ingestion and validation, GTFS-Realtime ingestion, calendars/timezones, authorized source records, provider health, real arrivals/vehicles/alerts, journey planning, ETA evaluation, persistent storage and a reviewed remote deployment. Production performance targets in the research have not been measured.

Contributing and license

Read CONTRIBUTING.md, SECURITY.md and the roadmap. Source code and original synthetic fixtures use Apache-2.0; see NOTICE. Provider data keeps its own license and is not covered by the code license.