Caltrain MCP

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

本项目是一个模型上下文协议（MCP）服务器，它承诺能准确告诉你下一班加州火车的到达时间……但实际上还是会晚点10分钟。它使用真实的GTFS数据，所以至少这份失望是“官方认证”的！

🚀 快速开始

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

与Claude Desktop配合使用

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

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

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

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

与其他MCP客户端配合使用

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

uvx caltrain-mcp

服务器通过标准输入/输出使用MCP协议进行通信。直接运行时它不会有什么特别的表现，只是静静地等待合适的MCP消息。

✨ 主要特性

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

📦 安装指南

1. 安装依赖项（也就是“更多可能出错的东西”）：

   # 如果你还没有安装uv（因为现在pip显然太主流了）
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # 使用uv安装依赖项（祈祷它真的能正常工作）
   uv sync
   

2. 获取GTFS数据： 服务器期望在 src/caltrain_mcp/data/caltrain-ca-us/ 目录中找到加州火车的GTFS数据。显然我们不能直接问火车它们在哪里。

   uv run python scripts/fetch_gtfs.py
   

   这个神奇的脚本会下载包含以下内容的文件：
   • stops.txt - 火车假装停靠的所有站点
   • trips.txt - 理论上的时空之旅
   • stop_times.txt - 火车“应该”到达的时间（剧透：它们不会按时到达）
   • calendar.txt - 工作日和周末的时刻表（因为火车也需要工作与生活的平衡）

💻 使用示例

基础用法

测试服务器功能

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

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)

高级用法

作为MCP服务器使用

本服务器设计为与MCP客户端配合使用，以下是具体配置方法：

与Claude Desktop配合

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

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

与其他MCP客户端配合

使用以下命令启动服务器：

uvx caltrain-mcp

📚 详细文档

可用工具

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集成

本服务器实现了模型上下文协议（MCP），这意味着它旨在与AI助手和其他MCP客户端无缝协作。配置完成后：

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

服务器提供了两个主要工具：

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

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

📄 许可证

本项目使用官方加州火车的GTFS数据。如果出了问题，请责怪他们，而不是我们。我们只是信使。

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