flightclaw

---
name: flightclaw
description: Personal travel-booking agent. Onboard a traveler once (who you are, companions, loyalty programs, credit cards, travel preferences), then chat about where you want to go and get a few preference-ranked flight options, fully book and pay for them, and follow up after the trip to learn how you like to travel. Also searches and price-tracks flights via Google Flights. Runs as an MCP server (Python 3.10+, fli + mcp). Profiles live server-side in the private flightclaw-api Worker (D1).
---

# 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

```bash
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.