🚇 Metro MCP

面向美国公共交通系统（DC 地铁与纽约地铁）的 Model Context Protocol 服务器

一个统一的远程 Model Context Protocol (MCP) 服务器，支持多个美国公共交通系统。目前支持华盛顿特区地铁（WMATA）和纽约市地铁（MTA）。专为与支持 MCP 的客户端（如 Claude Desktop、Cursor、Codex 以及任何支持 Streamable HTTP MCP 服务器的客户端）无缝集成而构建。

快速链接： 快速开始 • 你能做什么 • Transit Board • 部署 • 客户端集成

你能做什么

在 Claude Desktop 或任何支持 MCP 的客户端中，用自然语言提问关于 DC 地铁或纽约地铁的问题：

🚆 实时交通信息

华盛顿特区：

• "杜邦环岛下一班红线列车什么时候到？"

• "有哪些公交线路可用？"

• "查找杜邦环岛附近的公交站"

• "现在所有 30N 路公交车在哪里？"

• "1001195 号站点的下一班公交车什么时候到？"

• "显示地铁系统当前运行的所有列车"

• "蓝线现在有延误吗？"

• "联合车站的所有电梯都正常工作吗？"

纽约市：

• "时代广场下一班 1 号线列车什么时候到？"

• "A/C 线有延误吗？"

• "哪些列车到达中央车站？"

• "A 线是什么，它开往哪里？"

• "从时代广场步行可以到达哪些附近车站？"

• "在时代广场站台之间步行需要多长时间？"

🗺️ 车站信息与导航

华盛顿特区：

• "史密森尼地铁站在哪里？"

• "显示绿线上的所有车站"

纽约市：

• "联合广场车站在哪里？"

• "显示纽约地铁所有 496 个车站"

• "哪些车站与时代广场相连？"

• "解释快车和慢车之间的区别"

♿ 无障碍设施

华盛顿特区（电梯故障）：

• "从这里到国家机场之间有没有电梯故障？"

• "现在哪些 DC 地铁站的电梯正常工作？"

🔔 服务监控

两个城市：

• "纽约现在有交通延误吗？"

• "DC 地铁橙线运行正常吗？"

• "比较 DC 地铁和纽约地铁的服务质量"

📊 系统信息

华盛顿特区：

• 所有地铁站的完整列表，包含坐标

• 关于全部六条地铁线路（红线、蓝线、橙线、银线、绿线、黄线）的信息

纽约市：

• 完整覆盖： 所有 496 个纽约地铁站，包含坐标

• 换乘信息： 相连车站之间的步行时间（87 个车站有换乘）

• 线路描述： 所有 29 条线路的详细服务模式（快车与慢车、运营时间）

• 站台清晰度： 解释方向性站台（例如，"127N" = 时代广场北行）

Related MCP server: marta-mcp

快速开始

使用公共服务器

最快的入门方式是使用托管实例：

1. 打开你的 MCP 客户端

2. 添加此 URL：https://metro-mcp.anuragd.me/mcp

3. 点击"连接"并通过 GitHub 授权

4. 开始询问关于 DC 地铁或纽约地铁的问题

部署你自己的实例

想运行自己的实例？请参阅下面的部署部分。

部署

前提条件

• WMATA API 密钥（必需）

• Cloudflare 账户（免费套餐即可）

• Bun 用于包管理

• Node.js 用于 Wrangler 和 Workerd Vitest 池；Bun 仍然是唯一的包管理器和锁文件所有者

• GitHub OAuth 应用（用于身份验证）

环境设置

安装 bun.lock 记录的确切依赖：

bun install --frozen-lockfile

对于本地开发，创建一个专用的 GitHub OAuth 应用，其回调地址必须为 http://localhost:8787/callback。然后复制规范的 .dev.vars.example 模板，替换所有 replace-with-... 占位符，并启动 Wrangler：

cp .dev.vars.example .dev.vars
bun run dev

