flightclaw

flightclaw

FlightClaw 是一款个人旅行预订 Agent。它会记住你的身份、同行者、持有的忠诚度计划和银行卡，以及你的飞行偏好，然后为每次旅程推荐航班、预订、付款并从中学习。

个人资料、预订和付款通过托管服务运行 （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. 奖励机票／积分选项 — 如果他们想使用积分，请调用 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 提供给用户。用户可在该链接页面使用银行卡付款。
   • 关联虚拟卡 — 创建一笔金额恰好为 total_amount、币种为 total_currency 的 Link 支出请求。金额必须包含预订费；仅填写票价会导致金额不足。用户在 Link 中批准该笔支出。然后使用 Link 虚拟卡在 checkout_url 上付款。
4. 反复调用 get_checkout_status(checkout_id)，直到状态为 completed，然后调用 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 会存储用户的卡片和积分；如果存在其他 MCP 服务，Agent 会借助它们补充信息并采取行动：

• 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 忽略）。