🚂 Caltrain MCP Server (因为您喜欢等待火车)

这是一个模型上下文协议（MCP）服务器，承诺告诉您下一班Caltrain的确切到达时间……然后仍然会晚到10分钟。使用真实的GTFS数据，所以至少失望是官方的！

特性（或者说：“我们为什么建造这个东西”）

• 🚆 “实时”列车时刻表 - 获取任意两个车站之间的下一次发车时间（实际到达时间可能相差正负无穷）
• 📍 车站查找 - 因为显然31个车站太多记不住 🤷‍♀️
• 🕐 时间特定查询 - 以手术般的精确度规划您的通勤，然后看着它全部崩溃
• ✨ 智能搜索 - 输入“sf”而不是全名，因为我们在这里都很懒
• 📊 基于GTFS - 我们使用与Caltrain相同的资料，所以当事情出错时，我们可以一起责怪他们

安装（有趣的部分 🙄）

1. 安装依赖项（即“更多可以出错的东西”）：

   # 如果还没有安装uv（因为pip现在被认为太主流了）
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # 使用uv安装依赖项（希望它真的能工作）
   uv sync
   

2. 获取那甜美的GTFS数据： 服务器期望在src/caltrain_mcp/data/caltrain-ca-us/目录中找到Caltrain的GTFS数据。因为显然我们不能礼貌地问火车它们在哪里。

   uv run python scripts/fetch_gtfs.py
   

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

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

使用方法（祝你好运！）

作为MCP服务器（真正的用途）

此服务器设计用于与MCP客户端如Claude Desktop配合使用，而不是由人类直接运行（因为那样太简单了）。这是如何真正使用它的方法：

与Claude Desktop

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

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

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

然后重启Claude Desktop，您就可以直接在对话中访问Caltrain时刻表了！

与其他MCP客户端

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

uvx caltrain-mcp

服务器通过标准输入/输出使用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个Caltrain车站的列表，因为显然要求记住它们太多了。

返回值： 一个格式化的列表，让您意识到这趟火车据说要去多少地方。

车站名称识别（我们不是读心者，但我们尽力了）

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

• 全名："San Jose Diridon Station"（给完美主义者）
• 短名："San Francisco"（给稍微不那么完美主义者）
• 缩写："sf" → "San Francisco"（给真正懒的人）
• 部分匹配："diridon" 匹配 "San Jose Diridon Station"（当你懒得连打字都不想的时候）

可用车站（全部31个辉煌的站点）

服务器覆盖每一个Caltrain车站，因为我们是完美主义者：

从旧金山到圣何塞（主要事件）：

• 旧金山、22街、海湾岸、南旧金山、圣布兰卡、米尔布雷、百老汇、伯灵格姆、圣马特奥、海沃德公园、希尔兹代尔、贝尔蒙特、圣卡洛斯、红木城、门洛帕克、帕洛阿尔托、斯坦福、加利福尼亚大道、圣安东尼奥、山景城、桑尼维尔、劳伦斯、圣克拉拉、学院公园、圣何塞迪里东

从圣何塞到吉尔罗伊（“这存在有什么意义？”扩展）：

• 泰米恩、国会、花岗岩丘、摩根希尔、圣马丁、吉尔罗伊

示例输出（准备被惊艳）

🚆 下一班Caltrain从圣何塞迪里东站到旧金山Caltrain站，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：具有覆盖率报告的测试框架

发布过程（自动化神奇）

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

• 语义化版本控制：版本号根据提交信息自动确定，使用常规提交
• 自动标记：当您推送到main时，semantic-release会自动创建版本标签
• PyPI发布：标记的版本会自动构建并通过GitHub Actions发布到PyPI
• 可信发布：使用OIDC身份验证与PyPI（无需API令牌！）

发布

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

# 对于bug修复（小版本升级：1.0.0 → 1.0.1）
git commit -m "fix: 正确车站名称查找错误"

# 对于新特性（次版本升级：1.0.0 → 1.1.0）
git commit -m "feat: 添加周末时刻表支持"

# 对于重大变更（主版本升级：1.0.0 → 2.0.0）
git commit -m "feat!: 重新设计API结构"
# 或
git commit -m "feat: 重大API更改

BREAKING CHANGE: 这改变了函数签名"

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集成（给AI霸主）

此服务器实现了模型上下文协议（MCP），这意味着它可以无缝地与AI助手和其他MCP客户端配合使用。一旦配置好：

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

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

• next_trains - 获取车站之间的即将发车时间
• list_stations - 浏览所有可用的Caltrain车站

因此，您的AI助手现在可以像真人一样让您失望关于列车时刻表！未来真的来了。

许可（法律条款）

此项目使用官方的Caltrain GTFS数据。如果出现问题，请责怪他们，而不是我们。我们只是信使。

---

在湾区用爱和令人担忧的咖啡因量制作，那里公共交通既是必需品也是永恒的痛苦来源。