Caltrain MCP

🚀 加州火车MCP服务器（因为你喜欢等火车）

加州火车MCP服务器是一个基于Model Context Protocol (MCP)的服务器，它承诺能精准地告诉你下一班加州火车的到达时间，但实际上可能还是会晚点10分钟。该服务器使用真实的GTFS数据，所以这份失望也是“官方认证”的！

🚀 快速开始

安装依赖

# 如果你还没有安装uv（因为现在pip好像太主流了）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用uv安装依赖（祈祷它真的能成功）
uv sync

获取GTFS数据

服务器需要将加州火车的GTFS数据存放在src/caltrain_mcp/data/caltrain-ca-us/目录下。因为显然我们不能直接问火车它们在哪。

uv run python scripts/fetch_gtfs.py

这个神奇的脚本会下载包含以下内容的文件：

• stops.txt - 火车假装会停靠的所有站点
• trips.txt - 穿越时空的理论旅程
• stop_times.txt - 火车“应该”到达的时间（剧透：它们并不会按时到达）
• calendar.txt - 工作日和周末的时刻表（因为火车也需要工作与生活的平衡）

✨ 主要特性

• 🚆 “实时”火车时刻表 - 获取任意两个站点之间的下一班列车出发时间（实际到达时间可能会有正负无穷的偏差）
• 📍 站点查询 - 毕竟要记住31个站点实在太难了🤷‍♀️
• 🕐 特定时间查询 - 精确规划你的通勤行程，然后看着一切分崩离析
• ✨ 智能搜索 - 输入'sf'而不是完整名称，因为我们都很懒
• 📊 基于GTFS数据 - 我们使用与加州火车相同的数据，所以当出问题时，我们可以一起责怪他们

📦 安装指南

安装依赖

# 如果你还没有安装uv（因为现在pip好像太主流了）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用uv安装依赖（祈祷它真的能成功）
uv sync

获取GTFS数据

服务器需要将加州火车的GTFS数据存放在src/caltrain_mcp/data/caltrain-ca-us/目录下。因为显然我们不能直接问火车它们在哪。

uv run python scripts/fetch_gtfs.py

💻 使用示例

作为MCP服务器使用

这个服务器是为与像Claude Desktop这样的MCP客户端配合使用而设计的，而不是供人类直接运行（因为那样就太简单了）。以下是具体的使用方法：

与Claude Desktop配合使用

在你的Claude Desktop MCP配置文件中添加以下内容：

{
  "mcpServers": {
    "caltrain": {
      "command": "uvx",
      "args": ["caltrain-mcp"]
    }
  }
}

这将自动从PyPI安装并运行最新版本。

然后重启Claude Desktop，你就可以在对话中直接查询加州火车时刻表了！

与其他MCP客户端配合使用

任何兼容MCP的客户端都可以通过以下命令启动服务器：

uvx caltrain-mcp

服务器通过stdin/stdout使用MCP协议进行通信。直接运行时它不会有什么特别的表现，只是等待接收正确的MCP消息。

测试服务器（用于开发）

你可以通过直接导入来测试服务器是否正常工作：

from caltrain_mcp.server import next_trains, list_stations

# 测试查询下一班火车的功能（做好失望的准备）
result = await next_trains('San Jose Diridon', 'San Francisco')
print(result)  # 剧透：没有火车

# 测试列出所有站点的功能（总共31个，因为显然记住它们太难了）
stations = await list_stations()
print(stations)

📚 详细文档

可用工具

next_trains(origin, destination, when_iso=None)

礼貌地询问下一班火车何时到达。服务器会参考它的“水晶球”（GTFS数据），给你提供技术上准确的时间。 参数：

• origin (str) - 你当前所在的位置（可能正在后悔自己的人生选择）
• destination (str) - 你想去的地方（可能是除了这里的任何地方）
• when_iso (str, 可选) - 你想要出行的时间（就好像在公共交通中时间有任何意义一样）

示例：

# 查询从当前时间开始的下一班火车（也就是“现在就出发最好”）
next_trains('San Jose Diridon', 'San Francisco')

# 查询特定时间的火车（给那些认为时刻表有用的乐观主义者）
next_trains('Palo Alto', 'sf', '2025-05-23T06:00:00')

# 使用缩写（因为打字太累了）
next_trains('diridon', 'sf')

list_stations()

获取所有31个加州火车站点的列表，因为显然记住它们太难了。 返回值： 一个格式化的列表，让你意识到这列火车到底要去多少个地方。

站点名称识别

服务器支持多种偷懒的站点名称输入方式：

• 完整名称："San Jose Diridon Station"（给完美主义者）
• 简称："San Francisco"（给稍微不那么追求完美的人）
• 缩写："sf" → "San Francisco"（给真正的懒人）
• 部分匹配："diridon" 匹配 "San Jose Diridon Station"（当你懒得输入完整名称时）

可用站点

服务器覆盖了每一个加州火车站点，因为我们是完美主义者： 旧金山到圣何塞（主要路线）：

• 旧金山、22街、贝肖尔、南旧金山、圣布鲁诺、米尔布雷、百老汇、伯林盖姆、圣马特奥、海沃德公园、希尔斯代尔、贝尔蒙特、圣卡洛斯、红木城、门洛帕克、帕洛阿尔托、斯坦福、加州大道、圣安东尼奥、山景城、桑尼维尔、劳伦斯、圣克拉拉、大学公园、圣何塞迪里顿

圣何塞到吉尔罗伊（“这玩意为什么存在”的支线）：

• 塔米恩、国会山、 Blossom Hill、摩根山、圣马丁、吉尔罗伊

示例输出

