punitarani/fli

# 🛫 Fli - Flight Search MCP Server and Library 一个强大的 Python 库，提供对 Google Flights 数据的编程访问，并具有优雅的 CLI 界面。搜索航班，找到最佳优惠，并轻松筛选结果。 ## MCP Server ``` pipx install flights # 在 STDIO 上运行 MCP Server fli-mcp # 通过 HTTP 运行 MCP Server (可流式传输) fli-mcp-http # serves at http://127.0.0.1:8000/mcp/ ```  ### 连接到 Claude Desktop ``` { "mcpServers": { "fli": { "command": "/Users//.local/bin/fli-mcp" } } } ``` ### 可用的 MCP Tools MCP 服务器提供两个主要工具： | Tool | Description | |----------------------|-------------------------------------------------------------| | **`search_flights`** | Search for flights on a specific date with detailed filters | | **`search_dates`** | Find the cheapest travel dates across a flexible date range | #### `search_flights` 参数 | Parameter | Type | Description | |--------------------|--------|-----------------------------------------------------| | `origin` | string | Departure airport IATA code (e.g., 'JFK') | | `destination` | string | Arrival airport IATA code (e.g., 'LHR') | | `departure_date` | string | Travel date in YYYY-MM-DD format | | `return_date` | string | Return date for round trips (optional) | | `cabin_class` | string | ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST | | `max_stops` | string | ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS | | `departure_window` | string | Time window in 'HH-HH' format (e.g., '6-20') | | `airlines` | list | Filter by airline codes (e.g., ['BA', 'AA']) | | `sort_by` | string | CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME | | `passengers` | int | Number of adult passengers | #### `search_dates` 参数 | Parameter | Type | Description | |--------------------|--------|----------------------------------------------| | `origin` | string | Departure airport IATA code (e.g., 'JFK') | | `destination` | string | Arrival airport IATA code (e.g., 'LHR') | | `start_date` | string | Start of date range in YYYY-MM-DD format | | `end_date` | string | End of date range in YYYY-MM-DD format | | `trip_duration` | int | Trip duration in days (for round-trips) | | `is_round_trip` | bool | Whether to search for round-trip flights | | `cabin_class` | string | ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST | | `max_stops` | string | ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS | | `departure_window` | string | Time window in 'HH-HH' format (e.g., '6-20') | | `airlines` | list | Filter by airline codes (e.g., ['BA', 'AA']) | | `sort_by_price` | bool | Sort results by price (lowest first) | | `passengers` | int | Number of adult passengers | ## 快速开始 ``` pip install flights ``` ``` # 使用 pipx 安装 (推荐用于 CLI) pipx install flights # CLI 入门 fli --help ```  ## 特性 * 🔍 **Powerful Search** * One-way flight searches * Flexible departure times * Multi-airline support * Cabin class selection * Stop preferences * Custom result sorting * 💺 **Cabin Classes** * Economy * Premium Economy * Business * First * 🎯 **Smart Sorting** * Price * Duration * Departure Time * Arrival Time * 🛡️ **Built-in Protection** * Rate limiting * Automatic retries * Comprehensive error handling * Input validation ## CLI 使用 ### 搜索航班 ``` # 基本航班搜索 fli flights JFK LHR 2026-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 --stops NON_STOP \ # Non-stop flights only --sort DURATION # Sort by duration ``` ### 查找最便宜日期 ``` # 基本日期搜索 fli dates JFK LHR # 使用日期范围进行高级搜索 fli dates JFK LHR \ --from 2026-01-01 \ --to 2026-02-01 \ --monday --friday # Only Mondays and Fridays ``` ### CLI 选项 #### 航班命令 (`fli flights`) | 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` | | `--stops, -s` | Maximum stops | `NON_STOP`, `ONE_STOP` | | `--sort, -o` | Sort results by | `CHEAPEST`, `DURATION` | | `--format` | Output format | `text`, `json` | #### 日期命令 (`fli dates`) | 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 集成 Fli 包含一个 Model Context Protocol (MCP) 服务器，允许像 Claude 这样的 AI 助手直接搜索航班。这可以通过对话进行自然语言的航班搜索。 ### 运行 MCP Server ``` # 在 STDIO 上运行 MCP Server fli-mcp # 或者使用 uv (用于开发) uv run fli-mcp # 或者使用 make (用于开发) make mcp # 通过 HTTP 运行 MCP Server (可流式传输) fli-mcp-http # serves at http://127.0.0.1:8000/mcp/ ``` ### Claude Desktop 配置 要在 Claude Desktop 中使用航班搜索功能，请将此配置添加到您的 `claude_desktop_config.json`： **Location**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ``` { "mcpServers": { "flight-search": { "command": "fli-mcp", "args": [] } } } ``` 添加此配置后： 1. Restart Claude Desktop 2. You can now ask Claude to search for flights naturally: * "Find flights from JFK to LAX on December 25th" * "What are the cheapest dates to fly from NYC to London in January?" * "Search for business class flights from SFO to NRT with no stops" ## Python API 使用 ### 基本搜索示例 ``` from datetime import datetime, timedelta from fli.models import ( Airport, PassengerInfo, SeatType, MaxStops, SortBy, FlightSearchFilters, FlightSegment ) from fli.search import SearchFlights # 创建搜索过滤器 filters = FlightSearchFilters( passenger_info=PassengerInfo(adults=1), flight_segments=[ FlightSegment( departure_airport=[[Airport.JFK, 0]], arrival_airport=[[Airport.LAX, 0]], travel_date=(datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d"), ) ], seat_type=SeatType.ECONOMY, stops=MaxStops.NON_STOP, sort_by=SortBy.CHEAPEST, ) # 搜索航班 search = SearchFlights() flights = search.search(filters) # 处理结果 for flight in flights: print(f"💰 Price: ${flight.price}") print(f"⏱️ Duration: {flight.duration} minutes") print(f"✈️ Stops: {flight.stops}") for leg in flight.legs: print(f"\n🛫 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}") ``` ### 运行示例 我们在 `examples/` 目录中提供了 11 个综合示例，展示了各种用例： ``` # 使用 uv 运行示例 (推荐) uv run python examples/basic_one_way_search.py uv run python examples/round_trip_search.py uv run python examples/date_range_search.py # 或者先安装依赖，然后直接运行 pip install pydantic curl_cffi httpx python examples/basic_one_way_search.py ``` **Available Examples:** * `basic_one_way_search.py` - Simple one-way flight search * `round_trip_search.py` - Round-trip flight booking * `date_range_search.py` - Find cheapest dates * `complex_flight_search.py` - Advanced filtering and multi-passenger * `time_restrictions_search.py` - Time-based filtering * `date_search_with_preferences.py` - Weekend filtering * `price_tracking.py` - Price monitoring over time * `error_handling_with_retries.py` - Robust error handling * `result_processing.py` - Data analysis with pandas * `complex_round_trip_validation.py` - Advanced round-trip with validation * `advanced_date_search_validation.py` - Complex date search with filtering ## 示例 有关展示所有功能的综合示例，请参见 [`examples/`](examples/) 目录： ``` # 快速测试 - 运行一个简单示例 uv run python examples/basic_one_way_search.py # 运行所有示例以探索不同功能 uv run python examples/round_trip_search.py uv run python examples/complex_flight_search.py uv run python examples/price_tracking.py ``` **Example Categories:** * **Basic Usage**: One-way, round-trip, date searches * **Advanced Filtering**: Time restrictions, airlines, seat classes * **Data Analysis**: Price tracking, result processing with pandas * **Error Handling**: Retry logic, robust error management * **Complex Scenarios**: Multi-passenger, validation, business rules Each example is self-contained and includes automatic dependency checking with helpful installation instructions. ## 开发 ``` # 克隆仓库 git clone https://github.com/punitarani/fli.git cd fli # 使用 uv 安装依赖 uv sync --all-extras # 运行测试 uv run pytest # 运行 linting uv run ruff check . uv run ruff format . # 构建文档 uv run mkdocs serve # 或者使用 Makefile 执行常见任务 make install-all # Install all dependencies make test # Run tests make lint # Check code style make format # Format code ``` ### Docker 开发 ``` # 构建 devcontainer docker build -t fli-dev -f .devcontainer/Dockerfile . # 在容器内运行 CI docker run --rm fli-dev make lint test-all # 或者分别运行 lint 和测试 docker run --rm fli-dev make lint docker run --rm fli-dev make test-all ``` ### 使用 act 本地运行 CI To run GitHub Actions locally, install [act](https://github.com/nektos/act): ``` brew install act # 本地运行 CI (在 Python 3.10-3.13 上运行 lint + 测试) make ci # 或者在 Docker 中运行 CI (无需本地安装 act) make ci-docker ``` ## 贡献 Contributions are welcome! Please feel free to submit a Pull Request. ## 许可证 This project is licensed under the MIT License — see the LICENSE file for details.

标签：API封装, Claude桌面集成, Google Flights, HTTP服务, MCP服务器, Model Context Protocol, URL抓取, 代码示例, 数据分析, 数据抓取, 文档结构分析, 旅行助手, 旅行比价, 机票查询, 网络调试, 自动化, 航班搜索, 请求拦截, 运行时操纵, 逆向工具