内容
# GTFS 公共交通查询服务器
这是一个用于查询公共交通信息的MCP服务器，基于GTFS时间表和GTFS-RT实时动态信息。它适用于任何兼容GTFS的公共交通系统，并包含一个现成的纽约市地铁（MTA）的配置文件。
您可以询问诸如 *"下一班L列车从Bedford Av什么时候出发？"*, *"G列车有哪些服务警报？"*, 或 *"7号列车有哪些站点？"*。
**服务警报示例**
**到站时间示例**
## 快速开始
需要Node 22+。
```bash
git clone https://github.com/jdamcd/gtfs-mcp.git && cd gtfs-mcp
npm install
npm run build
```
将以下内容添加到您的Claude Desktop配置文件（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"gtfs": {
"command": "node",
"args": ["/absolute/path/to/gtfs-mcp/dist/index.js"],
"env": {
"GTFS_MCP_CONFIG": "/absolute/path/to/gtfs-mcp/config.mta.json"
}
}
}
}
```
重启Claude Desktop并询问一个纽约市地铁问题。第一次查询会触发GTFS时间表下载（MTA大约30秒）。后续查询速度很快。
### 添加其他公共交通系统
服务器读取一个JSON配置文件，定义一个或多个公共交通系统，由`GTFS_MCP_CONFIG`指向。在 [Mobility Database](https://mobilitydatabase.org/) 中查找您当地机构的动态信息源。
```json
{
"systems": [
{
"id": "mbta",
"name": "MBTA Boston",
"schedule_url": "https://cdn.mbta.com/MBTA_GTFS.zip",
"timezone": "America/New_York",
"realtime": {
"trip_updates": ["https://cdn.mbta.com/realtime/TripUpdates.pb"],
"vehicle_positions": ["https://cdn.mbta.com/realtime/VehiclePositions.pb"],
"alerts": ["https://cdn.mbta.com/realtime/Alerts.pb"]
},
"auth": null
}
],
"data_dir": "~/.gtfs-mcp/data",
"schedule_refresh_hours": 24
}
```
每个实时动态信息源类型接受多个URL（例如，MTA将行程更新分散在8个动态信息源中）。如果系统不提供某个动态信息源，请将其设置为`[]`。
`timezone` 是机构的IANA时区（例如 `"Europe/London"`）。它用于将计划的站点时间与“现在”进行比较，并在响应中渲染时间，而不受服务器时区的影响。
### 身份验证动态信息源
一些公共交通API需要API密钥。在运行时，从环境变量中读取密钥。在Claude Desktop的`env`块中设置它们与`GTFS_MCP_CONFIG`一起。
**查询参数**：
```json
{
"auth": {
"type": "query_param",
"param_name": "api_key",
"key_env": "MY_API_KEY"
}
}
```
**头部**：
```json
{
"auth": {
"type": "header",
"header_name": "X-Api-Key",
"key_env": "MY_API_KEY"
}
}
```
对于不需要身份验证的系统，将`auth`设置为`null`。
## 工具
| 工具 | 描述 | 参数 |
|------|-------------|------------|
| `list_systems` | 列出所有已配置的公共交通系统 | — |
| `search_stops` | 按名称搜索站点 | `system`, `query`, `limit?` |
| `find_nearby_stops` | 查找附近的站点，按距离排序 | `system`, `lat`, `lon`, `radius_m?`, `limit?` |
| `get_stop` | 站点详情和为其服务的线路 | `system`, `stop_id` |
| `get_arrivals` | 即将到站的车辆，包含实时延误 | `system`, `stop_id`, `route_id?`, `limit?` |
| `list_routes` | 系统中的线路，带有可选名称筛选和分页 | `system`, `query?`, `route_type?`, `limit?`, `offset?` |
| `get_route` | 线路详情，包含有序的站点列表 | `system`, `route_id`, `direction_id?` |
| `get_alerts` | 活跃的服务警报 | `system`, `route_id?`, `stop_id?` |
| `get_vehicles` | 实时车辆位置 | `system`, `route_id?` |
| `get_trip` | 行程的站点序列，包含实时延误 | `system`, `trip_id` |
| `get_feed_health` | 实时动态信息源诊断：每个URL的获取结果、实体计数、 oldest header age | `system` |
`system` 参数是来自您的配置的系统ID（例如 `"mta-subway"`）。ID在工具之间流动 - 例如 `search_stops` 返回一个 `stop_id`，而 `get_arrivals` 则使用它。
## 资源
| URI | 描述 |
|-----|-------------|
| `gtfs://systems` | 每个已配置系统的Markdown概述：id、名称、时区以及每个动态信息源类型连接的动态信息源URL数量。 |
支持资源的客户端（Claude Desktop，MCP Inspector）可以附加此内容作为上下文 - 这对于在一个对话中确定服务器实际了解哪些系统很有帮助，而无需调用 `list_systems`。
## 提示
| 名称 | 描述 | 参数 |
|------|-------------|-----------|
| `transit-status` | 当前系统中活跃警报的摘要。在Claude Desktop中，这出现在附件（“+”）菜单中。 | `system?` - 可选的系统ID，用于限定到一个系统。 |
提示返回一个导航消息，指示模型调用相关系统的 `get_alerts` 并生成一个简洁的摘要。模型仍然通过工具调用完成工作 - 提示只是框架。
## 开发
```bash
npm test
```
### 评估
LLM评估使用 [promptfoo](https://promptfoo.dev/) 验证模型是否选择了自然语言公共交通查询的正确工具。需要在 `.env` 或环境中设置 `ANTHROPIC_API_KEY`。
```bash
npm run build
npm run eval
npm run eval:view # 用于检查结果的Web UI
```
### MCP检查器
在没有Claude客户端的情况下交互式测试工具：
```bash
GTFS_MCP_CONFIG=./config.mta.json npx @modelcontextprotocol/inspector node dist/index.js
```
### 不变性测试
`scripts/campaign.ts` 在 `config.testing.json` 中的系统中针对真实的GTFS动态信息源运行整个工具表面，检查响应中的不变性违规，并在 `campaign-results/` 下写入每个调用的JSON。
> ⚠️ 这将为所有已配置的系统下载静态GTFS数据到 `./data-testing/` - 最多约10GB。
```bash
GTFS_MCP_CONFIG=./config.testing.json npx tsx scripts/campaign.ts --smoke # 所有系统快速通过
GTFS_MCP_CONFIG=./config.testing.json npx tsx scripts/campaign.ts --deep mbta,vbb # 选择系统的完整阶段
```
