flightclaw

flightclaw

FlightClaw is a personal travel-booking agent. It remembers who you are, who you
travel with, the loyalty programs and cards you hold, and how you like to fly —
then recommends, books, pays for, and learns from each trip.

Personalization data (travelers, preferences, cards/points, companion groups,
trip history) is stored server-side in the private flightclaw-api Worker
(D1), reached via FLIGHTCLAW_API_URL + FLIGHTCLAW_API_KEY. Payment for
bookings routes through Link virtual cards (duffel_book_with_link).

The flow

1. Onboarding (one time)

Set this up once, then reuse forever.

1. Who you are — save_traveler for yourself (full passport-accurate name,
   DOB, contact, loyalty programmes), then set_me to mark that profile as you
   and record home airports.
2. Companions — save_traveler for each person you travel with
   (relationship: spouse/partner/child/parent/friend/colleague). Group them
   with save_group (e.g. family = jack,jane).
3. Preferences — set_preferences: cabin by haul (e.g. short-haul ECONOMY,
   long-haul BUSINESS), preferred/avoided airlines, alliance, seat, departure
   window, max stops, red-eye tolerance, baggage, meal, and budget sensitivity
   (cheapest / balanced / comfort).
4. Cards & points — save_card for each card; set_points_balance for each
   loyalty/transfer program. Then enrich with the Card Links MCP
   (find_transfer_programs_for_airline, list_transfer_partners) so you know
   which airlines each card's points can reach.

2. Planning a trip

1. Ask where they want to go and who's coming — reuse a group with
   get_group (it returns the exact passengers string for booking) or make a
   new one with save_group.
2. Recommend — recommend_flights(origin, destination, date, ...). It loads
   the saved preferences, picks the cabin by haul, drops avoided airlines, and
   ranks options on price/duration/stops/preferred-airline/departure-window/
   red-eye, returning the top 3 with a "why this fits you" for each.
3. Awards / points option — if they want to spend points, call the Award
   Travel Finder MCP (search_availability, search_all_airlines,
   get_pricing) using their stored loyalty programs and points balances, and
   present award options alongside the cash fares ("best overall / cheapest /
   best points value").

3. Booking & paying

1. Get a bookable, payable offer with duffel_search_flights (real fares/
   conditions). duffel_get_offer / duffel_get_seat_map for extras.
2. Confirm the choice with the user, then duffel_book_with_link with the
   group's passengers string. This creates a Link spend request (the user
   approves the charge, ≤ $500), returns a virtual card + Duffel checkout URL,
   and you complete payment via Chrome automation. For higher amounts use
   duffel_book_flight (Duffel balance) or duffel_create_checkout.
3. log_trip right after booking (route, dates, travelers, cabin, price,
   order_id) so it enters history and the follow-up queue.

4. Post-trip follow-up & learning (the real magic)

1. trips_pending_followup surfaces trips that have completed/returned.
2. Ask how each went, then record_trip_feedback(id, feedback, learnings=...).
   Durable lessons (e.g. "prefers window on long-haul", "dislikes early
   departures") are appended to the user's preferences, so the next
   recommend_flights is sharper. Over time FlightClaw learns the traveler.

Tools

Personalization (backend-backed)

• Travelers: save_traveler, list_travelers, get_traveler, delete_traveler,
  set_me, get_me, import_local_passengers (one-time migration of any old
  local data/passengers.json).
• Preferences: set_preferences, get_preferences, update_preferences.
• Cards/points: save_card, list_cards, delete_card, set_points_balance,
  list_points.
• Groups: save_group, list_groups, get_group, delete_group.
• Trips: log_trip, list_trips, get_trip, trips_pending_followup,
  record_trip_feedback.
• Recommendation: recommend_flights.

Search & tracking — search_flights, search_dates, track_flight,
check_prices, list_tracked, remove_tracked.

Booking (Duffel) — duffel_search_flights, duffel_search_multi_city,
duffel_get_offer, duffel_get_seat_map, duffel_book_flight,
duffel_book_with_link, duffel_create_checkout, duffel_list_orders,
duffel_get_order, duffel_request_change, duffel_confirm_change,
duffel_cancel_order, duffel_confirm_cancel, duffel_check_alerts,
link_list_payment_methods.

External MCP integration

FlightClaw stores the user's cards/points; the agent enriches and acts on them
using two other MCP servers when present:

• Card Links — transfer partners and card comparisons for the user's stored
  cards.
• Award Travel Finder — award availability and points pricing across
  airlines/programs.

When surfacing card recommendations from Card Links, always include its
disclaimers: not financial advice; affiliate links may earn commission; card
terms change — verify current offers with the issuer.

Setup

pip install flights "mcp[cli]"
export FLIGHTCLAW_API_URL="https://flightclaw-api.<your>.workers.dev"
export FLIGHTCLAW_API_KEY="<your API key>"
claude mcp add flightclaw -- python3 /path/to/flightclaw/server.py

The Worker (flightclaw-api) holds the Duffel token and D1 profile store; apply
schema.sql once with wrangler d1 execute flightclaw-db --remote --file schema.sql.

Data

Personalization data is server-side (D1). Price-tracking history
(data/tracked.json) and a local Duffel order cache (data/duffel_orders.json)
remain local and are gitignored.