Rhein-Ruhr Fahrplan MCP

rhein-ruhr-fahrplan-mcp

面向莱茵-鲁尔地区公共交通时刻表数据的 MCP 服务（数据基础：莱茵-鲁尔交通联盟的开放数据）。PyPI 页面：https://pypi.org/project/rhein-ruhr-fahrplan-mcp/

两大数据支柱，均无需密钥：

支柱	来源	内容
计划时刻表（可选）	VRR-GTFS（公共交通开放数据，CKAN API）→ SQLite	仅包含配置的交通运营商（FAHRPLAN_AGENCY_IDS）；例如 NIAG：123 条线路、6.975 次行程、3.869 个站点
实时数据（始终启用）	VRR-EFA efa.vrr.de	全联盟区域的实时出发/到达信息，含预测、延误、站台和服务中断提示

**默认仅提供实时数据：**不做任何配置时，服务会立即启动，并通过 EFA 接口提供所有实时工具。此时 GTFS 工具（计划时刻表、站点索引）会显示清晰提示及设置指南——这是有意为之，因为不加筛选地导入会创建完整数据库（约 500 MB，约 700 万条停靠时间记录）。

工具（9 个）

工具	来源	用途
next_departures	EFA（实时）	提供含实时预测的出发信息
next_arrivals	EFA（实时）	提供含实时预测的到达信息
plan_connection	EFA（实时）	查询整个网络中从 A 到 B 的路线
line_disruptions	EFA（实时）	查询当前的服务中断/施工/绕行信息
find_stop	GTFS → EFA 回退	查找站点（解析 DHID）
stop_schedule	GTFS	查询计划时刻表（也支持明天/后天）
sync_status	GTFS	查看数据源状态：版本、有效期、行数
update_feed	GTFS	更新数据源（仅在有新资源时；具备幂等性）
get_default_start	GTFS → EFA	解析配置的默认起始站点（FAHRPLAN_DEFAULT_START）

快速开始

方式 A：uvx（stdio，无需 Docker）

uvx rhein-ruhr-fahrplan-mcp

或永久安装：

uv tool install rhein-ruhr-fahrplan-mcp
rhein-ruhr-fahrplan-mcp

• 立即启动（仅实时数据）。如需 GTFS 计划时刻表，只需设置一次环境变量（见下文），然后调用 update_feed 或重启服务——导入随后会在后台自动运行（约 1–2 分钟，下载 39 MB）。
• 固定数据库路径：~/.local/share/rhein-ruhr-fahrplan-mcp/fahrplan.db（XDG 路径，不受当前工作目录影响；可通过 FAHRPLAN_DB_PATH 覆盖）。

mcphub/客户端注册（stdio 类型）：

{
  "fahrplan-mcp": {
    "type": "stdio",
    "command": "uvx",
    "args": ["rhein-ruhr-fahrplan-mcp"],
    "env": {"FAHRPLAN_AGENCY_IDS": "nia-25"}
  }
}

（env 为可选项——不配置 Agencies 时，仅运行实时模式。）

方式 B：Docker（Streamable HTTP）

docker compose up -d --build

在 Hub 中注册为 Streamable HTTP 服务（通过 compose.override.yaml 连接网络，详见部署）：

http://fahrplan-mcp:8080/mcp

配置：交通运营商（FAHRPLAN_AGENCY_IDS）

GTFS 导入会筛选 VRR Feed 中的 agency_ids。设置一个或多个：

# z. B. nur NIAG (Kreise Kleve & Wesel):
export FAHRPLAN_AGENCY_IDS=nia-25

# oder mehrere Unternehmen:
export FAHRPLAN_AGENCY_IDS=nia-25,swk-02,dvg-20

在 compose.yaml 中：

    environment:
      - FAHRPLAN_AGENCY_IDS=nia-25
      # - FAHRPLAN_OPERATOR=NIAG   # optional: Live-Abfahrten auch filtern

未设置 FAHRPLAN_AGENCY_IDS 时：

• 实时工具（next_departures、next_arrivals、plan_connection、line_disruptions）正常工作（整个区域，所有运营商）
• GTFS 工具（带索引的 find_stop、stop_schedule、sync_status）和自动导入会返回配置提示，而不是执行导入

交通运营商（精选）

