Italian Travel Search MCP Server

イタリア旅行検索

HTTP および Model Context Protocol インターフェースを通じて、イタリア国内の長距離バスと列車をリアルタイム検索する、非公式の読み取り専用 TypeScript サービスです。

このプロジェクトでは、各プロバイダー固有の駅カタログ、リクエスト形式、運賃体系、複数区間の応答を、共通のアプリケーションコアの背後に隠しています。Italo の料金検索では、匿名の技術セッションと一時的な経路計画リソースを初期化します。顧客ログイン、運賃の選択、座席予約、支払いは対象外です。

重要

このプロジェクトは、Itabus、Autoservizi Salemi、Autolinee Federico、MarinoBus、FlixBus と提携しておらず、承認も受けていません。プロバイダー名および商標は各権利者に帰属します。ライブアダプターを有効にする前に、ご利用がプロバイダーの規約、適用法、および必要な許可に準拠していることをご確認ください。このリポジトリは、データの抽出または再配布の権利を付与するものではありません。

機能

• 異なる予約プラットフォーム間で、地点と旅程に共通のレスポンスモデルを使用します。
• 5 社のバス事業者と 2 社の鉄道事業者に対応するライブアダプター。
• あるプロバイダーが失敗しても、別のプロバイダーが成功した場合は部分的な結果を返します。
• ローカル stdio、または /mcp でのステートレス Streamable HTTP を介した MCP。後方互換性のあるバスツールと、独立した鉄道ツールを備えています。
• Trenitalia と Italo の駅および旅程を、各社のライブ予約 API から直接検索します。
• プロバイダーのサイトで手動検索を続けるための公式リンク。
• 指定された出発日を反映した検索を行います。都市検索では、利用可能な場合は実際の停留所名と住所を含め、Itabus のすべての停留所を保持します。
• 鉄道の警告では、提示運賃に含まれない市内乗り換えを明示します。
• 上流レスポンスをそのまま漏らさず、プロバイダーごとに整理されたエラーを返します。
• 上流リクエストのタイムアウトを設定し、非同期の料金確認を制限します。
• 地点のキャッシュは 1 時間、旅程のキャッシュは 60 秒です。
• オプトイン方式の不変な旅程ページネーション。HTTP と MCP で共有する、メモリ内スナップショットを 5 分間保持します。
• クライアントごとに、メモリ内で 1 分あたり 60 リクエストのレート制限を行います。
• 合成フィクスチャを使用したオフラインテスト。テストスイートからプロバイダーのサイトにアクセスすることはありません。
• 実行時の依存関係は最小限で、公式 MCP SDK と Zod のみです。

対応プロバイダー

プロバイダー ID	事業者	統合方式	地点	旅程
itabus	Itabus	Demandware エンドポイント	ライブ	ライブ
salemi	Autoservizi Salemi	Albatross テナント	ライブ	ライブ
federico	Autolinee Federico	Albatross テナント	ライブ	ライブ
marinobus	MarinoBus	Albatross テナント	ライブ	ライブ
flixbus	FlixBus	グローバル FlixBus 検索 API	ライブ	ライブ

プロバイダーの公開動作と制限については、以下のバスおよび鉄道 API ガイドに記載されています。

鉄道の駅、旅程、料金、空席状況は、Trenitalia と Italo の予約 API から直接取得します。時刻表のダウンロード、データセット、ストレージ容量、初期化コマンドは必要ありません。一方の事業者が失敗した場合、そのエラーはもう一方の事業者の結果と併せて報告されます。ViaggiaTreno と Italo のライブボード／単独ステータスは独立しており、Italo の料金確認セッションは可能な限り後処理で終了します。

要件

• Node.js 22.18 以降
• npm

クイックスタート

git clone https://github.com/Alexxanddr/italian-travel-search.git
cd italian-travel-search
npm install
cp .env.example .env
npm start

デフォルトでは、サーバーは http://127.0.0.1:3000 で待ち受けます。

curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/providers
curl http://127.0.0.1:3000/train-providers
curl 'http://127.0.0.1:3000/locations?query=Roma&provider=marinobus'

旅程を検索する場合は、実際の未来の日付を使用してください。

curl 'http://127.0.0.1:3000/journeys?origin=Roma&destination=Milano&date=YYYY-MM-DD&adults=1&children=0&provider=marinobus'

YYYY-MM-DD はプレースホルダーです。コマンドを実行する前に、実際の日付に置き換えてください。

HTTP インターフェース

メソッド	パス	用途
GET	/health	プロセスの稼働確認
GET	/providers	アダプターのステータスと運用上の理由
GET	/train-providers	鉄道事業者と、設定済みの運行スケジュール／料金／リアルタイム機能
GET	/locations	プロバイダーの場所検索
GET	/journeys	正規化された片道の旅程検索
GET	/train-locations	Trenitalia／Italo の駅検索
GET	/train-journeys	リアルタイムの鉄道旅程、空席状況、null 許容の料金
GET	/train-status	有効な場合の単独リアルタイム運行状況
GET	/station-board	有効な場合のリアルタイム到着／出発情報
POST	/mcp	ステートレス MCP Streamable HTTP エンドポイント

/locations と /journeys では、任意の provider パラメーターを指定できます。指定しない場合は、すべてのプロバイダーに個別に問い合わせ、成功したデータをプロバイダーごとのエラーと併せて保持します。

