Italian Bus and Rail Search MCP Server

イタリアのバス検索

HTTP および Model Context Protocol インターフェースを通じて、複数のイタリアの長距離バス事業者を検索する、非公式の読み取り専用 TypeScript サービスです。

このプロジェクトでは、事業者ごとに異なる駅カタログ、リクエスト形式、運賃体系、複数区間の応答を、共通のアプリケーションコアの背後に隠しています。ログイン、予約、座席選択、決済の操作は一切行いません。

重要

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

特長

• さまざまな予約プラットフォームの場所と旅程に対応する、単一の応答モデル。
• 4 社の事業者に対応するライブアダプター。
• ある事業者で障害が発生しても、別の事業者から成功した結果が得られた場合は部分的な結果を返します。
• 構造化された読み取り専用ツールを備えた、ローカルの stdio MCP サーバー。
• 事業者のサイトで手動検索を続けるための公式リンク。
• 上流の応答を漏らさず、事業者ごとに分類された構造化エラー。
• 上流へのリクエストのタイムアウトは 5 秒。
• 場所のキャッシュは 1 時間、旅程のキャッシュは 60 秒。
• クライアントごとのインメモリレート制限は、1 分あたり 60 リクエスト。
• 合成フィクスチャを使ったオフラインテスト。テストスイートが事業者のサイトに接続することはありません。
• 実行時の依存関係は最小限で、公式 MCP SDK と Zod のみです。

対応事業者

Provider ID	事業者	インテグレーション	場所	旅程
itabus	Itabus	Demandware エンドポイント	ライブ	ライブ
salemi	Autoservizi Salemi	Albatross テナント	ライブ	ライブ
federico	Autolinee Federico	Albatross テナント	ライブ	ライブ
marinobus	MarinoBus	Albatross テナント	ライブ	ライブ

各事業者の動作とインテグレーションの根拠は、事業者の調査に記録されています。

要件

• Node.js 22.18 以降
• npm

クイックスタート

git clone https://github.com/Alexxanddr/italian-bus-search.git
cd italian-bus-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/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	/locations	事業者の場所検索
GET	/journeys	正規化された片道旅程の検索

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

パラメーター、応答、ステータス、エラーに関する完全な仕様は、HTTP インターフェースをご覧ください。

MCP サーバー

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

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

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

npm run build
npm run mcp:built

list_providers、search_locations、search_journeys を公開します。ホストモデルは、「11 月 15 日にローマからミラノへ行くバスを探して」という依頼を場所と旅程のツール呼び出しに変換し、手動購入用の公式リンクとともに正規化された選択肢を表示できます。

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

ツールの仕様、制限、エラー、開発用コマンドについては、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 インターフェース — エンドポイントとエラーの正式な契約です。
• MCP インターフェース — ツール、結果、制限、stdio の正式な契約です。
• アーキテクチャ — モジュール、接続部分、フロー、設計上の決定事項です。
• プロバイダーの追加 — 調査、実装、検証のチェックリストです。
• 運用 — 設定、デプロイ時の制約、障害への対処方法です。
• プロバイダーの調査 — 一次情報による根拠と既知の制限事項です。
• 用語集 — プロジェクトで使用する標準用語です。
• コントリビューション — ローカルでのワークフローとプルリクエストの要件です。
• セキュリティポリシー — 脆弱性を非公開で報告する方法とサポート対象のバージョンです。
• エージェント向けの指示 — コーディングエージェント向けの簡潔なルーティング指示です。

対象範囲と制限事項

• 検索は片道のみです。
• 空席状況はプロバイダーが報告する情報であり、座席や価格を保証するものではありません。
• 価格やスケジュールは、検索から購入までの間に変更される場合があります。
• キャッシュとレート制限はプロセスの再起動時にリセットされ、レプリカ間で共有されません。
• 上流のインターフェースは非公式であり、予告なく変更される場合があります。
• どちらのインターフェースも、アカウント、予約、支払い、CAPTCHA の処理は意図的に対象外としています。

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

コントリビューションとセキュリティ

コントリビューションを歓迎します。まずはCONTRIBUTING.mdをご確認ください。脆弱性は公開イシューではなく、SECURITY.mdに従って非公開で報告してください。

ライセンス

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