uktrains

An agent-first UK train journey CLI and stdio MCP server. It's built for a personal LLM agent to search journeys, compare fares, and hand the human a pre-filled booking link — the tool never takes payment and never claims a booking was made. Fulfilment means one thing: a correct, pre-filled retailer checkout link the human taps to pay.

JSON is the default output everywhere (CLI and MCP alike); pass --pretty on the CLI for a human-readable table.

What it does today

• Resolves UK station names/aliases to CRS codes, including group stations ("Manchester", "London").
• Builds a journey intent from --from/--to plus --depart-after or --arrive-by (and the return-leg equivalents), and produces a pre-filled National Rail Enquiries journey planner booking link — the only live provider today (see "Capability tiers" below for the dormant Trainline provider). A return leg with arrive-by is flagged with a note: NRE's URL can't pre-fill that constraint on the return leg, so it's pre-filled as depart-after and the caller should verify the return train actually arrives by the deadline on the retail page.
• At Tier 1, fetches BR Fares flow-level fares (railcard-aware), sorted by price (the cheapest/fastest/balanced rankBy modes are accepted today but don't change ordering yet — journey-level ranking arrives with Tier 2), including return-vs-two-singles comparison.
• doctor reports which tier is active and validates configured keys.
• setup walks an agent (or a human) through the two optional signups.

live (CLI) and live_status (MCP) exist as structured stubs today — they return a TIER_UNAVAILABLE error with a setup pointer rather than pretending to have live data. Live departures/delays and richer in-tool journey planning land in a later plan (Tier 2).

Capability tiers

No free API combines journey planning with fares, and Darwin live data requires a Rail Data Marketplace account with human approval — so the tool degrades gracefully instead of demanding setup upfront.

Tier	Requires	Unlocks
0	Nothing (bundled station data)	Station resolution, journey intent construction, a pre-filled National Rail Enquiries booking link. The core "get me a train" flow works the moment you build it — the human sees times and fares on the retail page.
1	BR Fares API key (free, non-commercial, ~minutes to register, 100 calls/day)	In-tool fare quotes with railcard discounts — rank cheapest vs. fastest, compare return vs. two singles, before handing over a link. The parser is validated against docs-authored fixtures; run npx tsx scripts/record-brfares.ts <orig> <dest> <key> with your first real key to re-record a live response and confirm the shape still matches — if the live API's shape has drifted, fares present as UPSTREAM_DOWN rather than silently misparsing.
2	RDM account + "LDBWS – Public" subscription (free, 1–3 day approval)	Live departures, delays, platforms, cancellations; real in-tool journey planning with a realtime overlay. Not implemented yet — arrives in the next plan.

Run uktrains doctor at any time to see the active tier and exactly what's missing to reach the next one.

National Rail Enquiries is the sole live booking-link provider today. The code also carries a Trainline provider, but it's dormant: a Trainline link needs a verified station-ID mapping (URN) for BOTH the origin and destination, and data/trainline-urns.json currently has exactly one verified entry (KGX) — so no station pair can produce a Trainline link yet. The code path and its fixture-backed tests stay in place for when more URNs get recorded; until then, expect NRE-only links.

Install

For agents

If you are an LLM agent: read AGENTS.md — it is written for you and covers install, MCP registration, setup shepherding, and how to present options to your human.

git clone https://github.com/aaryan-gulia/uktrains.git
cd uktrains
npm install
npm run build

The built CLI is at dist/cli/index.js and runnable directly:

node dist/cli/index.js search --from KGX --to YRK --depart-after 2031-08-01T09:00:00+01:00

Or invoke it via npx once linked/published, or point an MCP client at the built entry point (below) — no global install required.

For humans

Same steps, then optionally npm link (or install globally once published) so the uktrains command is on PATH.

Requires Node.js 20+.

MCP client config

If uktrains is on PATH (e.g. via npm link):

{
  "command": "uktrains",
  "args": ["mcp"]
}

From a source checkout, without installing globally:

{
  "command": "node",
  "args": ["/absolute/path/to/uktrains/dist/cli/index.js", "mcp"]
}

The server exposes four tools: search_journeys, get_booking_link, live_status (Tier 2 stub), and lookup_station. Tool descriptions are normative — they tell the calling agent, for example, that arriveBy is a station arrival time and that the agent is responsible for adding transit and buffer time to the actual appointment.

CLI examples

# Search a journey (JSON by default; --pretty for a human-readable table)
uktrains search --from KGX --to YRK --depart-after 2031-08-01T09:00:00+01:00 --pretty

# Same, but restrict fares to a railcard and rank by cheapest
uktrains search --from "London" --to "Manchester" \
  --depart-after 2031-08-01T09:00:00+01:00 \
  --railcard 16-25 --rank-by cheapest

# Booking links only, no fare lookup
uktrains link --from KGX --to YRK --depart-after 2031-08-01T09:00:00+01:00

# Resolve a station name or CRS code
uktrains stations york

# Agent-drivable setup: machine-readable next steps for both signups
uktrains setup --json

# Store a key once the human has completed a signup
uktrains setup --set brfares=<key>

# Check active tier and validate configured keys
uktrains doctor

All time flags (--depart-after, --arrive-by, --return-depart-after, --return-arrive-by) take ISO-8601 timestamps and require an explicit timezone offset (e.g. 2031-08-01T09:00:00+01:00 or Z). Offset-less times are rejected with a structured INVALID_INPUT error — silently guessing a timezone produces silently wrong booking links.

Setup walkthrough

uktrains setup --json (the default) prints machine-readable steps so an agent can shepherd the human through both signups in the background, while Tier 0 already delivers working booking links:

1. BR Fares (Tier 1) — open https://www.brfares.com/api/login.html, register a free non-commercial account, obtain an API key, then run uktrains setup --set brfares=<key>.
2. Rail Data Marketplace (Tier 2, live data — not yet consumed by this build) — open https://raildata.org.uk, create an individual account (approval typically takes 1–3 working days), subscribe to the free "LDBWS – Public" product, then run uktrains setup --set rdm=<key>.

Config is stored at ~/.config/uktrains/config.json and holds only rail-domain state: API keys, railcards, and ranking preferences. No home station, no calendar integration — the calling agent already knows that.

Attribution and licensing notes

• Output carries "Powered by National Rail Enquiries" per NRE's OGL terms.
• Each user brings their own API keys. RDM and BR Fares agreements are per-account — this tool never shares keys or redistributes upstream data.
• The BR Fares free tier is registered for non-commercial use only.
• Fares are flow-level (origin→destination, railcard-adjusted), not per-train, and are stamped indicative and time-stamped at quote time. Advance fares are additionally flagged subject to availability, since Advance quota lives in the closed National Reservation Service that no open source exposes. Re-search before presenting a fare older than ~15 minutes.
• The tool never takes payment and never states or implies that a booking was completed — only that a booking link was produced.

Further reading

• Design spec: docs/superpowers/specs/2026-07-31-uktrains-design.md
• Implementation plan: docs/superpowers/plans/2026-07-31-uktrains-core-tier0-1.md
• Agent guide: AGENTS.md