agency_ids 来自 VRR-GTFS Feed（agency.txt，截至 2026 年 8 月）。常见运营商：

agency_id	运营商	区域/服务
nia-25	Niederrheinische Verkehrsbetriebe	公交，Kleve 和 Wesel 两县
dvg-20	Duisburger Verkehrsgesellschaft	Duisburg 公交/有轨电车
swk-02	SWK MOBIL	Krefeld
new-80	NEW mobil und aktiv M'gladbach	Mönchengladbach
vvg-65	NEW mobil und aktiv Viersen	Viersen
btm-70, rbg-70	Rheinbahn	Düsseldorf
bgs-00, bgs-30–bgs-34	BOGESTRA	Bochum/Gelsenkirchen
btm-13, eva-10–eva-12	Ruhrbahn	Essen/Mülheim
dsw-36–dsw-39	DSW21	Dortmund
sto-15, btm-15, eva-15	STOAG	Oberhausen
wsw-16, wsw-66	WSW mobil	Wuppertal
hst-00, hst-50	Hagener Straßenbahn	Hagen
sws-18	Stadtwerke Solingen	Solingen
swr-16	Stadtwerke Remscheid	Remscheid
ver-45	VER	Ennepe-Ruhr-Kreis
ves-40	Vestische	Recklinghausen/Marl
bvr-88	BVR Busverkehr Rheinland	Rheinland 公交
bsm-76	Bahnen der Stadt Monheim	Monheim
hcr-35	Straßenbahn Herne-Castrop	Herne/Castrop
swn-60	Stadtwerke Neuss	Neuss
ddb-8003	DB Regio NRW	NRW 区域列车
ddb-NX	National Express	Ruhrgebiet 区域列车
ddb-RR	RheinRuhrBahn	区域列车
ddb-R2	eurobahn	区域列车
ddb-W3	WestfalenBahn	区域列车
ddb-N2	NordWestBahn	区域列车
ddb-M2	REGIOBAHN	区域列车

Feed 中的铁路货运/包车条目（Train Charter Services、Train Rental International、Ulmer Eisenbahnfreunde 等）与客运无关。

完整列表： 当前 Feed 中的 agency.txt（通过下方的 CKAN-API 下载）——包含全部 58 个 ID 及名称。可以用 Python 查看：

python3 -c "import csv; [print(r['agency_id'], '|', r['agency_name'])
             for r in csv.DictReader(open('agency.txt'))]"

架构

┌─────────────────────── Server (stdio | http) ─────────────────────────┐
│                                                                        │
│  FastMCP                                                               │
│    ├── Live: EFA-Client (urllib, keyless)  ← immer aktiv                │
│    │     efa.vrr.de/standard/XML_DM_REQUEST (rapidJSON)               │
│    │     XML_TRIP_REQUEST2, XML_STOPFINDER_REQUEST                    │
│    └── Soll: GTFS-SQLite (nur mit FAHRPLAN_AGENCY_IDS) ← Auto-Update  │
│          CKAN-API (alle 6 h) → bei Neuheit: atomarer Import            │
└────────────────────────────────────────────────────────────────────────┘

特性

• 默认仅实时数据： 无需配置即可完整使用（实时工具）；设置 FAHRPLAN_AGENCY_IDS 后启用 GTFS 部分。
• 自动更新（设置 Agencies 后）：守护线程每隔 FAHRPLAN_FEED_CHECK_INTERVAL 秒（默认 6 小时）检查 CKAN-API；仅在发现新资源时导入——通过 .tmp + os.replace() 原子执行。初始导入和自动导入共用同一把锁（不会重复导入）。
• 实时数据运营商筛选： FAHRPLAN_OPERATOR（例如 NIAG）用于筛选 next_departures/next_arrivals；plan_connection 会优先按匹配结果排序。留空 = 所有运营商。
• 无需 API 密钥，无需账号。 VRR 开放数据使用条款：允许测试/业余/开发用途；如需长期公开使用，请发送邮件至 [email protected]。

部署（Docker）

HTTP 模式仅在容器网络中监听 :8080/mcp（不开放 Host 端口）。若要连接到现有 Docker 网络中的 MCP Hub，请在 compose.yaml 旁创建本地文件 compose.override.yaml：