保持模板中的 http://localhost:8787 源、localhost 主机/源允许列表、回调以及 ENVIRONMENT=development 值在一起。在 Wrangler 的默认本地模式下，配置的 OAUTH_KV 绑定使用 .wrangler 下的本地非生产存储；它不会读取或写入已部署的生产或预览命名空间。对于正常的本地开发，不要添加 --remote。

为每个部署环境创建一个 OAuth Provider 命名空间，并将其 ID 放入相应的 OAUTH_KV 绑定中：

bunx wrangler kv namespace create OAUTH_KV
bunx wrangler kv namespace create OAUTH_KV_preview

生产环境和预览环境还必须使用不同的 GitHub OAuth 应用。将每个回调配置为 ${MCP_PUBLIC_ORIGIN}/callback；切勿将生产应用或 OAuth KV 用于预览。每个环境设置：

• MCP_PUBLIC_ORIGIN、MCP_ALLOWED_HOSTNAMES 和 MCP_ALLOWED_ORIGIN_HOSTNAMES

• OAUTH_REDIRECT_URI 以及该环境的公共 GitHub GITHUB_CLIENT_ID

• ENVIRONMENT（production、preview 或 development）

• OAUTH_KV，指向该环境专用的命名空间

以交互方式设置生产密钥。MCP_REQUEST_STATE_KEY 是一个稳定的、特定于环境的 32 字节或更长的密钥，仅用于签名的 MRTR 状态。JWT_SECRET 暂时保留用于旧的 /mcp 受众桥接。

bunx wrangler secret put MCP_REQUEST_STATE_KEY
bunx wrangler secret put GITHUB_CLIENT_SECRET
bunx wrangler secret put WMATA_API_KEY
bunx wrangler secret put JWT_SECRET

为预览环境独立设置相同的四个密钥名称；命名的 Wrangler 环境不会继承生产密钥：

bunx wrangler secret put MCP_REQUEST_STATE_KEY --env preview
bunx wrangler secret put GITHUB_CLIENT_SECRET --env preview
bunx wrangler secret put WMATA_API_KEY --env preview
bunx wrangler secret put JWT_SECRET --env preview

Wrangler 必须同时包含 nodejs_compat 和 global_fetch_strictly_public。在任何批准的部署之前验证这两种形态：

bunx wrangler deploy --dry-run --outdir /tmp/metro-mcp-production
bunx wrangler deploy --dry-run --env preview --outdir /tmp/metro-mcp-preview

MCP 客户端集成

Claude

在 Claude Code 中使用规范的 Streamable HTTP 端点：

claude mcp add --transport http metro-mcp https://metro-mcp.anuragd.me/mcp

然后打开 /mcp，选择 metro-mcp，并完成 GitHub 登录和同意。Claude.ai/Desktop 用户可以在其计划和工作区策略允许的情况下，将相同的 URL 添加为远程自定义连接器。

Codex

codex mcp add metro-mcp --url https://metro-mcp.anuragd.me/mcp
codex mcp login metro-mcp --scopes transit:read

已检入的 mcp-config.json 显示了等效的通用远程 HTTP 配置。访问令牌和刷新令牌保留在客户端的凭据存储中；不要将它们粘贴到项目配置中。

传输兼容性

• MCP 2026-07-28 请求是无状态的，不需要 initialize。

• 普通工具、资源和提示仍然可用于 MCP 2025 无状态客户端。

• POST /sse 和 OPTIONS /sse 是 URL 别名，在授权之前重写为规范的 /mcp。

• 已移除旧的 HTTP+SSE。GET 和 DELETE 在 /sse 或 /mcp、会话消息 URL 以及 /sse/ 上返回 405。

• OAuth 受众和发现始终使用 https://metro-mcp.anuragd.me/mcp；/sse 永远不是 OAuth 资源。

OAuth 端点

Workers OAuth Provider 实现了带 PKCE 的 OAuth 2.1：