完全な仕様はバス APIと鉄道 APIに分かれており、共通の動作はHTTP APIにまとめられています。

MCP サーバー

最も簡単な MCP 設定では、npx を使って公開済みのパッケージを直接実行します。

{
  "mcpServers": {
    "italian-travel-search": {
      "command": "npx",
      "args": ["-y", "italian-travel-search@latest"]
    }
  }
}

または、ローカルの stdio サーバーをビルドして起動します。

npm run build
npm run mcp:built

既存の list_providers、search_locations、search_journeys バスツールとの互換性は維持されています。場所検索と旅程検索では、任意の offset／limit を指定できます。すべてのページを取得するには、truncated が false になるまで offset を limit ずつ増やします。鉄道では、list_train_providers、search_train_locations、search_train_journeys、get_train_status、get_station_board が追加されています。Trenitalia と Italo の料金およびリアルタイムアダプターは有効です。Italo のリアルタイムツールでは、日付が未検証であるという意味が維持されます。

旅程検索ですべての結果を取得するには、snapshot: true で開始し、 返された searchId、offset、limit だけを使って続行します。これにより、 ページ間で料金、エラー、順序、合計が同一に保たれます。ID の有効期限が切れた場合は、 新たに検索する必要があります。同じオプトイン方式は HTTP でも利用できます。 安定したページネーションを参照してください。

{
  "mcpServers": {
    "italian-travel-search": {
      "command": "node",
      "args": ["/absolute/path/to/italian-travel-search/dist/mcp/stdio.js"]
    }
  }
}

コンテナーまたはリモート MCPHub 環境にデプロイするには、HTTP プロセスを起動し、クライアントの接続先に http://italian-travel-search:3000/mcp を指定します。コンテナーイメージは ghcr.io/alexxanddr/italian-travel-search:latest です。データセットの初期化や永続ボリュームは必要ありません。

正式なツール仕様、制限、エラー、開発用コマンドについては、MCP インターフェースを参照してください。

アーキテクチャ

アプリケーションは、次の 4 つのレイヤーで構成されています。

1. HTTP アダプターと MCP アダプターが、それぞれのトランスポート固有のリクエストを検証します。
2. 共通のバリデーションと SearchService が、検索と部分的な結果を調整します。
3. 各プロバイダーアダプターが、リモートプロトコルをドメイン型に変換します。
4. ドメインモジュールが、正規化されたデータとエラー仕様を管理します。

プロバイダーアダプターは共通のインターフェースを実装するため、呼び出し元は結果が Itabus Demandware と Albatross テナントのどちらに由来するかを意識する必要はありません。モジュール、接合部、データフロー、キャッシュ、テスト戦略については、アーキテクチャを参照してください。

開発

npm run dev
npm run mcp
npm run check

npm run check は、オフラインテストスイート全体、TypeScript の型チェック、設定済みの lint チェックを実行します。事業者を追加する場合は、プロバイダーの追加に従ってください。HTML だけから新しい連携を推測したり、フィクスチャに認証情報をコピーしたりしないでください。

デプロイ

デフォルトのサーバーは意図的にループバックにバインドされ、レート制限とキャッシュの状態をプロセスメモリ内に保持します。リバースプロキシの背後に配置する場合や複数のレプリカを実行する場合は、事前に運用をお読みください。

プロジェクトドキュメント

• HTTP API — 共通の動作とエラー契約です。
• Bus API — バスプロバイダー、場所、移動経路、および使用例です。
• Train API — 鉄道の時刻表、リアルタイムの価格／状況、データの出所、および使用例です。
• MCP interface — 権威あるツール、結果、制限、および通信方式の契約です。
• Architecture — モジュール、境界、フロー、および設計上の決定事項です。
• Adding a provider — 調査、実装、および検証のチェックリストです。
• Operations — 設定、デプロイ上の制約、および障害対応です。
• Glossary — プロジェクト内で一貫して使用する用語です。
• Contributing — ローカルでのワークフローとプルリクエストに関するルールです。
• Security policy — 脆弱性の非公開報告とサポート対象バージョンについてです。
• Agent instructions — コーディングエージェント向けの簡潔なルーティング手順です。

対象範囲と制限

• 検索は片道のみです。
• 空席状況はプロバイダーが報告する情報であり、座席や価格を保証するものではありません。
• 価格や時刻表は検索から購入までの間に変更されることがあります。鉄道の検索結果には、リアルタイムの観測情報とデータソースのメタデータが含まれます。従来のフィールド名 timetableSource は互換性のために維持されています。
• キャッシュとレート制限はプロセスの再起動時にリセットされ、レプリカ間で共有されません。
• 上流インターフェースは非公式であり、予告なく変更されることがあります。
• どちらのインターフェースも、アカウント、予約、支払い、および CAPTCHA への対応は意図的に対象外としています。

購入は、bookingUrl でリンクされているプロバイダーの公式サイトで必ず完了し、確認してください。

貢献とセキュリティ

貢献を歓迎します。まずは CONTRIBUTING.md をご確認ください。脆弱性は公開 issue ではなく、SECURITY.md の手順に従って非公開で報告してください。

ライセンス

ソースコードは MIT License の下で公開されています。このライセンスの対象は、このリポジトリのコードであり、サードパーティのデータ、プロバイダーの商標、または上流システムへのアクセス権は対象外です。