DMV Transit

DMV Regional Transportation Assistant (transit-mcp)

A plain-language assistant that helps people — especially first-time riders — get around the Washington DC / Maryland / Virginia region by public transit. It answers from current, cited data pulled from WMATA (Metrorail + Metrobus), the Virginia systems (VRE, Fairfax Connector, ART, DASH, CUE, Loudoun, OmniRide, Virginia Breeze), Maryland (MTA bus, commuter bus, Metro SubwayLink, Light RailLink, MARC, Annapolis Transit, Harbor Connector, Potomac Valley), the Dulles Airport shuttles, and intercity services (Amtrak, FlixBus and other intercity buses), and focuses on what trips actually hinge on: which systems connect where, on which days and at what times a connection works, and how to pay each leg.

The home page is a leave-now trip planner on a map: type where you're going (or use your location), and it shows every good way to get there in the next 3 hours — direct trips first, one change only when it saves time, and changes with a wait of 10 minutes or less preferred (a longer wait is offered only when nothing better works) — with live departure times where the agency publishes them. It uses each agency's closest stops (up to about a mile away) and shows how much walking each trip involves. The assistant chat sits in a drawer beside the map.

Unofficial. This is an independent project. It is **not affiliated with,

endorsed by, sponsored by, or operated by** WMATA or any other transit agency.

Agency names identify their services only. For official information, contact the

agency directly.

Answers are grounded in the stored data: the assistant must call its tools before it answers, is instructed never to fill gaps from the model's general knowledge, and says "I don't have that information" rather than guess. (The Claude API no longer accepts a temperature setting, so accuracy is enforced through the data, the tools and the prompt instead — see chat/agent.py.)

Quick start (Windows)

1. Install Python 3.11+ (tick *Add python.exe to PATH*).
2. Double-click `start.bat`.

• First time: it sets everything up, creates a settings file and opens it in Notepad. Paste in your ANTHROPIC_API_KEY (console.anthropic.com) and WMATA_API_KEY (free at developer.wmata.com), save, and double-click start.bat again. It then downloads transit data (15–20 minutes for all 23 feeds).
• For the map planner, also add TRANSITLAND_API_KEY (transit.land, Explorer plan) and GOOGLE_GEOCODING_API_KEY (Google Geocoding API; GEOCODE_API_KEY from geocode.maps.co also works), and download the regional map once (about 600 MB; without it the map shows a plain background): powershell -ExecutionPolicy Bypass -File deploy\map\fetch-basemap.ps1
• After that: the assistant opens in your web browser within seconds.

1. Keep the black window open while you use it; close it to stop.

If a feed can't be downloaded, you can add it by hand — see feeds/README.md.

Deploying (public website)

The same app runs as a public site — https://dmvtransit.com — on one small AWS Lightsail server in Ohio (us-east-2) with Docker, created and managed by the scripts in deploy/lightsail/: docker compose up -d --build starts the website, automatic HTTPS (Caddy) and a scheduler that keeps data fresh. Public mode adds per-visitor rate limits, a site-wide daily cap and friendly error messages. Step-by-step guide: [deploy/README.md](deploy/README.md).

Architecture

