🚀 加州火車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 - 我們使用與加州火車相同的數據,所以出問題時我們可以一起責怪他們
📦 安裝指南
- 安裝依賴項(也就是“更多可能出錯的東西”):
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
- 獲取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)
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分支:
git commit -m "fix: correct station name lookup bug"
git commit -m "feat: add support for weekend schedules"
git commit -m "feat!: redesign API structure"
git commit -m "feat: major API changes
BREAKING CHANGE: This changes the function signatures"
semantic-release工作流將:
- 分析你的提交消息
- 確定適當的版本升級
- 創建一個git標籤(例如
v1.2.3
)
- 生成變更日誌
- 觸發發佈工作流以發佈到PyPI
本地測試
在推送之前在本地測試構建過程:
uv run python -m build --sdist --wheel
uv run twine check dist/*
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數據。如果出了問題,請責怪他們,而不是我們。我們只是信使。
在舊金山灣區,用 ❤️ 和大量咖啡因構建,在這裡公共交通既是必需品,也是無盡痛苦的來源。