services:
  fahrplan-mcp:
    networks:
      - mein-hub-netz   # Name des Netzes, in dem der Hub läuft

networks:
  mein-hub-netz:
    external: true

docker compose up -d 会自动合并 Override。该 Override 文件因环境而异，不应提交到仓库（已在 .gitignore 中）。

配置（Env）

变量	默认值	含义
FAHRPLAN_AGENCY_IDS	(空)	用于计划时刻表导入的逗号分隔 GTFS Agency ID。为空 = 仅实时数据；GTFS 工具会返回配置提示
FAHRPLAN_DEFAULT_START	(空)	默认起点站（DHID、EFA-ID 或唯一名称——可通过 find_stop 获取匹配的 ID）；可通过 get_default_start 查询
FAHRPLAN_OPERATOR	(空)	实时运营商筛选条件（例如 NIAG）；为空 = 所有公司
FAHRPLAN_DB_PATH	~/.local/share/rhein-ruhr-fahrplan-mcp/fahrplan.db	SQLite 数据库路径（Dockerfile：/data/fahrplan.db）
FAHRPLAN_MCP_TRANSPORT	stdio	stdio 或 http（Dockerfile 设置为 http）
FAHRPLAN_MCP_HOST / FAHRPLAN_MCP_PORT	0.0.0.0:8080（Dockerfile）	仅限 http 模式
FAHRPLAN_FEED_CHECK_INTERVAL	21600（6 h）	CKAN 检查；0 禁用自动更新

已验证的 EFA 特性（注意事项）

• outputFormat=rapidJSON：响应键名为 stopEvents/journeys（而不是 departureList/trips）。
• 站点名称可能有歧义 → 响应会包含 locations[] 建议项，且事件列表为空。因此：始终通过 DHID/ID 解析。
• GTFS parent_station 中的 …_Parent 后缀不被 EFA 接受 → 使用不带后缀的 DHID。
• 对于到站信息（itdTripDateTimeDepArr=arr），时间字段仍名为 departureTimePlanned/-Estimated。
• EFA 返回的所有时间都带有 Z 后缀（UTC）——客户端会先将其转换为 Europe/Berlin 时间，再输出（此前工具错误地显示了 UTC，看起来像是忽略了 departure_time 参数；已在 v1.2.1 中修复）。
• 延误按 UTC 时间差计算——不受时区影响，结果正确。
• MS_REQUEST（消息端点）返回 HTTP 400 → 从 DM 响应内嵌的 infos[] 中提取服务中断信息。
• calcNumberRequests 在 rapidJSON 中无法可靠工作 → plan_connection 返回的换乘方案可能多于 max_results（结果正确，仅数量限制较宽松）。

GTFS Feed 详情

• CKAN 数据集：496eea5d-d6ef-4dc2-aeb0-d15c4fbf3178（“Soll-Fahrplandaten VRR”），API：https://opendata.ruhr/api/3/action/package_show?id=…
• 资源 UUID 每月更换 → 导入时始终通过 CKAN API 获取最新 UUID。
• 筛选条件：agency_id IN (FAHRPLAN_AGENCY_IDS)；传递引用的行也会保留。
• 整个 Feed 的 stop_times.txt（约 700 万行）采用流式处理（首个列表版本因内存不足被终止）。
• 未筛选的整个 Feed 会生成约 500 MB 的数据库——因此有意不设为默认导入。

开发

git clone … && cd rhein-ruhr-fahrplan-mcp
uv venv && source .venv/bin/activate
uv pip install -e .
rhein-ruhr-fahrplan-mcp                   # stdio starten (Live-Only)
FAHRPLAN_AGENCY_IDS=nia-25 rhein-ruhr-fahrplan-mcp   # mit GTFS-Sollplan
python3 tests/stdio_e2e.py $(command -v rhein-ruhr-fahrplan-mcp)      # stdio-E2E
FAHRPLAN_AGENCY_IDS=nia-25 python3 tests/stdio_fullcycle.py $(command -v rhein-ruhr-fahrplan-mcp)  # inkl. Autoimport

发布：提升 pyproject.toml 中的版本号 → 提交 → git tag vX.Y.Z && git push origin vX.Y.Z——GitHub Action 会自动发布到 PyPI（Trusted Publishing）。