Three layers, each swappable on its own (details in docs/EXTENDING.md):

 agencies/*.toml ──► ingest source plugins ──► SQLite (FTS5) + data/gtfs/*.zip

one file per gtfs · web_pages · │ agency wmata_api · (yours) ▼ retrieval + scheduling engine heuristic | python | process | http │ TripRequest / TripPlan ▼ MCP server (17 tools) ──► web chat (Claude) └─► any MCP client

Every stored record keeps its source URL, fetch time and content hash, so answers are cited and stale data is flagged.

Where each kind of answer comes from

Web pages are never used for routes or schedules. Each feed is downloaded from the official URL listed in Transitland's public registry (no API quota used); Transitland's own hosted copy is the fallback, at one metered API call each (transit-mcp doctor shows which source each feed used). Every Transitland API call is counted against TRANSITLAND_MONTHLY_BUDGET (4,500 of the Explorer plan's 5,000), after which the planner shows scheduled times.

The planner only suggests a change between two stops less than 0.3 km apart (of any agency), so every transfer is a short walk. Trips with two changes are searched only when nothing with fewer changes works (TRIP_MAX_TRANSFERS). At BWI, DCA and IAD the step between the terminal and the rail station comes from planning/airports.toml: BWI's free shuttle to the MARC/Amtrak station (timing from the airport's website, since the shuttle has no current GTFS feed) and DCA's and IAD's walkways, each with the airport's own directions. Feeds that give trips as headways (frequencies.txt: the Dulles shuttles, CUE, Annapolis Transit) are expanded into one trip per run when loaded. Nearby stops are also grouped into clusters (every pair in a cluster is less than 0.3 km apart) for the assistant's "what connects here" answers.

Fares

Each agency's fare summary is in its definition file, with the agency's fare page scraped nightly where the site allows it. VRE and MARC price trips by station, which GTFS doesn't carry, so their published charts are in planning/rail_fares.toml and trips show the exact one-way fare. Fares that vary by trip (Amtrak, FlixBus, Greyhound, Virginia Breeze, intercity buses) send riders to the operator's site.

Rider reports (crowdsourced)

Riders can warn each other from the map page (Report an issue): the station and line (if any), where the trip started and ended, the date, and what happened in their own words. Each report is saved in the transit database (rider_reports) and checked by a small Claude model (REPORTS_MODEL, default claude-haiku-5-5), which holds back off-topic or abusive posts, sorts it (delay, crowding, elevator...), writes a short neutral summary and notes the agencies, lines and stations. Published reports show on matching trip options for REPORTS_SHOW_HOURS (3) and the assistant can look them up; both always label them as unverified rider reports. Review them with transit-mcp reports list|hide|publish|delete.

Accounts: My places

Visitors (tourists especially) sign in with their email address and a 6-digit code we email them (no password), and save their hotel with check-in and check-out dates, a home, and the attractions they plan to visit, each with an optional day. Current places appear as one-tap quick picks under "Where to?", in the From and To suggestions, and as pins on the map (Go here / Start here); a hotel counts only during the stay, and past visits drop out. Accounts live in their own SQLite file (ACCOUNTS_DB), never linked to the chat log; saved places are logged as "saved" without names and are kept out of links. Codes go out by SMTP (Amazon SES on the public site; see deploy/README.md); a local server without SMTP prints the code in its log. A code works for 10 minutes and 5 tries.

Plan my trip (assistant)

The site is one panel beside the map: "Where to?" at the top, then a single conversation where trip searches appear as live cards alongside the assistant's answers. The assistant can put a trip on the map itself (show_trip, for "take me to the Zoo"), and each question carries the trip on screen, so "how do I pay for this trip?" means the option the rider picked. On phones the panel is a sheet over the map.

Signed-in visitors can plan a trip by chatting: "Plan my visit" starts planning mode. It saves their hotel and places, puts stops on days with "be there by" or "leave at" times, and works out the buses and trains between them for each day (timetable trips that arrive with time to spare, or a walk when it's close). Questions about places to eat or visit are answered with Google Places Text Search (rating, price, opening hours), never from the model's memory, capped by GOOGLE_PLACES_SEARCH_MONTHLY_BUDGET. Anyone can ask questions; saving and planning need an account. The plan is stored in the account, shown under My places, and the planning tools run only in the web app, not on the MCP server, so /mcp holds no personal data. Tool inputs are left out of the chat log.

Command line

All commands run from the project folder (.venv\Scripts\transit-mcp.exe …, or just transit-mcp … with the virtual environment activated).

transit-mcp launch                         # what start.bat runs

transit-mcp doctor # what check-setup.bat runs transit-mcp ingest all # what refresh-data.bat runs transit-mcp ingest gtfs --only dash,vre # one scope (api|gtfs|web), some agencies transit-mcp agencies # every system with role + fare headline transit-mcp agencies --config