Metadata-Version: 2.4
Name: flight-planner-mcp
Version: 0.2.0
Summary: Flight planner for AI agents: airport lookup, nearby search, route check, distance, rolling BTS fare baseline, date hints, trip skeletons, ranked 1-stop/2-stop pairs. No booking.
Author-email: Surendran B <reachsuren@gmail.com>
License-Expression: MIT
Keywords: mcp,flights,flight-planner,airports,ourairports,static,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<3,>=2.0.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"

# flight-planner-mcp (package: `flight-planner-mcp`)

Static flight planner v0.2. 10 tools (airport_lookup, airport_nearby, route_check, distance_calc, fare_baseline latest-available-snapshot BTS median (DB1C Market 2026-06), cheap_date_hint low-confidence, trip_skeleton with METAR/TAF + FAA best-effort, flight_pairs 1-stop + 2-stop ranked, skills_list, skill_read), OurAirports 4,568 airports + 34,824 directed pairs, great-circle stdlib. No booking, no DB, zero paid API, zero secrets in repo.

## Fare baseline (latest-available snapshot, BTS DB1C Market — DB1C Market 2026-06)

`data/fares-us-rolling.json` holds passenger-weighted median/p25/p75 per directional US O&D from DB1C Market 2026-06 (latest available at build time; 40% ticket sample, public domain), built by `scripts/build_fares.py` from BTS DB1C bulk archives (Parquet/CSV). Zero-fare artifacts dropped; routes with n<50 sampled tickets are suppressed (tool returns `[TOO_THIN]`, never a guess). `data/fares-VINTAGE.txt` stamps the covered period. Raw files live outside the repo and are never committed — only the ~3.1MB aggregate ships.

## Refresh (monthly cron, snapshot replaced each build)

DB1C publishes monthly. Each update cycle, download the newest monthly archive and rebuild; the snapshot is replaced whole, no archive kept.

```cron
# monthly, 06:00 UTC on the 20th
0 6 20 * * cd ~/Projects/flight-planner-mcp && uv run --with duckdb python scripts/build_fares.py /tmp/DB1C.MARKET.*.parquet && python3 tests/test_e2e_contract.py
```

Manual fallback: download the newest DB1C Market archive from BTS Azure Blob storage and run `build_fares.py`. Never fake data: ship what exists and stamp the vintage honestly.

## Install

### Option A — Claude Code plugin (one click)

```bash
claude plugin marketplace add surendranb/flight-planner-mcp
claude plugin install flight-planner-mcp
```

Ships `.claude-plugin/plugin.json` (name `flight-planner-mcp`, version pinned to pyproject) + `.mcp.json`; skills resolve from `./skills/`.

### Option B — any MCP harness (incl. Antigravity, zero cloning)

Paste this block into the harness MCP config; the tester gets all 10 tools + `skills_list`/`skill_read` with no repo checkout:

```json
{
  "mcpServers": {
    "flight-planner-mcp": {
      "command": "uvx",
      "args": ["--from", "flight-planner-mcp", "flight-planner-mcp"],
      "env": {}
    }
  }
}
```

Same snippet lives in `mcp-config.json` at repo root. Opt out of telemetry with `"env": {"MCP_TELEMETRY_OPT_OUT": "1"}`. Requires `uvx` on PATH and network on first run.

## Refresh (plugin version pinning)

`skill_read` live-fetches `https://raw.githubusercontent.com/surendranb/flight-planner-mcp/main/skills/<name>.md` (local file is fallback only). Skill text edits therefore reach every installed copy at next call with no version bump. Bump `plugin.json` + `marketplace.json` versions only when tools, schemas, or data files change; keep them equal to the pyproject version.
