mcpField
F
fallback-and-resilience

fallback-and-resilience

github.com/borskiエージェントワークフロー78071 回インストール2 日前に更新
リポジトリ

fallback-and-resilience について

旅行計画エージェント向けの障害対策ガイドです。航空券やホテルなどの検索先の代替案と、停止・レート制限・アクセス制限への対応をまとめています。

主な機能

  1. 01検索先ごとの代替案
  2. 02API・サーバー障害への対応規則
  3. 03IP 許可リストエラーの診断
  4. 04ブラウザー自動化の障害対策
  5. 05代替先利用時の情報開示規則

活用シーン

  1. 01航空券検索の障害時に別サービスへ切り替え
  2. 02API のレート制限後に代替先を探す
  3. 03初回利用時の IP 拒否を診断
  4. 04検索結果がない路線の運航有無を確認

MCP 対応

MCP サーバーの呼び出し失敗時の復旧方法として、代替ソースの利用などを説明します。実際にツールを呼び出す前に、サーバーが利用不可と判断しないよう求めています。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/borski/travel-hacking-toolkit --skill fallback-and-resilience

インストール後、Claude Code で/fallback-and-resilienceを入力して読み込まれたか確認します。

詳細

フォールバックとレジリエンス

ツールは停止します。API は壊れます。検索ごとにバックアッププランを用意してください。

プライマリツール障害発生時フォールバック
DuffelAPI エラーまたはタイムアウトIgnav、Google Flights スキル、Skiplagged
IgnavAPI エラーDuffel、Google Flights スキル、Skiplagged
Google Flightsagent-browser エラーDuffel、Ignav、Skiplagged
Skiplagged502／タイムアウト（Cloudflare の問題）Kiwi.com MCP、Duffel、Ignav
Kiwi.comサーバーエラーSkiplagged MCP、Duffel
Seats.aeroAPI エラーまたは古いデータ航空会社のウェブサイトを直接確認するか、GDS の在庫確認に Duffel を使用
SouthwestSW のレート制限またはボット検出数分待ってから再試行してください。ローカルで実行できない場合は、Docker（ghcr.io/borski/sw-fares）を使用してください。現金価格をすばやく確認するフォールバックとして、Google Flights スキルを使用してください。
SerpAPIレート制限（無料枠は月100回）ホテルには Trivago、旅行先の検索にはウェブ検索
Trivagoサーバーエラーホテルには LiteAPI、または SerpAPI Google Hotels
LiteAPI認証エラー（401）Trivago MCP、SerpAPI Google Hotels
Airbnbスクレイピングがブロックされたairbnb.com を直接確認するようユーザーに提案
AwardWalletAPI エラー残高を直接ユーザーに尋ねる
FerryhopperサーバーエラーSerpAPI またはフェリールートのウェブ検索
Atlas Obscuraスクリプトエラー「[destination] でできる珍しいこと」をウェブ検索
Chase Travelログイン失敗または CSRF の問題現金価格には Duffel／Ignav を使用します。Points Boost と Edit の検出は Chase 限定であることに注意してください。
Amex Travelログイン失敗またはフォームの変更現金価格には Duffel／Ignav を使用します。IAP 運賃と FHR／THC の検出は Amex 限定であることに注意してください。
Deutsche Bahn（db-vendo）ライブラリエラーまたは bahn.de の停止SerpAPI Google Travel Explore、「[origin] [dest] DB train」のウェブ検索、または代わりに利用可能なフライトの確認
Wikipedia airportsAPI のレート制限（まれ）またはページが見つからない「[airport name] airlines destinations」をウェブ検索すると、Google 経由で同じデータが得られます。
運賃ツールで「結果なし」と表示される空席がないか、運航便がない可能性がありますwikipedia-airports を使って、その路線が実際に運航されているか確認してください。 Wikipedia に就航先として掲載されている場合、運賃ツールではその日に空席がありません。Wikipedia に掲載されていない場合、その路線は存在しません。絶対に成功しない検索をユーザーに再試行させずに済みます。

一般的なルール

  • MCP サーバーがエラーを返した場合は、 curl ベースのスキルに相当するものを試してください（またはその逆）。
  • **有料 API がレート制限に達した場合は、**無料の代替手段に切り替えてください。
  • **ツールが1つ失敗しただけで諦めないでください。**必ず少なくとも1つのフォールバックを試してください。
  • 使用した情報源をユーザーに伝えてください。「Skiplagged が停止していたため、代わりに Kiwi.com を確認しました。」

