transit-mcp-server

用于 511.org SF Bay Open Data 公交 API 的 MCP 服务器。为 LLM 提供实时的湾区公交数据——包括运营机构、线路、站点、实时发车信息、车辆位置和服务警报——覆盖 BART、Muni、AC Transit、Caltrain、VTA 以及所有其他向 511 报告的运营机构。

6 个工具，全部只读。

要求

• Node.js 18+

• 从 https://511.org/open-data/token 获取免费的 511 API 令牌

Related MCP server: Bay Wheels MCP Server

安装

npm install
npm run build

配置

{
  "mcpServers": {
    "transit": {
      "command": "node",
      "args": ["/absolute/path/to/transit-mcp-server/dist/index.js"],
      "env": { "TRANSIT_511_API_KEY": "your-token-here" }
    }
  }
}

配额是主要限制

511 允许每个密钥每小时 60 次请求，所有端点共享。这个限制足以影响这些工具的使用方式：

• 一次性解析运营机构代码和站点代码，然后重复使用。它们不会改变。

• 优先使用不带 operator_id 的 transit_list_service_alerts——一次调用即可覆盖所有机构。

• 切勿循环轮询 transit_next_departures。通勤途中十次检查就占用了每小时预算的六分之一。

transit_list_operators 会报告剩余预算，该值从 511 在每个响应中返回的 RateLimit-Remaining 头读取。超出配额会返回 429；如需增加配额，请联系 transitdata@511.org。

部署（用于 Claude 移动端 / claude.ai 连接器）

与任何托管的 MCP 服务器相同：使用 openssl rand -hex 32 生成路径密钥，在平台仪表板中设置 TRANSIT_511_API_KEY 和 MCP_PATH_SECRET，附带的 Dockerfile 和 railway.json 可直接在 Railway、Render 或 Fly 上使用。没有密钥时，服务器拒绝在公共接口上启动。/healthz 是一个无需认证的存活探针。

然后在浏览器中打开 claude.ai：Customize → Connectors → Add custom connector，URL 为 https://your-app.up.railway.app/mcp/<secret>。

工具

网络 — transit_list_operators、transit_list_lines、transit_find_stops

实时 — transit_next_departures、transit_list_vehicles

警报 — transit_list_service_alerts

每个工具都接受 response_format: "markdown" | "json"。默认是 Markdown，针对 LLM 阅读进行了优化；JSON 是完整的结构化负载。无论格式如何，structuredContent 始终会被填充。

示例

“下一班 N Judah 是什么时候？” → 使用 operator_id="SF" 和 query="judah" 调用 transit_find_stops 获取站点代码，然后使用该代码和 line="N" 调用 transit_next_departures。

“BART 运行正常吗？” → 使用 operator_id="BA" 调用 transit_list_service_alerts。

“我的通勤路上有什么问题吗？” → 不带运营机构调用 transit_list_service_alerts——一次调用即可覆盖所有湾区机构。

“现在火车在哪里？” → 使用 operator_id="BA" 调用 transit_list_vehicles。

设计说明

天生只读。 511 不提供任何写端点，每个工具都带有 readOnlyHint: true。测试对此进行了断言。

每个端点映射一个 operator_id。 511 在其静态端点上将此参数称为 operator_id，在其实时端点上称为 agency，但值相同。这里的每个工具都接受 operator_id，客户端会进行映射。这种分裂是 511 的问题，而不是调用方的问题。

两个实时端点确实有不同的封装结构。 StopMonitoring 没有 Siri 根包装；VehicleMonitoring 有。已发布的规范显示两者都有——但规范是错误的，按照文档中的结构解析发车信息将一无所获。两者都按照实时 API 实际输出的方式进行解析，并有测试分别固定。

倒计时基于到达时间，而非发车时间。 在几乎每一行真实数据中，ExpectedDepartureTime 都是 null，因此基于它进行倒计时会显示一个没有服务的站点。ExpectedArrivalTime 才是可靠的字段。

解析前会去除 UTF-8 BOM。 511 在 JSON 正文前加上 U+FEFF，这会导致简单的 JSON.parse 在完全有效的负载上抛出异常。认证失败是纯文本且没有 BOM，因此去除操作在状态检查之后进行。

看似数字和布尔值的值往往并非如此。 坐标和方位角以 JSON 字符串形式到达，VehicleAtStop 是字符串 "false"，并且在整个数据中使用 "" 表示 null。盲目强制转换会将缺失的位置变成看似有效的 0,0（非洲海岸外），因此空字符串被视为缺失而非零。

纪元零哨兵不是时间戳。 已排定但未分配车辆的行程会报告 RecordedAtTime 为 1970-01-01T00:00:00Z。它显示为“尚未分配车辆”，而不是“记录于 56 年前”。

GTFS-Realtime 枚举被解码。 511 的 JSON 警报渲染输出 "effect": 3，而 XML 渲染则显示 SignificantDelays。原因和影响都被映射回文字。

511 内部的伪机构被过滤掉。 5E、5F、5O 和 5S 分别是 511 应急、翻牌标志、运营和员工——它们出现在运营机构列表中，但不携带任何服务数据。

一切都使用太平洋时间。 时间戳以 UTC 到达，并以 America/Los_Angeles 渲染，因此夏令时在这里处理一次，而不是由模型每年处理两次。请注意，511 自己的 TimeZone 字段为每个湾区机构报告 America/Vancouver——这是一个已知的上游数据错误，被有意忽略。

截断总是被明确说明。 511 不进行分页；它返回整个集合，而大型机构有数千个站点。工具接受客户端 limit，每个被截断的结果都会说明省略了多少，因为静默缩短的列表会被理解为“这就是全部”。

注意事项

• 每小时配额为所有端点共 60 次请求。这是任何工作流的硬性限制。

• 运营机构代码容易猜错：VTA 是 SC（不是 VT），Capitol Corridor 是 AM（不是 CC），Tri Delta 是 3D。transit_list_operators 会在其输出中打印这些陷阱。

• 站点代码属于一个运营机构，不能在不同机构之间互换。

• transit_find_stops 在此服务器上进行过滤，因此窄查询不会节省配额——无论如何都会获取完整的站点列表。

• 实时预测大约提前 90 分钟，511 会从发车信息源中省略线路的最终仅到达站点。

• tripupdates 和 vehiclepositions 仅支持 protobuf，没有 JSON 选项，因此有意不暴露它们——支持它们意味着为 SIRI 端点已覆盖的数据引入 protobuf 依赖。

项目结构

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # enums, limits, operator-code traps
├── types.ts               # interfaces for every 511 entity
├── services/
│   └── transit-client.ts  # fetch wrapper, auth, BOM stripping, quota tracking, errors
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # limiting, truncation, Pacific-time rendering
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── network.ts         # operators, lines, stops
    ├── departures.ts      # real-time arrivals and vehicles
    └── alerts.ts          # service alerts

测试

npm run build
npm test            # 42 checks: handshake, BOM, envelopes, quirks, errors (mocked API)
npm run test:http   # 17 checks: config validation, path-secret gating, method handling, origins

两个测试套件都针对本地模拟运行，该模拟故意重现 511 的真实怪癖——BOM、缺失的 Siri 包装、字符串化的布尔值和坐标、纪元哨兵以及纯文本错误正文——因为这些正是简单客户端容易出错的地方。