🚆 2025年5月22日星期四，从圣何塞迪里顿车站到旧金山加州火车站的下一班加州火车出发时间：
• 153次列车：17:58:00 → 19:16:00（开往旧金山）
• 527次列车：18:22:00 → 19:22:00（开往旧金山）
• 155次列车：18:28:00 → 19:46:00（开往旧金山）
• 429次列车：18:43:00 → 19:53:00（开往旧金山）
• 157次列车：18:58:00 → 20:16:00（开往旧金山）

实际到达时间可能会有所不同。副作用可能包括存在主义的恐惧和对远程工作的深切感激。

🔧 技术细节

• GTFS数据处理：我们自动处理站点及其站台之间的关系（因为显然火车很复杂）
• 服务日历：遵循工作日/周末时刻表（火车也需要美容觉）
• 数据类型处理：处理GTFS文件中混合的整数/字符串格式的混乱情况
• 时间解析：支持24小时以上的格式，以适应那些传说中的深夜服务
• 错误处理：当你输入“纳尼亚”作为站点名称时，能优雅地失败

项目结构

caltrain-mcp/
├── .github/workflows/         # GitHub Actions（CI/CD的主宰）
│   ├── ci.yml                 # 主要的CI管道（代码检查、测试等）
│   └── update-gtfs.yml        # 自动更新GTFS数据
├── src/caltrain_mcp/          # 主包（因为现代Python需要结构）
│   ├── data/caltrain-ca-us/   # GTFS数据存储（CSV文件退休的地方）
│   ├── __init__.py            # 包初始化（Python的仪式）
│   ├── __main__.py            # python -m caltrain_mcp的入口点
│   ├── server.py              # MCP服务器实现（魔法发生的地方）
│   └── gtfs.py                # GTFS数据处理（也就是“与CSV文件搏斗”）
├── scripts/                   # 实用脚本（配角）
│   ├── __init__.py            # 使脚本成为一个合适的Python包
│   ├── fetch_gtfs.py          # 下载最新的“失望数据”
│   └── lint.py                # 本地运行所有CI检查（避免尴尬）
├── tests/                     # 测试套件（因为要“信任但验证”）
│   ├── conftest.py            # 共享的测试夹具（共同基础）
│   ├── test_gtfs.py           # GTFS功能测试（8个数据处理测试）
│   ├── test_server.py         # 服务器功能测试（4个MCP协议测试）
│   └── test_fetch_gtfs.py     # 数据获取测试（7个下载混乱测试）
├── .pre-commit-config.yaml    # 预提交钩子配置
├── pyproject.toml             # 现代Python配置（因为setup.py已经是2020年的东西了）
└── README.md                  # 这篇杰作

开发与测试

代码质量与CI/CD

本项目使用现代Python工具来保持代码的整洁和可维护性：

• Ruff：快速的代码检查和格式化工具（因为生命太短暂，不能用慢工具）
• MyPy：类型检查（因为猜测类型是业余人士的做法）
• Pytest：测试框架，带有覆盖率报告

发布流程

本项目使用自动版本控制和发布：

• 语义化版本控制：版本号根据提交消息使用Conventional Commits自动确定
• 自动打标签：当你推送到main分支时，semantic-release会自动创建版本标签
• PyPI发布：带标签的版本会通过GitHub Actions自动构建并发布到PyPI
• 可信发布：使用OIDC认证与PyPI交互（无需API令牌！）

发布版本

只需使用常规提交格式提交代码并推送到main分支：

# 修复bug（补丁版本升级：1.0.0 → 1.0.1）
git commit -m "fix: correct station name lookup bug"

# 添加新功能（次要版本升级：1.0.0 → 1.1.0）
git commit -m "feat: add support for weekend schedules"

# 重大变更（主要版本升级：1.0.0 → 2.0.0）
git commit -m "feat!: redesign API structure"
# 或者
git commit -m "feat: major API changes

BREAKING CHANGE: This changes the function signatures"

semantic-release工作流将：

1. 分析你的提交消息
2. 确定适当的版本升级
3. 创建一个git标签（例如，v1.2.3）
4. 生成变更日志
5. 触发发布工作流以发布到PyPI

本地测试

在推送之前，在本地测试构建过程：

# 在本地构建包
uv run python -m build --sdist --wheel

# 验证包
uv run twine check dist/*

# 测试上传到Test PyPI（可选）
uv run twine upload --repository testpypi dist/*

GitHub Actions CI

每次PR和推送到main分支都会触发自动检查：

• ✅ 代码检查：Ruff检查代码质量问题
• ✅ 格式化：确保代码风格一致
• ✅ 类型检查：MyPy验证类型注解
• ✅ 测试：完整的测试套件，带有覆盖率报告
• ✅ 覆盖率：在CI日志中显示测试覆盖率报告

如果任何检查失败，CI将礼貌地拒绝你的PR，因为标准很重要。

MCP集成

这个服务器实现了Model Context Protocol (MCP)，这意味着它可以与AI助手和其他MCP客户端无缝协作。配置完成后：

• Claude Desktop：在对话中直接向Claude询问火车时刻表
• 其他MCP客户端：任何兼容MCP的工具都可以访问加州火车数据
• 实时集成：你的AI可以查询时刻表、推荐路线并帮助规划行程
• 自然语言：无需记住站点名称或命令语法

服务器暴露了两个主要工具：

• next_trains - 获取站点之间的即将出发的列车信息
• list_stations - 浏览所有可用的加州火车站点

所以现在你的AI助手可以像真人一样让你对火车时刻表感到失望了！未来真的来了。

📄 许可证

本项目使用官方的加州火车GTFS数据。如果出了问题，怪他们，别怪我们。我们只是传话的。

在旧金山湾区，用❤️和大量咖啡因构建，这里的公共交通既是必需品，也是永恒痛苦的来源。