flightclaw

flightclaw

FlightClaw は、個人向けの旅行予約エージェントです。利用者本人や同行者、保有しているロイヤルティプログラムやカード、好みのフライトを記憶し、その情報をもとに旅行を提案、予約、支払いし、旅行ごとに学習します。

プロフィール、予約、支払いはホスト型サーバー （https://mcp.flightclaw.com/mcp、OAuth サインイン）で実行します。このリポジトリのローカルサーバーでは、フライトの検索と価格の追跡のみを行います。

ワークフロー

1. 初期設定（初回のみ）

一度設定すれば、その後はずっと再利用できます。

1. 利用者本人 — 自分の情報を save_traveler で保存します（パスポートに記載された正確な氏名、生年月日、連絡先、ロイヤルティプログラム）。次に set_me でそのプロフィールを自分として登録し、出発地となる空港を設定します。
2. 同行者 — 一緒に旅行する人ごとに save_traveler で保存します（relationship：配偶者／パートナー／子ども／親／友人／同僚）。save_group でグループを作成します（例：family = jack,jane）。
3. 好み — set_preferences で設定します：旅行距離ごとの座席クラス（例：短距離は ECONOMY、長距離は BUSINESS）、希望する／避けたい航空会社、航空連合、座席、出発時間帯、乗り継ぎの最大回数、深夜便の許容度、手荷物、食事、予算に対する優先度（cheapest／balanced／comfort）。
4. カードとポイント — カードごとに save_card を実行し、ロイヤルティ／ポイント移行プログラムごとに set_points_balance を実行します。その後、Card Links MCP（find_transfer_programs_for_airline、list_transfer_partners）を使って情報を補完し、各カードのポイントをどの航空会社で利用できるかを確認します。

2. 旅行の計画

1. 行き先と同行者を尋ねます。既存のグループは get_group で再利用できます（予約に使う正確な passengers 文字列が返されます）。または、save_group で新しいグループを作成します。
2. おすすめ — recommend_flights(origin, destination, date, ...) を実行します。保存済みの好みを読み込み、旅行距離に応じて座席クラスを選び、避けたい航空会社を除外します。料金／所要時間／乗り継ぎ回数／希望する航空会社／出発時間帯／深夜便の許容度を基準に選択肢を順位付けし、それぞれに「おすすめする理由」を添えて上位3件を返します。
3. 特典航空券／ポイント利用の選択肢 — ポイントを使いたい場合は、保存済みのロイヤルティプログラムとポイント残高を使い、Award Travel Finder MCP（search_availability、search_all_airlines、get_pricing）を呼び出します。現金での運賃と併せて、特典航空券の選択肢を提示します（「総合おすすめ／最安／ポイント還元率が最も高い」）。

3. 予約と支払い

ホスト型サーバー（https://mcp.flightclaw.com/mcp）

1. search_flights／search_multi_city／recommend_flights → オファーを選択 → get_offer で料金、手荷物、運賃規則を確認します。オファーの有効期限は約30分です。
2. 利用者に選択内容を確認してから、create_checkout(offer_id, passengers) を実行します。checkout_id、checkout_url、正確な total_amount と total_currency（航空会社の運賃＋FlightClaw の予約手数料）が返されます。この時点ではまだ請求されません。
3. 次のいずれかの方法で支払います。
   • チェックアウトリンク — 利用者に checkout_url と total_amount を伝えます。利用者はそこでカード決済します。
   • Link のバーチャルカード — total_currency で total_amount と完全に一致する Link の支払いリクエストを作成します。金額には予約手数料を含める必要があります。運賃だけでは不足します。利用者が Link で支払いを承認したら、Link のバーチャルカードを使って checkout_url で支払います。
4. completed になるまで get_checkout_status(checkout_id) を実行し、その後 get_order を実行します。failed は支払いが行われていないことを意味するため、再試行できます。

支払いのルール：

• create_checkout が返す total_amount を使ってください。自分で料金を計算してはいけません。
• 利用者が Link で承認した金額を超えて支払ってはいけません。合計金額が変わった場合は処理を中止し、新しいチェックアウトを作成して、改めて承認を求めてください。
• 利用者にカード番号を尋ねたり、入力させたりしてはいけません。

予約後、log_trip（ルート、日付、旅行者、座席クラス、料金、order_id）を呼び出し、旅行を履歴とフォローアップキューに追加します。

4. 旅行後のフォローアップと学習（本当の醍醐味）

1. trips_pending_followup で、旅行が終了して帰着した旅行を表示します。
2. それぞれの旅行について感想を尋ね、record_trip_feedback(id, feedback, learnings=...) を実行します。 「長距離便では窓側を好む」「早朝の出発は苦手」といった長期的に役立つ教訓がユーザーの好みに追加されるため、次回の recommend_flights の精度が上がります。使い続けることで、FlightClaw は旅行者について学習していきます。

ツール

パーソナライズ（ホスト型）

• 旅行者：save_traveler、list_travelers、get_traveler、delete_traveler、 set_me、get_me。
• 好み：set_preferences、get_preferences、update_preferences。
• カード／ポイント：save_card、list_cards、delete_card、set_points_balance、 list_points。
• グループ：save_group、list_groups、get_group、delete_group。
• 旅行：log_trip、list_trips、get_trip、trips_pending_followup、 record_trip_feedback。
• おすすめ：recommend_flights。

検索と追跡 — search_flights、search_dates、track_flight、check_prices、list_tracked、remove_tracked。

ホスト型の予約 — get_offer、get_seat_map、create_checkout、 get_checkout_status、list_orders、get_order、request_change、 cancel_order。ホスト型の価格追跡：track_flight、list_tracked、 remove_tracked（毎日確認し、価格が下がるとメールで通知します）。

外部 MCP 連携

FlightClaw はユーザーのカードとポイントを保存します。エージェントは、利用可能な場合、ほかの 2 つの MCP サーバーを使って情報を充実させ、これらを活用します。

• Card Links — ユーザーが保存したカードの提携先とカードの比較情報。
• Award Travel Finder — 航空会社やプログラムを横断した特典航空券の空席状況とポイント価格。

Card Links のカードおすすめを提示する際は、必ず免責事項も記載してください。金融アドバイスではないこと、アフィリエイトリンクによって紹介料が発生する場合があること、カードの利用条件は変更されるため、現在の特典をカード発行会社に確認する必要があること。

セットアップ

ホスト型：claude mcp add --transport http flightclaw https://mcp.flightclaw.com/mcp （OAuth でサインインしてください。キーは不要です）。

ローカル（検索と価格追跡のみ。アカウントは不要）：

pip install "flights==0.9.0" "mcp[cli]<2" fastmcp pydantic-settings
claude mcp add flightclaw -- python3 /path/to/agents/server.py

データ

ローカルサーバーは、価格追跡履歴を data/tracked.json に保存します （Git で無視されます）。