Skip to content

armgit / fli

Public Imported from GitHub
0

Google Flights MCP, CLI and Python Library

feat: add development container setup and Dockerfile

Punit Aranie370818693dc
diff --git a/.actrc b/.actrc
new file mode 100644
index 0000000..5c08277
--- /dev/null
+++ b/.actrc
@@ -0,0 +1 @@
+-P ubuntu-latest=catthehacker/ubuntu:act-latest
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 0000000..941f3f8
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,36 @@
+FROM python:3.10-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ git \
+ curl \
+ make \
+ && rm -rf /var/lib/apt/lists/*
+
+# Install act (for running GitHub Actions locally)
+RUN curl -sSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b /usr/local/bin
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Set up workspace
+WORKDIR /workspace
+
+# Copy dependency files first for better layer caching
+COPY pyproject.toml uv.lock README.md ./
+
+# Copy source for package install
+COPY fli/ ./fli/
+
+# Install dependencies
+RUN uv sync --extra dev --frozen
+
+# Copy the rest of the project
+COPY . .
+
+# Ensure the virtual environment is activated by default
+ENV PATH="/workspace/.venv/bin:$PATH"
+ENV VIRTUAL_ENV="/workspace/.venv"
+
+# Default command
+CMD ["bash"]
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..cb3eb36
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,24 @@
+{
+ "name": "fli-dev",
+ "build": {
+ "dockerfile": "Dockerfile",
+ "context": ".."
+ },
+ "workspaceFolder": "/workspace",
+ "mounts": [
+ "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
+ ],
+ "customizations": {
+ "vscode": {
+ "extensions": [
+ "ms-python.python",
+ "charliermarsh.ruff"
+ ],
+ "settings": {
+ "python.defaultInterpreterPath": "/workspace/.venv/bin/python"
+ }
+ }
+ },
+ "postCreateCommand": "uv sync --extra dev",
+ "remoteUser": "root"
+}
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..a4948d3
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,14 @@
+.venv/
+**/__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+junit.xml
+site/
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index b001a63..f328635 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -42,7 +42,7 @@ jobs:
FORCE_COLOR: 1
- name: Upload Test Results
- if: always()
+ if: always() && !env.ACT
uses: actions/upload-artifact@v6
with:
name: Test Results (Python ${{ matrix.python-version }})
diff --git a/Makefile b/Makefile
index 58173f7..de1c292 100644
--- a/Makefile
+++ b/Makefile
@@ -49,6 +49,22 @@ test-fuzz:
test-all:
uv run --extra dev pytest -vv --all
+# Run CI locally using act (requires Docker and act: https://github.com/nektos/act)
+ci:
+ act -j lint -j test --workflows .github/workflows/test.yml
+
+# Run CI in Docker container (mounts source and Docker socket for act)
+ci-docker:
+ docker run --rm \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ -v $(PWD):/workspace \
+ -w /workspace \
+ fli-dev make ci
+
+# Build dev container
+devcontainer:
+ docker build -t fli-dev -f .devcontainer/Dockerfile .
+
# Generate the requirements.txt file
requirements:
uv export --format requirements-txt --no-hashes > requirements.txt
@@ -70,6 +86,9 @@ help:
@echo " make test-mcp - Run tests with MCP"
@echo " make test-fuzz - Run tests with fuzzing"
@echo " make test-all - Run all tests"
+ @echo " make ci - Run CI locally using act (requires Docker)"
+ @echo " make ci-docker - Run CI in Docker container"
+ @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 requirements
+.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
diff --git a/README.md b/README.md
index fe3f63b..6d653ff 100644
--- a/README.md
+++ b/README.md
@@ -46,42 +46,42 @@ fli-mcp-http # serves at http://127.0.0.1:8000/mcp/
The MCP server provides two main tools:
-| Tool | Description |
-|------|-------------|
+| 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_dates`** | Find the cheapest travel dates across a flexible date range |
#### `search_flights` Parameters
-| 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 |
+| 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` Parameters
-| 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 |
+| 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 |
+| `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 |
## Quick Start
@@ -102,30 +102,30 @@ fli --help
## Features
* πŸ” **Powerful Search**
- * One-way flight searches
- * Flexible departure times
- * Multi-airline support
- * Cabin class selection
- * Stop preferences
- * Custom result sorting
+ * 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
+ * Economy
+ * Premium Economy
+ * Business
+ * First
* 🎯 **Smart Sorting**
- * Price
- * Duration
- * Departure Time
- * Arrival Time
+ * Price
+ * Duration
+ * Departure Time
+ * Arrival Time
* πŸ›‘οΈ **Built-in Protection**
- * Rate limiting
- * Automatic retries
- * Comprehensive error handling
- * Input validation
+ * Rate limiting
+ * Automatic retries
+ * Comprehensive error handling
+ * Input validation
## CLI Usage
@@ -161,27 +161,28 @@ fli dates JFK LHR \
#### Flights Command (`fli flights`)
-| Option | Description | Example |
-|------------------|--------------------------|------------------------|
-| `--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` |
+| Option | Description | Example |
+|------------------|-----------------------|------------------------|
+| `--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` |
#### 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` |
+| 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` |
## MCP Server Integration
-Fli includes a Model Context Protocol (MCP) server that allows AI assistants like Claude to search for flights directly. This enables natural language flight search through conversation.
+Fli includes a Model Context Protocol (MCP) server that allows AI assistants like Claude to search for flights directly.
+This enables natural language flight search through conversation.
### Running the MCP Server
@@ -220,9 +221,9 @@ After adding this configuration:
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"
+ * "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 Usage
@@ -301,7 +302,8 @@ python examples/basic_one_way_search.py
* `complex_round_trip_validation.py` - Advanced round-trip with validation
* `advanced_date_search_validation.py` - Complex date search with filtering
-> πŸ’‘ **Tip**: Examples include automatic dependency checking and will show helpful installation instructions if dependencies are missing.
+> πŸ’‘ **Tip**: Examples include automatic dependency checking and will show helpful installation instructions if
+> dependencies are missing.
## Examples
@@ -354,6 +356,34 @@ make lint # Check code style
make format # Format code
```
+### Docker Development
+
+```bash
+# Build the devcontainer
+docker build -t fli-dev -f .devcontainer/Dockerfile .
+
+# Run CI inside the container
+docker run --rm fli-dev make lint test-all
+
+# Or run lint and tests separately
+docker run --rm fli-dev make lint
+docker run --rm fli-dev make test-all
+```
+
+### Running CI Locally with act
+
+To run GitHub Actions locally, install [act](https://github.com/nektos/act):
+
+```bash
+brew install act
+
+# Run CI locally (lint + tests on Python 3.10-3.13)
+make ci
+
+# Or run CI inside Docker (no local act installation needed)
+make ci-docker
+```
+
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.