simscout

simscout

simscout は、旅行用 eSIM プランを掲載する esimoa のホスト型 MCP サーバーへの、小規模なローカルブリッジです。目的地と旅行日数、 必要なデータ量を指定すると、カタログから条件に合うプラン、 KRW 建ての価格、購入できる esimoa.com 上の各プランページへの リンクが返されます。

このブリッジは独自のカタログを持ちません。稼働中のエンドポイントから 取得したとおりの上流サーバーのツール一覧をローカルで提供し、各ツールの呼び出しを 上流に転送して、結果を変更せずに返します。取得した機能はすべて読み取り専用で、 検索、プランの詳細取得、候補の比較、目的地の一覧表示のみです。 チェックアウトや支払いのツールは含まれていません。

ツール

• search_esims — 目的地を指定してカタログを検索します。 すべてのフィルターは任意です。country（ISO コードまたは 任意の言語での名称。例：JP または Japan）、days（旅行日数）、 data_gb / max_data_gb、unlimited、 countries（複数の国を訪れる旅行。最大 8 か国）、data_type （daily または total）、local_number、network （local または roaming）、multi_country、min_price_krw / max_price_krw、provider、hotspot、five_g、 sort（recommended、price、data、price_per_gb または validity）、limit（1〜10、デフォルトは 5）、lang。 各結果には id とプランページの url が含まれます。
• get_esim — 1 つのプランの詳細を取得します。必須： id（search_esims の結果から指定）。任意：lang。
• compare_esims — 2〜5 件のプランを並べて比較します： 価格、データ量、有効期間、1 GB あたりの価格、カバレッジ、ネットワーク、 ホットスポット、現地の電話番号に加え、最安値、最大データ量、 最長の有効期間、1 GB あたりの最安値を誇るプランも表示します。必須： ids。任意：lang。
• list_countries — プランが販売されているすべての目的地を、 国ごとのプラン数と最低価格とともに表示します。任意： query（名称または ISO コードによる絞り込み）と lang。
• search — ChatGPT のディープリサーチで使われる検索／取得形式で フリーテキスト検索を行います。例：「Japan 7 days unlimited」。必須：query。fetch で使う ID を返します。 フィルターを指定できる場合は、search_esims を優先してください。
• fetch — search が返した ID を使って、1 つのプランをドキュメントとして 取得します。必須：id。search_esims で見つけたプランには、 代わりに get_esim を使用してください。

設定

• ESIMOA_MCP_URL（任意）— 上流エンドポイントを上書きします。 デフォルトは https://api.esimoa.com/mcp です。 （この上書き機能は、この再構築版独自の、再構築箇所であることを示す実装です。）
• ESIMOA_API_KEY（任意）— 設定すると、すべての上流リクエストに X-API-Key: <key> ヘッダーが付与されます （パートナーキーを使うと、購入リンクにパートナーのアフィリエイトコードが追加されます）。 設定されていない場合、キーのヘッダーは送信されず、上流は通常のリンクを返します。 Authorization ヘッダーは一切送信されません。 （この転送機能も、再構築版独自の、再構築箇所であることを示す実装です。 元の機能はキーなしで取得されました。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーミング可能な HTTP セッションを開きます。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name simscout）を送信し、続いて notifications/initialized 通知を送り、その後、呼び出し元の引数を変更せずに含めた tools/call リクエストを送信します。上流が initialize への応答で Mcp-Session-Id ヘッダーを返した場合、その値はセッションの以降のすべてのリクエストに 付与され、プロセスが終了するまでセッションが再利用されます。応答は プレーンな JSON またはサーバー送信イベントとして届く場合があり、 どちらも読み取ります。

上流からの正常な結果は、上流が設定した isError フラグも含めて、 そのまま返されます。JSON-RPC エラー、2xx 以外のステータス、 読み取り不能な応答、完了できないリクエストなどの失敗は、 テキストが simscout error: で始まる isError 結果として返されます （このエラー表示は、この再構築版独自の、再構築箇所であることを示す実装です）。

CLI

各ツールは、JSON 引数の文字列を 1 つ取るサブコマンドとしても実行できます （引数を取らないツールでは省略してください）。

npx @reneturcios/simscout search_esims '{"country":"JP","days":7,"sort":"price"}'
npx @reneturcios/simscout get_esim '{"id":"plan-9"}'
npx @reneturcios/simscout compare_esims '{"ids":["plan-9","plan-11"]}'
npx @reneturcios/simscout list_countries '{"query":"Japan"}'
npx @reneturcios/simscout --version

終了コード：成功時は 0、isError 結果の場合は 1、 使用方法のエラーの場合は 2。

MCP サーバー

npx -y @reneturcios/simscout mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "simscout": {
      "command": "npx",
      "args": ["-y", "@reneturcios/simscout", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/simscout
docker run --rm ghcr.io/cloudcorprecords/simscout --version

コンテナーのデフォルトコマンドは mcp です。そのため、最初の 形式は stdio MCP サーバーとして動作し、それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化された JSON-RPC アップストリームを使用して実行されます。実際のネットワーク呼び出しはありません。

ライセンス

MIT — LICENSE を参照してください。