DMV Transit

DMV 区域交通助手（transit-mcp）

一款通俗易懂的助手，帮助人们——尤其是第一次乘车的乘客——在华盛顿特区／马里兰州／弗吉尼亚州地区搭乘公共交通出行。它根据从 WMATA（Metrorail + Metrobus）、弗吉尼亚州各系统（VRE、Fairfax Connector、ART、DASH、CUE、Loudoun、OmniRide、Virginia Breeze）、马里兰州各系统（MTA bus、通勤巴士、Metro SubwayLink、Light RailLink、MARC、Annapolis Transit、Harbor Connector、Potomac Valley）、Dulles Airport 接驳车和城际服务（Amtrak、FlixBus 及其他城际巴士）获取的最新引用数据作答，重点关注实际影响行程的事项：不同系统在哪里衔接、在哪些日期和时段可以顺利换乘，以及如何支付每一段行程的费用。

主页是一个地图式即时出发行程规划器：输入目的地（或使用你的位置），即可查看接下来 3 小时内所有合适的出行方式——优先显示直达行程，只有在能节省时间时才提供一次换乘，并优先选择等待时间不超过 10 分钟的换乘（只有在没有更好的方案时才会提供等待时间更长的方案）；如果交通机构公布了实时出发时间，也会一并显示。它会使用各交通机构距离最近的站点（最远约 1 英里），并显示每种行程需要步行多远。助手聊天窗口位于地图旁的抽屉面板中。

非官方。 这是一个独立项目。它不隶属于 WMATA 或任何其他交通机构，也未获其认可、赞助或运营。机构名称仅用于标识其服务。有关官方信息，请直接联系相关机构。

回答以存储的数据为依据：助手必须先调用工具再作答，并被要求绝不使用模型的一般知识填补信息缺口；遇到不确定的信息时，它会说“我没有这方面的信息”，而不是猜测。（Claude API 不再接受 temperature 设置，因此准确性由数据、工具和提示词来保障——详见 chat/agent.py。）

快速开始（Windows）

