Caltrain MCP

🚂 Caltrain MCP Server (電車の待ち時間が大好きなあなたに)

このModel Context Protocol (MCP) サーバーは、次のカルトレインがいつ到着するかを正確に教えてくれると約束しますが、結局10分遅れることがあります。実際のGTFSデータを使用しているので、少なくとも失望は公式なものです！

🚀 クイックスタート

このサーバーは、Claude DesktopなどのMCPクライアントと併用することを想定しています。以下に、具体的なセットアップ方法と使用方法を説明します。

✨ 主な機能

• 🚆 「リアルタイム」の列車時刻表 - 任意の2駅間の次の出発時刻を取得できます（実際の到着時刻は±無限に変動する可能性があります）
• 📍 駅検索 - 31駅もの駅名を暗記するのは難しいので、検索機能を用意しています🤷‍♀️
• 🕐 特定時間のクエリ - 通勤を細かく計画できますが、実際にはすべてがうまくいかないこともあります
• ✨ スマート検索 - 駅名の一部を入力するだけで検索できます。皆さんが怠け者であることを理解しています
• 📊 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 - 平日と週末の時刻表 (電車も仕事と生活のバランスを取る必要があります)

💻 使用例

基本的な使用法

MCPサーバーとしての使用 (本格的な使い方)

このサーバーは、Claude DesktopなどのMCPクライアントと併用することを想定しており、人間が直接実行することは想定されていません（それは簡単すぎるからです）。以下に、実際の使用方法を説明します。

Claude Desktopでの使用

Claude DesktopのMCP設定ファイルに以下を追加します:

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

これにより、PyPIから最新バージョンが自動的にインストールされ、実行されます。 その後、Claude Desktopを再起動すると、会話の中で直接カルトレインの時刻表にアクセスできます！

その他のMCPクライアントでの使用

任意のMCP互換クライアントは、以下のコマンドでサーバーを起動することができます:

uvx caltrain-mcp

サーバーは、MCPプロトコルを使用してstdin/stdoutを介して通信します。直接実行すると何も起こりません - 適切な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駅すべてのカルトレインの駅名のリストを取得できます。駅名を暗記するのは難しいので、この機能を用意しました。

戻り値: このリストを見ると、この電車がどれだけ多くの場所を走っているかがわかります。

駅名の認識

サーバーは、駅名の入力を楽にするために、さまざまな方法をサポートしています:

• 完全な名称: "San Jose Diridon Station" (完璧主義者向け)
• 短い名称: "San Francisco" (少し妥協する人向け)
• 略称: "sf" → "San Francisco" (本当に怠け者向け)
• 部分一致: "diridon" は "San Jose Diridon Station" と一致します (面倒くさがり屋向け)

利用可能な駅 (31駅すべての素晴らしい停留所)

サーバーは、すべてのカルトレインの駅をカバーしています。私たちは完璧主義者です。

サンフランシスコからサンノゼまで (メインイベント):

• San Francisco, 22nd Street, Bayshore, South San Francisco, San Bruno, Millbrae, Broadway, 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

サンノゼからギルロイまで (「なぜこれが存在するのか」拡張区間):

• Tamien, Capitol, Blossom Hill, Morgan Hill, San Martin, Gilroy

サンプル出力 (驚かされる準備をしてください)

🚆 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         # サーバー機能のテスト (MCPプロトコルの4つのテスト)
│   └── 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に公開されます
• 信頼された公開: PyPIとのOIDC認証を使用しているので、APIトークンは必要ありません！

リリースの作成

Conventional Commits形式でコミットし、main ブランチにプッシュします:

# バグ修正の場合 (パッチバージョンの更新: 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/*

# テスト用のPyPIにアップロードしてテストします (オプション)
uv run twine upload --repository testpypi dist/*

GitHub Actions CI

すべてのPRと main ブランチへのプッシュは、自動的にチェックをトリガーします:

• ✅ リント: Ruffがコード品質の問題をチェックします
• ✅ フォーマット: コードスタイルの一貫性を保証します
• ✅ 型チェック: MyPyが型アノテーションを検証します
• ✅ テスト: カバレッジレポート付きの完全なテストスイート
• ✅ カバレッジ: CIログにテストカバレッジレポートが表示されます

CIは、いずれかのチェックが失敗した場合は、あなたのPRを丁寧に拒否します。基準は重要です。

🤖 MCP統合

このサーバーは、Model Context Protocol (MCP) を実装しているため、AIアシスタントや他のMCPクライアントとシームレスに連携するように設計されています。設定後は、以下のことが可能です:

• Claude Desktop: 会話の中で直接Claudeに列車時刻表を尋ねることができます
• その他のMCPクライアント: 任意のMCP互換ツールがカルトレインのデータにアクセスできます
• リアルタイム統合: あなたのAIが時刻表を確認し、経路を提案し、旅行を計画するのを支援できます
• 自然言語: 駅名やコマンド構文を覚える必要はありません

サーバーは、2つの主要なツールを公開しています:

• next_trains - 駅間の次の出発時刻を取得する
• list_stations - すべての利用可能なカルトレインの駅を閲覧する

これで、あなたのAIアシスタントが人間のように列車時刻表についてあなたを失望させることができます！未来は本当にやってきました。

📄 ライセンス

このプロジェクトは、公式のカルトレインのGTFSデータを使用しています。何かがうまくいかなかった場合は、私たちではなく彼らを責めてください。私たちはただの伝達者です。

このプロジェクトは、ベイエリアで❤️と大量のカフェインを使って作られました。ここでは、公共交通機関は必需品であり、永遠の苦しみの源でもあります。