# SkyOdyssey MCP

SkyOdyssey MCP exposes the SkyOdyssey flight engine as a Model Context Protocol server.

It is designed for AI clients (Claude Desktop, MCP Inspector, custom MCP hosts) that need:

- Cheapest destination exploration
- Multi-leg itinerary optimization
- Region/airport reference resources

---

## Features

- MCP tools for flight search and itinerary optimization
- Shared core logic with `SkyOdyssey-CLI` (`logic.py`, `airports.py`)
- Country/airport/airline filters
- Budget-aware pruning (`max_budget`)
- Direct-flight filtering
- Multi-origin and flexible stay support for 3-leg itineraries
- SQLite caching (`flights_cache.db`, TTL 6h)
- Retry/backoff behavior for unstable provider responses
- Pydantic validation on itinerary outputs

---

## Tools Exposed

### `get_flights_on_date`
Fetch one-way flights for a specific route/date.

Inputs:
- `origin` (IATA)
- `destination` (IATA)
- `date` (`YYYY-MM-DD`)
- `adults` (default `1`)
- `seat_type` (default `economy`)

### `get_cheapest_destinations`
Explore a region from one origin/date and return cheapest options.

Inputs:
- `origin`
- `date`
- `region` (default `Europe`)
- `limit` (default `15`)
- `adults`
- `seat_type`
- `excluded_countries`
- `excluded_airports`
- `direct_only`
- `include_airlines`, `exclude_airlines`
- `max_budget`

### `find_cheapest_two_city_itinerary`
Find cheapest 3-leg itinerary loops.

Inputs include:
- `origin` (single airport or list)
- `start_date`
- `stay_days_1` / `stay_days_2` (fixed int or `[min, max]`)
- `region`
- `limit_per_leg`
- `excluded_countries`, `excluded_airports`
- `max_itineraries`
- `force_different_countries`
- `direct_only`
- `return_origin` (open-jaw)
- `include_airlines`, `exclude_airlines`
- `max_budget`

Guardrails:
- `origin` list max: `5`
- `limit_per_leg` max: `30`
- `max_itineraries` max: `100`
- stay range window max width: `14` days (for each of `stay_days_1` and `stay_days_2`)

---

## Resources

- `airports://regions` → available regions
- `airports://{region}` → airport codes for a region

---

## Requirements

- Python 3.10+
- Internet access (provider scraping via `fast-flights`)

---

## Installation

From `SkyOdyssey-MCP`:

```bash
python -m pip install -r requirements.txt
```

---

## Run the Server

```bash
python server.py
```

Server transport:
- `stdio` (configured in `server.py`)

---

## Claude Desktop Example

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "skyodyssey": {
      "command": "python",
      "args": ["C:/absolute/path/to/SkyOdyssey/SkyOdyssey-MCP/server.py"]
    }
  }
}
```

---

## Project Structure

- `server.py` — MCP server entrypoint and tool/resource registration
- `logic.py` — flight search, filtering, optimization, cache
- `airports.py` — regions, airport datasets, exclusion helpers
- `requirements.txt` — runtime dependencies

---

## Troubleshooting

### Import error for `fast_flights`
- Reinstall dependencies: `python -m pip install -r requirements.txt`
- Ensure your Python environment is the same one used to run `server.py`

### Empty or partial results
- Provider instability/timeouts can happen; retry run
- Reduce search width (`limit_per_leg`) and/or constraints
- Relax filters (`direct_only`, exclusions, budget)

### Cache issues
- Delete cache if needed:
  - Windows PowerShell: `Remove-Item flights_cache.db`
  - Windows cmd: `del flights_cache.db`

---

## License

MIT License.