Content
# PointPilot
**Open-source award flight search engine.** Find the best way to use credit card points for flights — with a REST API, MCP server for Claude Desktop, and a step-by-step booking playbook engine.
[Live App](https://flypointpilot.com) · [API Docs](#api-endpoints) · [MCP Setup](#use-with-claude-desktop)
---
## What It Does
PointPilot searches across airline loyalty programs to find award flights, then tells you exactly how to book them:
1. **Search** — Enter your origin, dates, and points balances. PointPilot checks award availability across programs (Aeroplan, ANA, Virgin Atlantic, etc.) and compares against cash prices.
2. **Rank** — Results are scored by cents-per-point (CPP) value, cash savings, transfer path availability, and booking friction.
3. **Playbook** — Select a flight and get step-by-step transfer and booking instructions, including risk warnings (low seats, slow transfers, expiring promos).
### Supported Points Programs
| Program | Code |
|---------|------|
| Amex Membership Rewards | `MR` |
| Chase Ultimate Rewards | `CHASE` |
| Capital One Miles | `CAP1` |
| Citi ThankYou Points | `CITI` |
| Bilt Rewards | `BILT` |
| Marriott Bonvoy | `MARRIOTT` |
---
## Quick Start
### 1. Clone and install
```bash
git clone https://github.com/wrahim3933/PointPilot.git
cd PointPilot/backend
pip install -r requirements.txt
```
### 2. Configure
```bash
cp .env.example .env
# Edit .env — no API keys needed for basic functionality (mock providers work out of the box)
```
### 3. Run the API
```bash
uvicorn app.main:app --reload --port 8000
```
The API is now running at `http://localhost:8000`. Try it:
```bash
# Health check
curl http://localhost:8000/health
# Search for award flights from JFK in July
curl -X POST http://localhost:8000/v1/trip-searches \
-H "Content-Type: application/json" \
-d '{
"origins": ["JFK"],
"date_window_start": "2025-07-01",
"date_window_end": "2025-07-15",
"duration_nights": 5,
"travelers": 2,
"cabin_preference": "business",
"search_mode": "points",
"balances": [{"program": "MR", "balance": 150000}, {"program": "CHASE", "balance": 80000}]
}'
```
---
## Use with Claude Desktop
PointPilot includes an MCP server so you can search flights and get playbooks directly from Claude.
### Setup
**1. Install uv** (if you don't have it):
```bash
brew install uv # macOS
# or: curl -LsSf https://astral.sh/uv/install.sh | sh
```
**2. Add to Claude Desktop config** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"pointpilot": {
"command": "uv",
"args": [
"run", "--with", "mcp[cli]", "--with", "requests",
"python", "/path/to/PointPilot/backend/mcp_server.py"
],
"env": {
"POINTPILOT_API_BASE": "https://pointpilot-api.up.railway.app"
}
}
}
}
```
> Update the path to where you cloned the repo. For local development, change `POINTPILOT_API_BASE` to `http://localhost:8000`.
**3. Restart Claude Desktop.** The tools appear automatically.
### MCP Tools
| Tool | Description |
|------|-------------|
| `search_award_flights` | Find award flights from any origin, ranked by value |
| `generate_booking_playbook` | Get step-by-step transfer and booking instructions |
| `get_featured_deals` | See curated award deals available right now |
| `get_transfer_partners` | Explore transfer partners and active bonuses for any program |
**Example prompt:**
> "Find me business class flights from JFK to Tokyo using my 150k MR points"
---
## API Endpoints
### Trip Searches
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/trip-searches` | Create a new trip search |
| `GET` | `/v1/trip-searches/{id}` | Retrieve a trip search |
### Recommendations
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/recommendations/generate` | Generate ranked award flight options |
### Playbooks
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/playbook/generate` | Generate booking playbook from a recommendation |
| `POST` | `/v1/playbook/generate-from-match` | Generate playbook from raw flight params |
| `POST` | `/v1/playbook-ai/explain-step` | AI explanation for a playbook step |
### Deals & Data
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/featured-deals` | Current featured award deals |
| `POST` | `/v1/outcomes` | Record a booking outcome |
| `GET` | `/health` | Health check |
---
## Architecture
```
backend/
├── mcp_server.py # MCP server for Claude Desktop (stdio)
├── app/
│ ├── main.py # FastAPI entry point
│ ├── store.py # JSON file persistence
│ ├── routers/ # HTTP endpoints
│ ├── services/ # Business logic
│ │ ├── recommender.py # Destination candidate generation
│ │ ├── scoring.py # Blended value scoring
│ │ ├── valuation.py # CPP range & confidence calculation
│ │ ├── risk.py # Booking risk assessment
│ │ ├── transfer_graph.py # Card → airline transfer paths
│ │ ├── playbook_service.py # Step-by-step playbook builder
│ │ └── ai/ # AI explanation engines (mock / Claude)
│ ├── adapters/
│ │ ├── providers.py # Award & airfare data providers
│ │ └── interfaces.py # Provider protocol definitions
│ ├── domain/
│ │ └── models.py # Pydantic models
│ └── data/ # Static transfer partner & airline data
├── data/ # Runtime data (deals, snapshots)
└── scripts/ # Data pipeline scripts
```
### How Scoring Works
Each award option is scored on three axes:
- **CPP Value** — cents per point, computed as `(cash_price - taxes) / points_cost`. Capped at 7.5 cpp to prevent outliers.
- **Out-of-Pocket Cost** — total cash the traveler actually pays (taxes on award, or full fare in cash mode).
- **Friction** — penalty for stops, long travel times, and complex itineraries.
These are combined into a blended score weighted by the user's preference (`maximize_value`, `minimize_cost`, or `balanced`).
### AI Provider Toggle
The playbook explanation endpoint supports two providers:
```bash
# Default — deterministic, no API key needed
AI_PROVIDER=mock
# Claude Sonnet — requires ANTHROPIC_API_KEY
AI_PROVIDER=claude
```
---
## Optional: Live Data Sources
Out of the box, PointPilot uses estimated/mock data that works without API keys. For live data:
| Source | What It Provides | Env Var |
|--------|-----------------|---------|
| [Seats.aero](https://seats.aero) | Live award seat availability | `SEATS_AERO_API_KEY` |
| [Duffel](https://duffel.com) | Live cash airfare pricing | `DUFFEL_API_KEY` |
| [Anthropic](https://anthropic.com) | AI playbook explanations | `ANTHROPIC_API_KEY` |
---
## Contributing
Contributions welcome! Some areas that could use help:
- **More transfer partner data** — adding new programs or updating transfer ratios
- **Better destination coverage** — expanding the route candidate pool
- **Scoring improvements** — refining the CPP/friction/value model
- **New MCP tools** — hotel search, multi-city routing, etc.
```bash
# Run locally
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
# Test MCP server
mcp dev backend/mcp_server.py
```
---
## License
MIT — see [LICENSE](LICENSE).
