Google Flights MCP, CLI and Python Library
Update docs for v0.8.0 (#87)
Punit Arani0d592dd11dc0
diff --git a/AGENTS.md b/AGENTS.mdindex 425829c..625bb8b 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -15,7 +15,7 @@ All standard commands are in the `Makefile` and `CLAUDE.md`. Key ones:- **Format**: `make format`- **Tests**: `make test` (standard), `make test-all` (including fuzz)- **CLI**: `uv run fli flights JFK LAX 2026-05-15`-- **MCP HTTP server**: `uv run fli-mcp-http` (serves at `http://127.0.0.1:8000/mcp`)+- **MCP HTTP server**: `uv run fli-mcp-http` (serves at `http://127.0.0.1:8000/mcp/`)### Testing caveats@@ -26,4 +26,4 @@ All standard commands are in the `Makefile` and `CLAUDE.md`. Key ones:### MCP server notes- The MCP HTTP endpoint requires `Accept: application/json, text/event-stream` header.-- The `fli/server/` module referenced in the Makefile (`make server`) does not exist yet; do not attempt to run it.+- The `fli/server/` module has been removed from the codebase.diff --git a/CLAUDE.md b/CLAUDE.mdindex 3eac206..3942849 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -11,7 +11,6 @@ Fli is a Python library that provides programmatic access to Google Flights data- **Core utilities** (`fli/core/`) - Shared parsing and building utilities- **Search engine** (`fli/search/`) - Flight and date search implementations using Google Flights API- **Data models** (`fli/models/`) - Pydantic models for airports, airlines, and flight data structures-- **FastAPI server** (`fli/server/`) - REST API endpoints for flight search functionality## Development Commandsdiff --git a/Makefile b/Makefileindex de1c292..2c2ec50 100644--- a/Makefile+++ b/Makefile@@ -13,12 +13,6 @@ install-dev:install-all:uv sync --extra dev-# Run the server-server:- uv run uvicorn fli.server.main:app-server-dev:- uv run uvicorn fli.server.main:app --reload-# Run the MCP servermcp:uv run fli-mcp@@ -75,8 +69,6 @@ help:@echo " make install - Install dependencies"@echo " make install-dev - Install with dev dependencies"@echo " make install-all - Install all dependencies"- @echo " make server - Run the server"- @echo " make server-dev - Run the development server with reload"@echo " make mcp - Run the MCP server"@echo " make docs - Build the docs"@echo " make format - Format code using ruff"@@ -91,4 +83,4 @@ help:@echo " make devcontainer - Build dev container image"@echo " make requirements - Generate the requirements.txt file"# Declare the targets as phony-.PHONY: help install install-dev install-all server server-dev mcp docs format lint lint-fix test test-mcp test-fuzz test-all ci ci-docker devcontainer requirements+.PHONY: help install install-dev install-all mcp docs format lint lint-fix test test-mcp test-fuzz test-all ci ci-docker devcontainer requirementsdiff --git a/README.md b/README.mdindex 46bcc98..2e83c44 100644--- a/README.md+++ b/README.md@@ -133,10 +133,10 @@ fli --help```bash# Basic flight search-fli flights JFK LHR 2025-10-25+fli flights JFK LHR 2026-10-25# Advanced search with filters-fli flights JFK LHR 2025-10-25 \+fli flights JFK LHR 2026-10-25 \--time 6-20 \ # Departure time window (6 AM - 8 PM)--airlines BA KL \ # Airlines (British Airways, KLM)--class BUSINESS \ # Cabin class@@ -149,7 +149,7 @@ fli flights JFK LHR 2025-10-25 \>> ```bash> # Return machine-readable flight results-> fli flights JFK LHR 2025-10-25 --format json+> fli flights JFK LHR 2026-10-25 --format json> ```### Find Cheapest Dates@@ -160,8 +160,8 @@ fli dates JFK LHR# Advanced search with date rangefli dates JFK LHR \- --from 2025-01-01 \- --to 2025-02-01 \+ --from 2026-01-01 \+ --to 2026-02-01 \--monday --friday # Only Mondays and Fridays```@@ -170,7 +170,7 @@ fli dates JFK LHR \>> ```bash> # Return machine-readable date search results-> fli dates JFK LHR --from 2025-01-01 --to 2025-02-01 --format json+> fli dates JFK LHR --from 2026-01-01 --to 2026-02-01 --format json> ```### CLI Options@@ -179,6 +179,7 @@ fli dates JFK LHR \| Option | Description | Example ||------------------|-----------------------|------------------------|+| `--return, -r` | Return date | `2026-10-30` || `--time, -t` | Departure time window | `6-20` || `--airlines, -a` | Airline IATA codes | `BA KL` || `--class, -c` | Cabin class | `ECONOMY`, `BUSINESS` |@@ -188,14 +189,19 @@ fli dates JFK LHR \#### Dates Command (`fli dates`)-| Option | Description | Example |-|---------------|---------------|------------------------|-| `--from` | Start date | `2025-01-01` |-| `--to` | End date | `2025-02-01` |-| `--class, -c` | Cabin class | `ECONOMY`, `BUSINESS` |-| `--stops, -s` | Maximum stops | `NON_STOP`, `ONE_STOP` |-| `--[day]` | Day filters | `--monday`, `--friday` |-| `--format` | Output format | `text`, `json` |+| Option | Description | Example |+|--------------------|------------------------|------------------------|+| `--from` | Start date | `2026-01-01` |+| `--to` | End date | `2026-02-01` |+| `--duration, -d` | Trip duration in days | `3` |+| `--round, -R` | Round-trip search | (flag) |+| `--airlines, -a` | Airline IATA codes | `BA KL` |+| `--class, -c` | Cabin class | `ECONOMY`, `BUSINESS` |+| `--stops, -s` | Maximum stops | `NON_STOP`, `ONE_STOP` |+| `--time` | Departure time window | `6-20` |+| `--sort` | Sort by price | (flag) |+| `--[day]` | Day filters | `--monday`, `--friday` |+| `--format` | Output format | `text`, `json` |## MCP Server Integrationdiff --git a/docs/api/models.md b/docs/api/models.mdindex e786a51..d026b3b 100644--- a/docs/api/models.md+++ b/docs/api/models.md@@ -17,12 +17,12 @@ flight_segments = [FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LAX, 0]],- travel_date="2024-06-01",+ travel_date="2026-06-01",),FlightSegment(departure_airport=[[Airport.LAX, 0]],arrival_airport=[[Airport.JFK, 0]],- travel_date="2024-06-15",+ travel_date="2026-06-15",)]diff --git a/docs/api/search.md b/docs/api/search.mdindex ad560dd..9aafce6 100644--- a/docs/api/search.md+++ b/docs/api/search.md@@ -41,7 +41,7 @@ filters = FlightSearchFilters(FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LAX, 0]],- travel_date="2024-06-01",+ travel_date="2026-06-01",)],seat_type=SeatType.ECONOMY@@ -65,11 +65,11 @@ filters = DateSearchFilters(FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LAX, 0]],- travel_date="2024-06-01",+ travel_date="2026-06-01",)],- from_date="2024-06-01",- to_date="2024-06-30"+ from_date="2026-06-01",+ to_date="2026-06-30")# Search datesdiff --git a/docs/examples/advanced.md b/docs/examples/advanced.mdindex c2ab6f9..cc26acf 100644--- a/docs/examples/advanced.md+++ b/docs/examples/advanced.md@@ -41,7 +41,7 @@ filters = FlightSearchFilters(FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LHR, 0]],- travel_date="2024-06-01",+ travel_date="2026-06-01",)],seat_type=SeatType.BUSINESS,@@ -75,7 +75,7 @@ filters = FlightSearchFilters(FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LAX, 0]],- travel_date="2024-06-01",+ travel_date="2026-06-01",time_restrictions=TimeRestrictions(earliest_departure=6, # 6 AMlatest_departure=10, # 10 AM@@ -110,11 +110,11 @@ filters = DateSearchFilters(FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LAX, 0]],- travel_date="2024-06-01",+ travel_date="2026-06-01",)],- from_date="2024-06-01",- to_date="2024-06-30",+ from_date="2026-06-01",+ to_date="2026-06-30",seat_type=SeatType.PREMIUM_ECONOMY)@@ -145,11 +145,11 @@ def track_prices(days=7):FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LAX, 0]],- travel_date="2024-06-01",+ travel_date="2026-06-01",)],- from_date="2024-06-01",- to_date="2024-06-07"+ from_date="2026-06-01",+ to_date="2026-06-07")search = SearchDates()@@ -232,7 +232,7 @@ def analyze_results(results: List[FlightResult]) -> pd.DataFrame:from fli.models import (Airport, Airline, SeatType, MaxStops,PassengerInfo, TimeRestrictions, TripType,- FlightSegment, FlightSearchFilters+ FlightSegment, FlightSearchFilters, LayoverRestrictions)from fli.search import SearchFlightsfrom datetime import datetime, timedelta@@ -241,7 +241,7 @@ from datetime import datetime, timedeltaoutbound = FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LHR, 0]],- travel_date="2024-06-01",+ travel_date="2026-06-01",time_restrictions=TimeRestrictions(earliest_departure=6, # 6 AMlatest_departure=12, # 12 PM@@ -253,7 +253,7 @@ outbound = FlightSegment(return_flight = FlightSegment(departure_airport=[[Airport.LHR, 0]],arrival_airport=[[Airport.JFK, 0]],- travel_date="2024-06-15",+ travel_date="2026-06-15",time_restrictions=TimeRestrictions(earliest_departure=14, # 2 PMlatest_departure=20, # 8 PM@@ -296,27 +296,20 @@ filters = FlightSearchFilters(search = SearchFlights()results = search.search(filters)-# Process results with detailed information-for flight in results:- print(f"\nTotal Price: ${flight.total_price}")-- print("\nOutbound Flight:")- for leg in flight.outbound.legs:- print(f"Flight: {leg.airline.value} {leg.flight_number}")- print(f"From: {leg.departure_airport.value} at {leg.departure_datetime}")- print(f"To: {leg.arrival_airport.value} at {leg.arrival_datetime}")- print(f"Duration: {leg.duration} minutes")- if leg.layover_duration:- print(f"Layover: {leg.layover_duration} minutes")-- print("\nReturn Flight:")- for leg in flight.return_flight.legs:- print(f"Flight: {leg.airline.value} {leg.flight_number}")- print(f"From: {leg.departure_airport.value} at {leg.departure_datetime}")- print(f"To: {leg.arrival_airport.value} at {leg.arrival_datetime}")- print(f"Duration: {leg.duration} minutes")- if leg.layover_duration:- print(f"Layover: {leg.layover_duration} minutes")+for outbound_result, return_result in results:+ print(f"\nOutbound Flight (${outbound_result.price}):")+ for leg in outbound_result.legs:+ print(f" Flight: {leg.airline.value} {leg.flight_number}")+ print(f" From: {leg.departure_airport.value} at {leg.departure_datetime}")+ print(f" To: {leg.arrival_airport.value} at {leg.arrival_datetime}")+ print(f" Duration: {leg.duration} minutes")++ print(f"\nReturn Flight:")+ for leg in return_result.legs:+ print(f" Flight: {leg.airline.value} {leg.flight_number}")+ print(f" From: {leg.departure_airport.value} at {leg.departure_datetime}")+ print(f" To: {leg.arrival_airport.value} at {leg.arrival_datetime}")+ print(f" Duration: {leg.duration} minutes")```### Advanced Date Search with Validation@@ -350,8 +343,8 @@ def validate_dates(from_date: str, to_date: str, min_stay: int, max_stay: int):raise ValueError("Minimum stay cannot be greater than maximum stay")-from_date = "2024-06-01"-to_date = "2024-06-30"+from_date = "2026-06-01"+to_date = "2026-06-30"min_stay = 2max_stay = 4diff --git a/docs/guides/mcp.md b/docs/guides/mcp.mdindex 2da0c78..27857de 100644--- a/docs/guides/mcp.md+++ b/docs/guides/mcp.md@@ -92,8 +92,8 @@ Search for flights between two airports on a specific date.{"departure_airport": "JFK","arrival_airport": "LHR",- "departure_time": "2025-03-15T18:00:00",- "arrival_time": "2025-03-16T06:30:00",+ "departure_time": "2026-03-15T18:00:00",+ "arrival_time": "2026-03-16T06:30:00","duration": 450,"airline": "BA","flight_number": "BA178"@@ -134,13 +134,13 @@ Find the cheapest travel dates between two airports within a date range."success": true,"dates": [{- "date": "2025-03-15",+ "date": "2026-03-15","price": 350.00,"currency": "USD","return_date": null},{- "date": "2025-03-18",+ "date": "2026-03-18","price": 375.00,"currency": "USD","return_date": null@@ -148,7 +148,7 @@ Find the cheapest travel dates between two airports within a date range.],"count": 30,"trip_type": "ONE_WAY",- "date_range": "2025-03-01 to 2025-03-31"+ "date_range": "2026-03-01 to 2026-03-31"}```diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.mdindex 7da7bac..4b67f15 100644--- a/docs/guides/quickstart.md+++ b/docs/guides/quickstart.md@@ -23,19 +23,19 @@ pipx install flights1. Search for one-way flights:```bash-fli flights JFK LHR 2025-06-01+fli flights JFK LHR 2026-06-01```2. Search for round trip flights:```bash-fli flights JFK LHR 2025-06-01 --return 2025-06-15+fli flights JFK LHR 2026-06-01 --return 2026-06-15```3. Search with filters:```bash-fli flights JFK LHR 2025-06-01 \+fli flights JFK LHR 2026-06-01 \--time 6-20 \ # Departure window (6 AM - 8 PM)--airlines BA KL \ # Airlines (British Airways, KLM)--class BUSINESS \ # Cabin class@@ -45,7 +45,7 @@ fli flights JFK LHR 2025-06-01 \4. Find cheapest dates:```bash-fli dates JFK LHR --from 2025-06-01 --to 2025-06-30+fli dates JFK LHR --from 2026-06-01 --to 2026-06-30```!!! warning "Experimental"@@ -55,8 +55,8 @@ fli dates JFK LHR --from 2025-06-01 --to 2025-06-305. Return machine-readable JSON:```bash-fli flights JFK LHR 2025-06-01 --format json-fli dates JFK LHR --from 2025-06-01 --to 2025-06-30 --format json+fli flights JFK LHR 2026-06-01 --format json+fli dates JFK LHR --from 2026-06-01 --to 2026-06-30 --format json```### MCP Server (for AI Assistants)@@ -89,7 +89,7 @@ flight_segments = [FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LAX, 0]],- travel_date="2025-06-01"+ travel_date="2026-06-01")]@@ -127,12 +127,12 @@ flight_segments = [FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LAX, 0]],- travel_date="2025-06-01"+ travel_date="2026-06-01"),FlightSegment(departure_airport=[[Airport.LAX, 0]],arrival_airport=[[Airport.JFK, 0]],- travel_date="2025-06-15"+ travel_date="2026-06-15")]@@ -175,11 +175,11 @@ filters = DateSearchFilters(FlightSegment(departure_airport=[[Airport.JFK, 0]],arrival_airport=[[Airport.LAX, 0]],- travel_date="2025-06-01",+ travel_date="2026-06-01",)],- from_date="2025-06-01",- to_date="2025-06-30"+ from_date="2026-06-01",+ to_date="2026-06-30")# Search dates@@ -212,7 +212,13 @@ python examples/basic_one_way_search.py* `round_trip_search.py` - Round-trip flight search example* `date_range_search.py` - Date range search example* `complex_flight_search.py` - Advanced filtering example+* `time_restrictions_search.py` - Time-constrained search example+* `date_search_with_preferences.py` - Weekend and day filtering example+* `complex_round_trip_validation.py` - Complex round-trip with validation+* `advanced_date_search_validation.py` - Advanced date search with validation+* `price_tracking.py` - Price monitoring over time* `error_handling_with_retries.py` - Robust error handling example+* `result_processing.py` - Data analysis with pandas> 💡 **Tip**: Examples include automatic dependency checking and will guide you through installation if dependencies are missing.diff --git a/docs/index.md b/docs/index.mdindex 37a65c6..60b2e34 100644--- a/docs/index.md+++ b/docs/index.md@@ -69,8 +69,8 @@ See the [MCP Guide](guides/mcp.md) for Claude Desktop configuration.The `--format json` CLI output is experimental. The schema is intended for agents and tools such as `jq`, but may evolve in future releases.```bash-fli flights JFK LHR 2025-06-01 --format json-fli dates JFK LHR --from 2025-06-01 --to 2025-06-30 --format json+fli flights JFK LHR 2026-06-01 --format json+fli dates JFK LHR --from 2026-06-01 --to 2026-06-30 --format json``````pythondiff --git a/examples/README.md b/examples/README.mdindex 0483c89..a8bb6ba 100644--- a/examples/README.md+++ b/examples/README.md@@ -198,8 +198,8 @@ from datetime import datetime, timedeltafuture_date = (datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d")# Date ranges-from_date = "2024-06-01"-to_date = "2024-06-30"+from_date = "2026-06-01"+to_date = "2026-06-30"```### Passenger Configurationdiff --git a/mkdocs.yml b/mkdocs.ymlindex 86c3adf..265979a 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -1,9 +1,9 @@site_name: Fli Documentationsite_url: https://punitarani.github.io/fli-site_description: Documentation for the Fli library - A Python wrapper for Google Flights API+site_description: Documentation for the Fli library - A Python library for direct Google Flights API accessrepo_url: https://github.com/punitarani/flisite_author: Punit Arani-copyright: Copyright © 2024 Punit Arani+copyright: Copyright © 2024-2026 Punit Aranitheme:name: materialdiff --git a/skills/fli/SKILL.md b/skills/fli/SKILL.mdindex 2a7527b..13cb79d 100644--- a/skills/fli/SKILL.md+++ b/skills/fli/SKILL.md@@ -105,7 +105,7 @@ Do not tell users to run `pipx install fli`.Use:```bash-fli flights JFK LAX 2025-10-25+fli flights JFK LAX 2026-10-25```### Cheapest-date search@@ -113,7 +113,7 @@ fli flights JFK LAX 2025-10-25Use:```bash-fli dates JFK LAX --from 2025-01-01 --to 2025-01-31+fli dates JFK LAX --from 2026-01-01 --to 2026-01-31```### Common filters@@ -121,7 +121,7 @@ fli dates JFK LAX --from 2025-01-01 --to 2025-01-31Use filters like these when the user asks for them:```bash-fli flights JFK LHR 2025-10-25 \+fli flights JFK LHR 2026-10-25 \--time 6-20 \--airlines BA KL \--class BUSINESS \