1. 安装 Python 3.11+（勾选 Add python.exe to PATH）。
2. 双击 start.bat。
   • 首次运行：程序会完成所有设置、创建设置文件并用记事本打开。粘贴你的 ANTHROPIC_API_KEY (console.anthropic.com) 和 WMATA_API_KEY （可在 developer.wmata.com 免费获取），保存后再次双击 start.bat。随后程序会下载交通数据（全部 23 个数据源约需 15–20 分钟）。
   • 要使用地图规划器，还需添加 TRANSITLAND_API_KEY (transit.land，Explorer 计划）和 GOOGLE_GEOCODING_API_KEY（Google Geocoding API； 也可使用来自 geocode.maps.co 的 GEOCODE_API_KEY），并下载一次区域地图 （约 600 MB；未下载时地图会显示纯色背景）： powershell -ExecutionPolicy Bypass -File deploy\map\fetch-basemap.ps1
   • 此后：助手会在几秒内于网页浏览器中打开。
3. 使用期间请保持黑色窗口打开；关闭窗口即可停止运行。

文件	作用
start.bat	如有需要则完成设置，然后启动助手并打开浏览器
refresh-data.bat	下载最新的服务提醒、时刻表、票价和乘客信息（每周运行一次）
check-setup.bat	以通俗易懂的方式检查密钥、数据、交通机构和行程规划器

如果无法下载某个数据源，可以手动添加——请参阅 feeds/README.md。

部署（公共网站）

同一应用也作为公共网站 https://dmvtransit.com 运行，部署在俄亥俄州（us-east-2）的一台小型 AWS Lightsail 服务器上，并使用 Docker。该服务器由 deploy/lightsail/ 中的脚本创建和管理：运行 docker compose up -d --build 即可启动网站、自动 HTTPS（Caddy）以及用于保持数据最新的调度程序。公共模式会为每位访客设置速率限制、全站每日上限，并显示友好的错误消息。 分步指南：deploy/README.md。

架构

分为三层，每层都可以独立替换（详见 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

层	扩展点	位置
机构	放入 TOML 文件，无需编写代码	agencies/，内置定义位于 src/transit_mcp/agencies/definitions/
数据源	@register_source 插件或入口点	src/transit_mcp/ingest/sources/
行程规划	使用 Python、Node（stdio）或 HTTP 编写自己的引擎，并遵循版本化 JSON 契约	src/transit_mcp/planning/，模板位于 engines/

每条存储的记录都会保留其来源 URL、获取时间和内容哈希，因此答案会注明来源，并标记过时数据。

各类答案的来源

答案	来源
线路、站点、时刻表、运营日和运营时段（包括 Metrorail 和 Metrobus）	各机构的 GTFS 数据源，通过 Transitland 查找
票价、支付方式、乘车方式	机构自己的票价／乘客指南网页，以及 WMATA 的站间票价数据（与 wmata.com/pay.html 核对）
服务中断	WMATA 实时事件、各机构的 GTFS-realtime 警报，以及其服务警报／服务变更网页——始终与 GTFS 时刻表一并显示，绝不取代时刻表
实时出发时间（地图规划器）	机构自己的 GTFS-realtime TripUpdates 数据源，URL 由 Transitland 列出（WMATA rail 和 bus、VRE、Fairfax Connector、MARC、ART）；其余机构使用 Transitland 的出发时间 API。否则显示计划时刻，并标注为“计划时刻”
地址 → 地图坐标	输入时通过 Google Places Autocomplete 获取建议（选中地点后，通过 Place Details 获取其位置）；否则使用 Google Geocoding API（没有 Google 密钥时使用 geocode.maps.co）；所有请求都由服务器发出（密钥不会传到浏览器）
地图	使用自托管的 Protomaps 数据提取文件中的 OpenStreetMap 数据，并通过 MapLibre GL 绘制

网页不会用于提供线路或时刻表。每个数据源都从 Transitland 公共注册表中列出的官方 URL 下载（不消耗 API 配额）；如果失败，则使用 Transitland 自托管副本，每个副本调用一次计量 API（transit-mcp doctor 会显示每个数据源使用的来源）。Transitland 的每次 API 调用都会计入 TRANSITLAND_MONTHLY_BUDGET（Explorer 计划的 5,000 次调用中有 4,500 次可用），超出后，规划器会显示计划时刻。

规划器只会建议在相距不足 0.3 km 的两个站点之间换乘（不论站点属于哪个机构），因此每次换乘都只需短距离步行。只有在没有更少换乘的可行方案时，才会搜索两次换乘的行程（TRIP_MAX_TRANSFERS）。在 BWI、DCA 和 IAD，航站楼与轨道站之间的接驳信息来自 planning/airports.toml：BWI 的免费接驳车通往 MARC／Amtrak 车站（因接驳车没有当前 GTFS 数据源，时间信息取自机场网站），以及 DCA 和 IAD 的步行通道；每项信息都附有机场自己的指引。对于以发车间隔表示行程的数据源（frequencies.txt：Dulles 接驳车、CUE、Annapolis Transit），加载时会将其展开为每班车一条行程。相邻站点也会分组为站点集群（集群中任意两站之间的距离都不足 0.3 km），供助手回答“这里有哪些换乘连接”。

票价

每个机构的票价摘要都在其定义文件中；如果网站支持抓取，我们会每晚抓取该机构的票价页面。VRE 和 MARC 按车站为行程定价，而 GTFS 不包含车站信息，因此它们公布的价目表保存在 planning/rail_fares.toml 中，行程会显示准确的单程票价。票价会随行程变化的运营方（Amtrak、FlixBus、Greyhound、Virginia Breeze、城际巴士）会引导乘客前往运营方的网站。

乘客报告（众包）

乘客可以在地图页面上相互提醒（报告问题）：报告内容包括车站和线路（如有）、行程的起点和终点、日期，以及乘客用自己的话描述的情况。每条报告都会保存到交通数据库（rider_reports），并由一个小型 Claude 模型（REPORTS_MODEL，默认为 claude-haiku-5-5）审核。该模型会拦截离题或辱骂性内容、对报告分类（延误、拥挤、电梯等）、撰写简短中立的摘要，并注明涉及的机构、线路和车站。已发布的报告会显示在匹配的行程选项中，有效期为 REPORTS_SHOW_HOURS（3）小时，助手也可以查阅；两者始终会标明这些报告未经核实，来自乘客。使用 transit-mcp reports list|hide|publish|delete 审核报告。

账户：我的地点

访客（尤其是游客）使用电子邮件地址和我们发送给他们的 6 位验证码登录（无需密码），并保存酒店及入住、退房日期、住址，以及计划前往的景点；每个景点都可以选择填写日期。当前地点会显示在“去哪儿？”下方，作为一键快捷选项；也会出现在“出发地”和“目的地”建议中，并作为图钉显示在地图上（前往这里／从这里出发）。酒店仅在入住期间有效，过去的行程会自动移除。账户保存在独立的 SQLite 文件（ACCOUNTS_DB）中，绝不会与聊天记录关联；保存地点时只记录为“已保存”，不包含名称，也不会加入链接。验证码通过 SMTP 发送（公共网站使用 Amazon SES；参见 deploy/README.md）；未配置 SMTP 的本地服务会在日志中打印验证码。验证码有效期为 10 分钟，最多可尝试 5 次。

规划我的行程（助手）

网站在地图旁设有一个面板：顶部是“去哪儿？”，下方是一个对话窗口，行程搜索结果会以实时卡片的形式显示在助手的回答旁边。助手可以直接将行程显示在地图上（show_trip，例如“带我去动物园”），每个问题也会包含当前屏幕上显示的行程，因此“这趟行程怎么付费？”指的是乘客选中的选项。在手机上，面板会以抽屉形式覆盖在地图上。

已登录的访客可以通过聊天规划行程：“规划我的行程”会启动规划模式。该模式会保存他们的酒店和地点，按天安排停靠点，并设置“最晚到达时间”或“出发时间”，然后为每天规划停靠点之间的公交和火车路线（可选择有充足时间余量的时刻表行程，或在时间紧张时步行）。关于餐饮或游览地点的问题会使用 Google Places Text Search 回答（评分、价格、营业时间），绝不依赖模型的记忆，且搜索次数受 GOOGLE_PLACES_SEARCH_MONTHLY_BUDGET 限制。任何人都可以提问；保存和规划功能需要账户。计划会保存在账户中，并显示在“我的地点”下方。规划工具仅在 Web 应用中运行，不会在 MCP 服务上运行，因此 /mcp 不会存储任何个人数据。工具输入不会记录在聊天日志中。

命令行

所有命令都在项目文件夹中运行（.venv\Scripts\transit-mcp.exe …；或激活虚拟环境后运行 transit-mcp …）。

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              # agency files, their sources, problems
transit-mcp status                         # row counts + freshness (JSON)
transit-mcp search "how do I pay with my phone"
transit-mcp chat --open                    # web chat only
transit-mcp serve                          # MCP server over stdio
transit-mcp planner request "Reston" "Pentagon"   # the JSON an engine receives
transit-mcp planner test "Reston" "Pentagon" --engine process --command "node engines/example-js/engine.js"
transit-mcp planner schema                 # write docs/planner-schema/*.json

重新运行 ingest 安全且开销很小：系统会通过内容哈希检测未更改的网页和数据源。单个数据源出错不会中断其余任务。

已加载的机构

slug	机构	模式	数据
wmata	Metrorail (WMATA)	轨道交通	通过 Transitland 获取 GTFS + WMATA API（车站、事件、票价）+ wmata.com（票价、提醒、指南）
metrobus	Metrobus (WMATA)	公交	通过 Transitland 获取 GTFS（+ WMATA 公交事件）
vre	Virginia Railway Express	通勤铁路	通过 Transitland 获取 GTFS
fairfax-connector	Fairfax Connector	公交	通过 Transitland 获取 GTFS + GTFS 实时提醒 + 票价页面
art	Arlington Transit	公交	通过 Transitland 获取 GTFS + 票价和提醒页面
dash	DASH (Alexandria) — 免费	公交	通过 Transitland 获取 GTFS + 乘客页面
cue	CUE (City of Fairfax)	公交	通过 Transitland 获取 GTFS
loudoun	Loudoun County Transit	公交	通过 Transitland 获取 GTFS + 票价和新闻页面
omniride	OmniRide (PRTC)	公交	通过 Transitland 获取 GTFS + 票价和服务更新页面
virginia-breeze	Virginia Breeze	城际客车	通过 Transitland 获取 GTFS + 预订页面
mta-md-bus	MTA Maryland Local Bus	公交	通过 Transitland 获取 GTFS
mta-md-commuter-bus	MTA Maryland Commuter Bus	通勤公交	通过 Transitland 获取 GTFS
mta-md-metro	MTA Maryland Metro SubwayLink	轨道交通	通过 Transitland 获取 GTFS
mta-md-light-rail	MTA Maryland Light RailLink	轨道交通	通过 Transitland 获取 GTFS
marc	MARC Train	通勤铁路	通过 Transitland 获取 GTFS
annapolis-transit	Annapolis Transit	公交	通过 Transitland 获取 GTFS
harbor-connector	Harbor Connector (Baltimore)	渡轮	通过 Transitland 获取 GTFS
potomac-valley	Potomac Valley Transit Authority	公交	通过 Transitland 获取 GTFS
dulles-shuttles	Dulles Airport Shuttles (车库、经济型停车场)	公交	通过 Transitland 获取 GTFS
charm-city-circulator	Charm City Circulator (Baltimore，免费)	公交	通过 Transitland 获取 GTFS
intercity-bus	城际巴士（组合数据源）	城际巴士	通过 Transitland 获取 GTFS
flixbus	FlixBus	城际巴士	通过 Transitland 获取 GTFS
amtrak	Amtrak	城际铁路	通过 Transitland 获取 GTFS

马里兰州和城际机构目前还没有手写的票价或乘客页面：助手会根据各机构的 GTFS 数据源，将乘客引导至其官方票价页面。

要添加一个机构，请复制 agencies/_template.toml — 参见 agencies/README.md。

发布 MCP 服务

https://dmvtransit.com/mcp 上的 MCP 服务开放使用：任何人都可以无需密钥连接 （MCP_OPEN），每个网络地址每分钟最多 120 次请求、每天最多 3,000 次（ChatGPT 和 Claude 从共享服务器发起调用） （MCP_OPEN_RATE_PER_MINUTE、MCP_OPEN_RATE_PER_DAY），所有无密钥调用者每天总计最多 8,000 次（MCP_OPEN_DAILY_CAP）。通过 transit-mcp mcp-keys add 创建的密钥享有更高的限额。 该服务的地址查询使用独立的 Google 配额 （MCP_GOOGLE_GEOCODING_MONTHLY_BUDGET），因此外部使用不会消耗网站的配额。每个工具都有标题和只读注释。各目录要求提供的页面为 /mcp-server（文档）、/privacy 和 /terms。

server.json 将服务描述为 com.dmvtransit/transit，用于官方 MCP Registry （于 2026-11-03 发布，版本为 1.0.0）。要发布新版本，请提高 version 并运行 python tools/registry_publish.py（添加 --dry-run 仅测试 登录）。该流程使用 HTTP 域名验证登录：公钥通过 /.well-known/mcp-registry-auth 提供，私钥保存在仓库外的 ~/.dmvtransit/mcp-registry-key.pem；请妥善保管。已发布的版本无法删除。

MCP 工具

工具	用途
search_transit_info(query, category?, limit?)	搜索各机构的票价、乘车指南和警报页面（不搜索路线或时刻表）
get_service_alerts(line?, station?, mode?, agency?)	实时服务中断信息：WMATA 事件及各机构的 GTFS-realtime 警报
get_elevator_escalator_status(station?)	电梯／自动扶梯停运信息
get_station_info(station)	线路、地址、停车场、出入口
get_fare(origin, destination, rider_type?)	Metrorail 站点间票价
get_metro_route(origin, destination)	Metrorail 线路、换乘、方向、首末班车、中断信息
list_topics() / get_guide(topic)	内容概览／完整乘车指南
list_agencies()	所有系统：角色、优势、服务区域、票价概览
find_stops_near(place, radius_m?, agency?)	跨机构查找地点附近的站点／车站
get_route(agency, query)	某条线路的运营日、运营时间、发车频率、终点站、票价
transfers_at(place, day?, time?)	步行距离内的其他系统，以及该时段是否可以换乘
how_to_pay(agency)	付款方式、购票地点、应用、SmarTrip／非接触式支付、换乘
geocode_address(query, limit?)	查找地址、酒店或地标的位置：规划行程前的步骤，便于大模型确认地点
plan_trip(origin, destination, depart_at?)	某个时间（默认当前时间）起 3 小时内的实际行程选项，包括步行、候车时间；现在出发时还会提供实时行程时间；支持地址、地点、车站或“lat,lon”
plan_connection(origin, destination, when?)	每段行程所乘系统、换乘枢纽、可用日期、票价——通过已配置的引擎查询；也支持地址
get_rider_reports(station?, line?, days?)	乘客近期在网站上提交的未经核实的报告（延误、拥挤、电梯、提示）
estimate_trip_cost(origin, destination, when?, rider_category?)	每段票价和总价

资源：transit://region/agencies、transit://wmata/freshness、 transit://wmata/guide/{topic}。

在其他客户端中使用 MCP 服务

通过 Web，供另一台机器上的大模型或应用使用：https://dmvtransit.com/mcp （MCP Streamable HTTP），并通过 Authorization: Bearer <key> 发送 API 密钥。密钥和 限制见 deploy/README.md。如需自行运行： transit-mcp mcp-keys add "who it's for"，然后运行 transit-mcp serve --http （服务地址为 http://127.0.0.1:8766/mcp）。

在同一台机器上，通过 stdio 使用 — Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "dmv-transit": {
      "command": "C:\\path\\to\\transit_mcp\\.venv\\Scripts\\transit-mcp.exe",
      "args": ["serve"],
      "env": { "TRANSIT_MCP_DB": "C:\\path\\to\\transit_mcp\\transit.db" }
    }
  }
}

开发

.venv\Scripts\python.exe -m pip install -e ".[dev]"

.venv\Scripts\python.exe -m pytest

测试使用 tests/fixtures/ 中的固定数据离线运行（如果已安装 node，则会运行 Node 引擎测试）。设置说明见 .env.example。

法律声明

请参阅 NOTICE.md。WMATA API 数据依据其开发者许可协议使用；GTFS 数据源由各机构发布（通过 Transitland 找到）；抓取仅限公开且允许 robots 访问的页面，并实施速率限制且注明来源。 与 WMATA 或所列任何机构均无关联。