<div align="center">

<img src="assets/waypoint-banner.svg" alt="Waypoint — Find your way to the right airport" width="100%">

<br/>

### Find the right airport. Start anywhere.

Discover departure and destination airports by city, country, airport name, or code — powered by open data, with no API key required.

<br/>

[![CI](https://github.com/ahmedsameh123-hub/waypoint-airport-finder/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmedsameh123-hub/waypoint-airport-finder/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
![FastAPI](https://img.shields.io/badge/API-FastAPI-009688?logo=fastapi&logoColor=white)
![Streamlit](https://img.shields.io/badge/UI-Streamlit-FF4B4B?logo=streamlit&logoColor=white)
![MCP](https://img.shields.io/badge/AI-MCP-7451B8)
![License](https://img.shields.io/badge/License-MIT-42D6C3)

<br/>

[Features](#sparkles-features) · [Quick start](#rocket-quick-start) · [API](#globe-api) · [Docker](#whale-docker) · [MCP](#robot-mcp-integration)

</div>

---

## ✨ Features

| | Capability | What it does |
|:--:|---|---|
| 🌍 | **Global airport search** | Find airports by city, country, airport name, IATA code, or ICAO code. |
| 🧭 | **Trip suggestions** | Compare departure and destination airport shortlists side by side. |
| 📍 | **Nearby airports** | Discover airports within a radius of any latitude/longitude. |
| 🗺️ | **Interactive dashboard** | Explore airport cards, useful stats, and a map in Streamlit. |
| ⚡ | **FastAPI service** | A documented REST API with validation and interactive Swagger docs. |
| 🤖 | **MCP-ready** | Let compatible AI clients ask Waypoint for airport suggestions. |
| 🔓 | **No API key** | Starts with free, openly licensed airport data from OurAirports. |

> **Data, not flight bookings:** Waypoint finds airports. It does not provide live flights, schedules, fares, or route availability.

## 🚀 Quick start

**Requirements:** Python 3.11+ and Node.js 20.6+ (only needed for the MCP server).

```powershell
# 1. Create and activate a virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 2. Install the API and dashboard
python -m pip install -r requirements.txt

# 3. Start the API
uvicorn app.main:app --reload
```

Open a second terminal in the project directory:

```powershell
.\.venv\Scripts\Activate.ps1
streamlit run frontend/Home.py
```

<div align="center">

| Service | Local address |
|:--|:--|
| **Waypoint dashboard** | [http://localhost:8501](http://localhost:8501) |
| **Interactive API docs** | [http://localhost:8000/docs](http://localhost:8000/docs) |
| **Alternative API docs** | [http://localhost:8000/redoc](http://localhost:8000/redoc) |

</div>

On its first request, the API downloads the OurAirports dataset to `data/airports.csv` and keeps a local copy, refreshed every 24 hours. An internet connection is needed for the initial download.

## 🌐 API

### Compare a trip

```http
POST /trips/suggest
Content-Type: application/json
```

```json
{
  "origin": "Cairo",
  "destination": "Paris",
  "limit": 5,
  "scheduled_only": true
}
```

### Search airports

```http
GET /airports/search?q=Cairo&limit=10&scheduled_only=true
```

### Find nearby airports

```http
GET /airports/nearby?lat=30.0444&lon=31.2357&radius_km=100&limit=10
```

### Check data status or refresh the dataset

```http
GET  /health
GET  /meta
POST /admin/refresh
```

## 🐳 Docker

With Docker Desktop installed, start the API and dashboard together:

```powershell
docker compose up --build
```

Visit [localhost:8501](http://localhost:8501) for the dashboard or [localhost:8000/docs](http://localhost:8000/docs) for the API. Docker Compose stores the downloaded airport dataset in a named volume.

Stop the services with **Ctrl+C**, then run:

```powershell
docker compose down
```

## 🤖 MCP integration

Build the MCP server:

```powershell
npm ci
npm run build
```

Start the FastAPI service, then add this server to your MCP client's configuration (replace the example path with your project path):

```json
{
  "mcpServers": {
    "waypoint-airports": {
      "command": "node",
      "args": ["C:\\path\\to\\waypoint-airport-finder\\dist\\index.js"],
      "env": {
        "AIRPORT_API_URL": "http://127.0.0.1:8000"
      }
    }
  }
}
```

The `suggest_travel_airports` tool accepts an origin, destination, an optional result limit, and a `scheduledOnly` filter. Only airports with scheduled passenger service are returned by default. The API must remain running while you use MCP.

## ⚙️ Configuration

No secrets or API keys are needed. To customize the local settings, copy `.env.example` to `.env`:

```dotenv
AIRPORT_API_URL=http://127.0.0.1:8000
AIRPORT_DATA_DIR=./data
```

| Variable | Purpose |
|---|---|
| `AIRPORT_API_URL` | FastAPI address used by the Streamlit dashboard and MCP client. |
| `AIRPORT_DATA_DIR` | Local folder used to cache the airport dataset. |
| `CORS_ORIGINS` | Comma-separated browser origins permitted by the API. |

## 🧑‍💻 Development

```powershell
# Python tests
python -m unittest discover -s tests -v

# Build the TypeScript MCP server
npm ci
npm run build
```

GitHub Actions runs the Python suite and MCP build on each push and pull request.

## 📚 Airport data

Airport records are sourced from [OurAirports](https://ourairports.com/data/) and distributed under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). Please keep this attribution when redistributing the data.

---

<div align="center">

**Made for smoother journeys.** &nbsp; ✈️ &nbsp; [Back to top ↑](#waypoint--open-airport-finder)

</div>