• 发现：/.well-known/oauth-authorization-server

• 注册：先使用 CIMD，/register 作为临时的动态客户端注册回退

• 授权：/authorize（GitHub OAuth 集成）

• 令牌：/token（带 PKCE 验证的授权码交换）

• 回调：/callback（GitHub OAuth 回调）

客户端会收到明确的 transit:read 同意屏幕。授权绑定到规范的 /mcp 资源；访问令牌最长持续 60 分钟，刷新令牌最长持续 30 天并在使用时轮换，承载令牌仅在 Authorization 头中接受。DCR 回退将于 2027-06-30 停用。

版本 5.0 要求对没有受众的令牌、绑定到 /sse 的令牌以及在旧 DCR 存储中注册的客户端重新授权。绑定到 /mcp 的现有兼容旧 JWT 在其嵌入的到期时间和 2026-11-30T00:00:00Z 中较早者停止工作。

支持的城市

服务器目前支持以下交通系统：

可用的 MCP 工具

服务器通过 MCP 协议公开以下工具：

总计：13 个 MCP 工具（11 个核心 + 2 个新的纽约专用工具）

MCP 应用：Transit Board

上述所有 13 个工具都引用一个自包含的 Transit Board MCP 应用。支持 Apps 的主机可以将每个结果渲染为专用的到达、服务、车站/网络、线路或车辆视图。不支持 Apps 的主机接收相同的 content 文本回退和 structuredContent 契约；该增强不会添加工具或更改交通调用。

编译后的应用提交在 public/apps/transit-board.html。该公共资产仅包含应用程序代码：不嵌入任何交通结果、身份、令牌、密钥或配置值。沙盒视图不进行直接的浏览器网络请求，不使用浏览器存储，也不请求浏览器权限。刷新是唯一的服务器交互，并通过主机以原始参数传递给来源允许列表中的工具。

使用以下命令构建并运行确定性的本地 Apps 验收套件：

bun run build:apps
bun run test:apps

有关确切的主机边界、所有十三个视图映射、Chromium 覆盖范围以及 Apps 渲染与回退客户端验收之间的区别，请参阅 docs/mcp-apps-verification.md。对于此版本，Codex 作为回退客户端验证 MCP 发现和普通工具结果；不声称 Codex 中的内联 Apps 渲染。

技术细节

MCP 协议

• 版本： MCP 2026-07-28，兼容普通 MCP 2025 无状态协议

• 传输方式： 无状态流式 HTTP，每个请求通过全新的 SDK v2 服务器处理。支持 JSON 和请求作用域的 SSE 响应；不声明协议会话、可恢复性和服务器推送。

• 认证： Cloudflare Workers OAuth Provider 负责发现、CIMD/DCR 校验、PKCE、RFC 9207 颁发者标识符、RFC 8707 资源绑定、RFC 9728 受保护资源元数据、刷新令牌轮换、吊销以及 Provider 令牌存储。

• 工具结果格式： 每个工具都会输出 structuredContent（与 outputSchema 匹配的强类型对象），同时附带旧版 content[0].text（序列化 JSON）以保持向后兼容。

• 工具注解： 每个工具都声明了 readOnlyHint、idempotentHint、openWorldHint，以便客户端能够呈现安全操作提示。

• 暴露的能力：

  • tools — 13 个公交查询工具（DC + NYC）

  • resources — 三个 transit:// URI 模板（stations、routes、incidents）

  • prompts — 三个预设模板（service-briefing、commute-planner、accessibility-check）

  • MRTR 输入 — 现代客户端在遇到歧义站点时收到 input_required；MCP 2025 客户端收到带有精确站点 ID 的确定性重试指引

  • 进度通知：当客户端通过 params._meta.progressToken 选择启用时，get_all_stations 会发出进度通知

公交 API

WMATA（华盛顿地铁）：

