# flighttrack

A self-hosted flight price monitor you can share with friends. Everyone talks
to it two ways:

- **Telegram bot** — `/track`, `/list`, `/stop`, and instant push alerts the
  moment a tracked flight drops below its threshold.
- **Remote MCP server** — add it as a custom connector in Claude and ask
  things like "any drops on my tracked flights?" or "what's the cheapest
  time to fly to Tokyo based on my history?"

Both read and write the same Postgres database, filled in by a background
scraper that runs on a schedule.

## How it works

1. `app/scheduler.py` runs forever. Every `CHECK_INTERVAL_MINUTES`, it pulls
   every active tracked flight whose next check is due, scrapes a fresh
   price for it, stores the observation, and — if the price is at or below
   the user's threshold and they haven't been alerted for this flight
   recently — sends a Telegram alert.
2. `app/scraper.py` wraps the `faster-flights` library, which queries Google
   Flights the same way its own web page does internally (a signed request,
   not a headless browser), so it's far lighter and less detectable than
   full browser automation. It reports back a status (`ok` / `empty` /
   `blocked`) so scraper failures don't get silently swallowed.
3. `app/telegram_bot.py` is how people join. DMing the bot `/start` creates
   their account and hands back a personal MCP connector URL (with their
   token baked in). `/track FROM TO YYYY-MM-DD [RETURN_DATE] PRICE [by:YYYY-MM-DD]`
   adds a flight to watch in one line; `/track` with no arguments instead
   walks you through it - shows today's price for the route, then asks for
   your threshold and an optional buy-by deadline. The `by:` date / deadline
   is a decision cutoff - tracking auto-stops after it even if the price
   never dropped, useful when you want to buy well before the flight itself.
   Alerts list every offer at or under your threshold (not just the
   cheapest), each with a direct booking link where one can be built, plus a
   short buy-now-or-wait read based on that flight's own price history.
4. `app/mcp_server.py` is a remote MCP server (Streamable HTTP transport).
   Each friend's connector URL is unique
   (`https://yourhost/mcp?token=THEIR_TOKEN`) so their tracked flights and
   history stay scoped to them — no shared login needed, and it doesn't
   depend on any Claude-side auth feature, since the token just rides along
   in the URL you give them.

## Why this setup, specifically

- **Postgres, not SQLite** — three processes (scheduler, bot, MCP server)
  all touch the database concurrently. Postgres handles that without the
  file-locking headaches SQLite has under concurrent writers.
- **A real always-on VPS, not free-tier serverless** — the scraper needs to
  run on a schedule indefinitely and Postgres needs a persistent disk;
  serverless free tiers generally sleep or reset. A $5-6/mo box (Hetzner
  CX22, DigitalOcean basic droplet) is the simplest thing that actually
  stays up.
- **Query-param token, not the beta connector "request headers" feature** —
  Claude's ability to attach a static auth header to a custom connector is
  still a slow beta rollout as of this writing, so it isn't something to
  depend on. A token embedded in the connector URL itself works today, for
  every friend, regardless of which Claude client or plan they're on.

## Setup

### 1. Get a domain pointed at your server

Remote MCP servers must be reachable over public HTTPS — Claude connects to
it from Anthropic's cloud, not from your friends' laptops. If you don't want
to buy a domain, [duckdns.org](https://www.duckdns.org) gives a free
subdomain. Point it at your VPS's IP.

### 2. Create a Telegram bot

Message [@BotFather](https://t.me/BotFather) on Telegram, `/newbot`, and
copy the token it gives you into `.env`.

### 3. Configure

```bash
cp .env.example .env
# edit .env: TELEGRAM_BOT_TOKEN, POSTGRES_PASSWORD, PUBLIC_MCP_URL
```

### 4. Run it

```bash
docker compose up -d --build
```

This starts three containers (`db`, `bot`, `mcp`) plus the scheduler runs
inside the `bot` container's process group (see `docker-compose.yml`).

### 5. Put HTTPS in front of it

Any reverse proxy that can auto-provision Let's Encrypt certs works —
[Caddy](https://caddyserver.com) is the least config for this:

```
# /etc/caddy/Caddyfile
yourdomain.duckdns.org {
    reverse_proxy localhost:8000
}
```

### 6. Add friends

Have them DM your Telegram bot `/start`. It replies with their personal
connector URL. They paste that into Claude at **Settings → Connectors →
Add custom connector**.

## What's here vs. what's a next step

This is a working skeleton, not a hardened production service. Before
leaning on it hard, you'll want to:

- Add retry/backoff in `scraper.py` for transient failures vs. real blocks.
- Rotate/expire tokens (`app/auth.py` has the hook point).
- Rate-limit the MCP `track_flight` tool so one person can't add hundreds
  of flights and blow through your scrape budget.
- Swap the naive day-of-week average in `get_recommendation` for something
  better once you've got a few months of real data per route.