🚂 Caltrain MCP服务器（因为你喜欢等火车）
 
一个模型上下文协议（MCP）服务器，承诺告诉你 _精确地_ 下一班Caltrain何时到达。..然后无论如何都要迟到10分钟。使用真实的GTFS数据，所以至少失望是官方的！
功能（或：“我们为什么建造这个东西”）
- 🚆 “实时”列车时刻表 -获取任意两个车站之间的下一班发车时间（实际到达时间可能存在+/-无穷大的差异）
- 📍 车站查询 -因为显然31个车站太多了，记不住🤷♀️
- 🕐 特定时间查询 -以外科手术般的精准度规划你的通勤，然后看着一切分崩离析
- ✨ 智能搜索 -键入“sf”而不是全名，因为我们在这里都很懒
- 📊 基于GTFS -我们使用与Caltrain相同的数据，所以当事情出错时，我们可以一起责怪他们
设置（有趣的部分🙄)
- 安装依赖项 （又名“更多要打破的东西”）：
# Install uv if you haven't already (because pip is apparently too mainstream now)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies using uv (fingers crossed it actually works)
uv sync- 获取甜蜜的GTFS数据:
服务器需要Caltrain GTFS数据 src/caltrain_mcp/data/caltrain-ca-us/ 目录。因为显然我们不能随便问火车在哪里。
uv run python scripts/fetch_gtfs.py这个神奇的脚本下载的文件包含：
- stops.txt -所有的火车都假装停了下来 - trips.txt -穿越时空的理论之旅 - stop_times.txt -当火车 _假定的_ 到达（剧透：他们没有） - calendar.txt -工作日与周末时间表（因为火车也需要工作与生活的平衡）
用法（祝你好运！）
作为MCP服务器（真正的交易）
此服务器旨在与Claude Desktop等MCP客户端一起使用，而不是由人类直接运行（因为这太容易了）。以下是如何实际使用它：
使用克劳德桌面
将此添加到您的Claude Desktop MCP配置文件中：
{
"mcpServers": {
"caltrain": {
"command": "uvx",
"args": ["caltrain-mcp"]
}
}
}这将自动从PyPI安装并运行最新版本。
然后重新启动Claude Desktop，您将可以在对话中直接访问Caltrain时间表！
与其他MCP客户端
任何兼容MCP的客户端都可以通过以下方式启动此服务器：
uvx caltrain-mcp服务器使用MCP协议通过stdin/stdout进行通信。直接运行时，它不会做任何令人兴奋的事情——它只是坐在那里等待正确的MCP消息。
测试服务器（用于开发）
你可以通过直接导入来测试这个东西是否真的有效：
from caltrain_mcp.server import next_trains, list_stations
# Test next trains functionality (prepare for disappointment)
result = await next_trains('San Jose Diridon', 'San Francisco')
print(result) # Spoiler: there are no trains
# Test stations list (all 31 of them, because apparently that's manageable)
stations = await list_stations()
print(stations)可用工具（您的新好友）
next_trains(origin, destination, when_iso=None)
礼貌地问下一班火车什么时候来。服务器将查询其水晶球（GTFS数据），并为您提供以下时间 _技术上_ 准确。
参数：
origin（str）：你现在在哪里（可能后悔你的人生选择）destination（str）：你想去的地方（可能除了这里以外的任何地方）when_iso（str，可选）：当你想旅行时（就像时间在公共交通中有任何意义一样）
示例：
# Next trains from current time (aka "right now would be nice")
next_trains('San Jose Diridon', 'San Francisco')
# Trains at a specific time (for the optimists who think schedules matter)
next_trains('Palo Alto', 'sf', '2025-05-23T06:00:00')
# Using abbreviations (because typing is hard)
next_trains('diridon', 'sf')list_stations()
列出所有31个加州火车站，因为记住它们显然太难了。
退货： 一个格式化的列表，让你意识到这列火车应该去多少地方。
车站名称识别（我们不是读心术者，但我们会尝试）
服务器支持多种方式来避免输入站名：
- 全名“San Jose Diridon车站”（为完美主义者而设）
- 短名称：“旧金山”（对于不那么完美主义的人）
- 缩写：“sf”→ “旧金山”（指真正懒惰的人）
- 部分匹配：“diridon”匹配“San Jose diridon Station”（当你不受打扰时）
可用站点（全部31个精彩站点）
服务器覆盖了Caltrain的每一个车站，因为我们是完美主义者：
旧金山至圣何塞 （主要活动）：
- 旧金山，22街，Bayshore，南旧金山，San Bruno，Millbrae，百老汇，Burlingame，San Mateo，Hayward Park，Hillsdale，Belmont，San Carlos，Redwood City，Menlo Park，Palo Alto，Stanford，California Avenue，San Antonio，Mountain View，Sunnyvale，Lawrence，Santa Clara，College Park，San Jose Diridon
圣何塞至吉尔罗伊 （“这为什么存在？”扩展）：
- 塔米恩、国会大厦、布鲁森山、摩根山、圣马丁、吉尔罗伊
样本输出（准备惊喜）
🚆 Next Caltrain departures from San Jose Diridon Station to San Francisco Caltrain Station on Thursday, May 22, 2025:
• Train 153: 17:58:00 → 19:16:00 (to San Francisco)
• Train 527: 18:22:00 → 19:22:00 (to San Francisco)
• Train 155: 18:28:00 → 19:46:00 (to San Francisco)
• Train 429: 18:43:00 → 19:53:00 (to San Francisco)
• Train 157: 18:58:00 → 20:16:00 (to San Francisco)_实际到达时间可能会有所不同。副作用可能包括存在恐惧和对远程工作的深刻欣赏。_
技术细节（供书呆子使用）
- GTFS处理：我们自动处理车站和站台之间的关系（因为显然火车很复杂）
- 服务日历：尊重工作日/周末的时间表（火车也需要美容休息）
- 数据类型：处理GTFS文件中混合整数/字符串格式的混乱
- 时间解析：为那些神秘的深夜服务支持24小时以上的格式
- 错误处理：当您键入“纳尼亚”作为电台名称时，会优雅地失败
项目结构（有组织的混乱）
caltrain-mcp/
├── .github/workflows/ # GitHub Actions (the CI/CD overlords)
│ ├── ci.yml # Main CI pipeline (linting, testing, the works)
│ └── update-gtfs.yml # Automated GTFS data updates
├── src/caltrain_mcp/ # Main package (because modern Python demands structure)
│ ├── data/caltrain-ca-us/ # GTFS data storage (where CSV files go to retire)
│ ├── __init__.py # Package initialization (the ceremony of Python)
│ ├── __main__.py # Entry point for python -m caltrain_mcp
│ ├── server.py # MCP server implementation (where the magic happens)
│ └── gtfs.py # GTFS data processing (aka "CSV wrestling")
├── scripts/ # Utility scripts (the supporting cast)
│ ├── __init__.py # Makes scripts a proper Python package
│ ├── fetch_gtfs.py # Downloads the latest disappointment data
│ └── lint.py # Run all CI checks locally (before embarrassment)
├── tests/ # Test suite (because trust but verify)
│ ├── conftest.py # Shared test fixtures (the common ground)
│ ├── test_gtfs.py # GTFS functionality tests (8 tests of data wrangling)
│ ├── test_server.py # Server functionality tests (4 tests of MCP protocol)
│ └── test_fetch_gtfs.py # Data fetching tests (7 tests of download chaos)
├── .pre-commit-config.yaml # Pre-commit hooks configuration
├── pyproject.toml # Modern Python config (because setup.py is so 2020)
└── README.md # This literary masterpiece开发和测试（当事情不可避免地破裂时）
代码质量和CI/CD
这个项目使用现代Python工具来保持代码的干净和可维护性：
- 拉夫：闪电般快速的抓取和格式化（因为对于慢速工具来说，生命太短暂了）
- MyPy：类型检查（因为猜测类型是为业余爱好者准备的）
- Pytest：具有覆盖率报告的测试框架
发布流程（自动化精彩）
此项目使用自动版本控制和发布：
- 语义版本控制：版本号由提交消息自动确定，使用 常规承诺
- 自动标记：当你推
main，语义发布会自动创建版本标签 - PyPI出版：标记的版本会自动构建并通过GitHub Actions发布到PyPI
- 可信发布：使用带PyPI的OIDC身份验证（不需要API令牌！）
发布
只需使用常规提交格式提交并推送到main：
# For bug fixes (patch version bump: 1.0.0 → 1.0.1)
git commit -m "fix: correct station name lookup bug"
# For new features (minor version bump: 1.0.0 → 1.1.0)
git commit -m "feat: add support for weekend schedules"
# For breaking changes (major version bump: 1.0.0 → 2.0.0)
git commit -m "feat!: redesign API structure"
# or
git commit -m "feat: major API changes
BREAKING CHANGE: This changes the function signatures"语义发布工作流将：
- 分析您的提交消息
- 确定合适的版本差异
- 创建一个git标签（例如。，
v1.2.3) - 生成变更日志
- 触发发布工作流以发布到PyPI
局部测试
在推送之前，在本地测试构建过程：
# Build packages locally
uv run python -m build --sdist --wheel
# Validate packages
uv run twine check dist/*
# Test upload to Test PyPI (optional)
uv run twine upload --repository testpypi dist/*GitHub操作CI
每个PR和主推送都会触发自动检查：
- ✅ 代码检查：Ruff检查代码质量问题
- ✅ 格式化：确保一致的代码风格
- ✅ 类型检查：MyPy验证类型注释
- ✅ 测试：具有覆盖率报告的完整测试套件
- ✅ 覆盖：CI日志中的测试覆盖率报告
如果任何检查失败，CI将礼貌地拒绝您的PR，因为标准很重要。
MCP集成（针对AI霸主）
该服务器实现了模型上下文协议（MCP），这意味着它旨在与AI助手和其他MCP客户端无缝协作。配置后：
- 克劳德桌面：在谈话中直接问克劳德火车时刻表
- 其他MCP客户端：任何与MCP兼容的工具都可以访问Caltrain数据
- 实时集成：你的人工智能可以检查时间表，建议路线，并帮助计划旅行
- 自然语言：无需记住站名或命令语法
服务器公开了两个主要工具：
next_trains-获取车站之间即将出发的航班list_stations-浏览所有可用的Caltrain车站
因此，你的人工智能助手现在可以像真人一样让你对火车时刻表感到失望！未来真的在这里。
许可证（法律事务）
该项目使用Caltrain GTFS官方数据。如果出了问题，就怪他们，而不是我们。我们只是信使。
______________________________________________________________________
_内置于❤️ 湾区的咖啡因含量令人担忧，公共交通既是必需品，也是永恒痛苦的根源。_