服务器对接官方 WMATA REST API。详情请访问 WMATA 开发者文档：

• 站点预测： 实时列车到站信息

• 站点信息： 站点名称、代码和位置

• 事件： 服务中断和公告

• 电梯/扶梯故障： 无障碍信息

MTA（纽约地铁）：

服务器使用 MTA 提供的 GTFS-Realtime 数据源。公共 API 端点（无需 API 密钥）：

• 实时数据源： Protocol Buffers 格式，每 30 秒更新一次

• 8 个独立数据源： 覆盖所有地铁线路（1-7、A/C/E、B/D/F/M 等）

• NYCT 扩展： 列车 ID、轨道分配和方向信息

• 服务警报： 内嵌于 GTFS-Realtime 警报实体中

托管

• 平台： Cloudflare Workers

• 静态资源： public/ 通过 Cloudflare Workers Static Assets 部署，并绑定为 env.ASSETS；Worker 优先处理 API/OAuth/MCP 路由，然后将落地页、文档、图片和图标请求委托给静态资源绑定。

• 存储：

  • 环境专属的 Cloudflare KV OAUTH_KV — OAuth Provider 授权、令牌和注册信息

  • 无活跃的协议会话存储。旧版 MetroMcpAgent 导出和原始 v1 迁移仅保留用于回滚，处于非活跃状态。

• 运行时： V8 隔离环境，全球边缘部署

源码结构

代码库为多城市公交支持而组织，职责划分清晰：

src/
├── index.ts              # Outer route normalization and Provider composition
├── public-handler.ts     # /info, OAuth UI, and static assets
├── route-normalizer.ts   # Exact /mcp admission and /sse URL alias
├── oauth/                # Provider configuration, GitHub consent, legacy bridge
├── mcp/                  # Stateless server factory, tools, resources, and prompts
├── mcp-agent.ts          # Inactive 4.x rollback class only
└── transit/              # WMATA and MTA clients with request cancellation

关键架构决策：

• 公交抽象： 通用 TransitAPIClient 接口使新增城市（BART、MBTA 等）变得简单

• 城市路由： 单个服务器通过 MCP 工具调用中的 city 参数处理所有城市

• 标准化响应： 所有公交客户端都返回标准化的 TransitStation、TransitPrediction 和 TransitIncident 类型

• 可扩展性： 新增城市只需实现抽象客户端类

验证与回滚

使用 bun run test 运行完整的本地测试套件。经过认证的符合性测试运行器需要操作员在进程环境中提供短期有效的 Provider 访问令牌；它从不存储令牌，也不会将其放入命令行参数中：

export MCP_CONFORMANCE_TARGET_URL=https://metro-mcp-preview.anuragd.me/mcp
export MCP_CONFORMANCE_ALLOW_REMOTE=1
read -rsp 'Short-lived MCP token: ' MCP_CONFORMANCE_TOKEN && export MCP_CONFORMANCE_TOKEN
./scripts/run-conformance.sh
unset MCP_CONFORMANCE_TOKEN

核心协议验收记录请参阅 docs/mcp-2026-verification.md，Transit Board 浏览器边界请参阅 docs/mcp-apps-verification.md。

回滚会恢复之前的 Worker 版本及其之前的绑定。在稳定期内，请勿删除原始的 MetroMcpAgent Durable Object 命名空间，也不要添加删除迁移；协议会话状态是可丢弃的，但保留该类以及原始 v1 迁移可以确保回滚的可能性。

回滚 Transit Board 会移除 Apps 元数据/资源、浏览器源码和构建依赖，同时保持公交提供方、OAuth、路由、绑定和版本不变。

贡献

欢迎贡献！您可以：

• 通过 GitHub Issues 报告错误或请求功能

• 提交包含改进的拉取请求

• 分享对 MCP 实现的反馈

许可证

MIT 许可证 — 详情请参阅 LICENSE 文件。

为华盛顿特区地铁社区倾心打造 ❤️