加州火车MCP服务器是一个基于Model Context Protocol (MCP)的服务器,它承诺能精准地告诉你下一班加州火车的到达时间,但实际上可能还是会晚点10分钟。该服务器使用真实的GTFS数据,所以这份失望也是“官方认证”的!
# 如果你还没有安装uv(因为现在pip好像太主流了)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 使用uv安装依赖(祈祷它真的能成功)
uv sync
服务器需要将加州火车的GTFS数据存放在src/caltrain_mcp/data/caltrain-ca-us/
目录下。因为显然我们不能直接问火车它们在哪。
uv run python scripts/fetch_gtfs.py
这个神奇的脚本会下载包含以下内容的文件:
stops.txt
- 火车假装会停靠的所有站点trips.txt
- 穿越时空的理论旅程stop_times.txt
- 火车“应该”到达的时间(剧透:它们并不会按时到达)calendar.txt
- 工作日和周末的时刻表(因为火车也需要工作与生活的平衡)# 如果你还没有安装uv(因为现在pip好像太主流了)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 使用uv安装依赖(祈祷它真的能成功)
uv sync
服务器需要将加州火车的GTFS数据存放在src/caltrain_mcp/data/caltrain-ca-us/
目录下。因为显然我们不能直接问火车它们在哪。
uv run python scripts/fetch_gtfs.py
这个服务器是为与像Claude Desktop这样的MCP客户端配合使用而设计的,而不是供人类直接运行(因为那样就太简单了)。以下是具体的使用方法:
在你的Claude Desktop MCP配置文件中添加以下内容:
{
"mcpServers": {
"caltrain": {
"command": "uvx",
"args": ["caltrain-mcp"]
}
}
}
这将自动从PyPI安装并运行最新版本。
然后重启Claude Desktop,你就可以在对话中直接查询加州火车时刻表了!
任何兼容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个加州火车站点的列表,因为显然记住它们太难了。 返回值: 一个格式化的列表,让你意识到这列火车到底要去多少个地方。
服务器支持多种偷懒的站点名称输入方式:
服务器覆盖了每一个加州火车站点,因为我们是完美主义者: 旧金山到圣何塞(主要路线):
圣何塞到吉尔罗伊(“这玩意为什么存在”的支线):
🚆 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(开往旧金山)
实际到达时间可能会有所不同。副作用可能包括存在主义的恐惧和对远程工作的深切感激。
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 # 这篇杰作
本项目使用现代Python工具来保持代码的整洁和可维护性:
本项目使用自动版本控制和发布:
main
分支时,semantic-release会自动创建版本标签只需使用常规提交格式提交代码并推送到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工作流将:
v1.2.3
)在推送之前,在本地测试构建过程:
# 在本地构建包
uv run python -m build --sdist --wheel
# 验证包
uv run twine check dist/*
# 测试上传到Test PyPI(可选)
uv run twine upload --repository testpypi dist/*
每次PR和推送到main
分支都会触发自动检查:
如果任何检查失败,CI将礼貌地拒绝你的PR,因为标准很重要。
这个服务器实现了Model Context Protocol (MCP),这意味着它可以与AI助手和其他MCP客户端无缝协作。配置完成后:
服务器暴露了两个主要工具:
next_trains
- 获取站点之间的即将出发的列车信息list_stations
- 浏览所有可用的加州火车站点所以现在你的AI助手可以像真人一样让你对火车时刻表感到失望了!未来真的来了。
本项目使用官方的加州火车GTFS数据。如果出了问题,怪他们,别怪我们。我们只是传话的。
在旧金山湾区,用❤️和大量咖啡因构建,这里的公共交通既是必需品,也是永恒痛苦的来源。