呼び出さずに MCP が利用できないと判断しない

ツール一覧を一目見ただけで、MCP サーバーが「利用できない」と判断してはいけません。**まず実際にツールを呼び出してください。**Skiplagged サーバーと Kiwi サーバーには API キーが不要で、サポート対象のすべてのハーネス設定に接続されています。リポジトリのディレクトリから起動したセッションでは利用できます。呼び出しが実際に失敗した場合は、エラーをユーザーに引用してからフォールバックしてください。

また、フォールバックする際に、ツールキットの情報源の代わりとして、その場しのぎのブラウザーによるスクレイピングを黙って使ってはいけません。その場しのぎのスクレイピング（例：ブラウザーを手動で操作して Google Flights を調べる方法）では、市場の大半が反映されない価格になります。やむを得ず使う場合は、そのことを明示し、そこから得た価格にはすべて信頼度が低いと記してください。「MCP の情報源に接続できなかったため、スクレイピングで得た価格は1件のみです。市場価格ではなく、上限の目安として扱ってください。」

IP 許可リストに関するエラー（初回に起きやすい失敗）

このツールキットの複数の API では、開発者キーに対する IP 許可リストが適用されています。次のエラー形式が表示された場合は、認証やクォータについて深追いしないでください。まずユーザーに IP を許可リストに追加するよう提案してください。

APIエラー形式許可リストのページ
AwardWallet{"error": "access_denied", "code": "IP_DENIED"}https://business.awardwallet.com/profile/api
TripAdvisorUser is not authorized to access this resource with an explicit denyhttps://www.tripadvisor.com/developers

初回利用時に、認証エラーのようなエラーで API 呼び出しが失敗した場合の診断手順：

  1. curl ifconfig.me を実行して、ユーザーの現在の送信元 IP を取得します。
  2. エラー形式が IP 許可リストに関するものと一致するか確認します（上の表、または「explicit deny」／「IP_DENIED」／「not whitelisted」のような類似表現）。
  3. ユーザーに次のように伝えます。「これはキーの問題ではなく、IP 許可リストの問題のようです。 で <their IP> を追加し、AWS のエッジキャッシュに反映されるまで 1〜5 分待ってから再試行してください。」
  4. ユーザーが IP を許可リストに追加している間は、適切に機能を縮退させます。そのデータソースなしで処理を続け、対応待ちであることを伝えてください。ワークフローの残りの処理を止めないでください。
  5. 複数 IP に関する注意点：住宅用 CGNAT、VPN の出口、ホテルの Wi-Fi、旅行先の場所では、それぞれ個別に登録する必要があります。新しいネットワークから同じエラーが発生した場合は、IP が変わっています。

「キャッシュされた空席情報がありません」は最終結論ではありません

Seats.aero が路線とプログラムの組み合わせに対して結果を返さない場合、Seats.aero が最近その情報を取得していないことを意味します。特典航空券が予約できないという意味ではありません。利用可能なプログラムでキャッシュされた結果がない場合は、特典航空券の予約は不可能だと判断する前に、航空会社のウェブサイトを直接検索してください。

Patchright ベースのスキル（Southwest、AA、Chase、Amex、TaW）

これらのスキルは、検出を回避するブラウザーでウェブサイトに直接アクセスします。よくある失敗の原因：

  • ログインフォームの変更。 サイトの DOM が更新されています。セレクターが動作しなくなります。スキルを更新してください。
  • 2FA のループ。 一部のスキル（AA、Amex）はメールによる 2FA に対応しています。アカウントで 2FA の送信方法が正しく設定されていることを確認してください。
  • ボット検出。 「unusual activity」や CAPTCHA のページが表示された場合、永続プロファイルがフラグ付けされている可能性があります。新しいプロファイルを試すか、1 時間待ってください。
  • ヘッドレス検出。 Patchright はヘッドありで動作します。ローカルで失敗する場合は、Docker イメージを使ってください（xvfb が仮想ディスプレイを提供します）。

Docker イメージの失敗

docker pull ghcr.io/borski/... が失敗する場合：

  • unauthorized： docker logout ghcr.io を実行してから、もう一度試してください。または、read:packages 権限を持つ GitHub PAT でログインしてください。それ以外の場合は、docker build -t <tag> skills/<skill>/ でローカルにビルドしてください。
  • ネットワークのタイムアウト： ARM 環境でチェックサムの不一致が発生する場合は、--platform linux/amd64 を指定して再試行してください。

コメント

Markdown 対応