# ✈️ Flight Tool MCP Server

A lightweight [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that exposes real-time flight search as a tool for any MCP-compatible AI agent — Claude, LangGraph, or any other MCP client.

Built on top of the [AviationStack](https://aviationstack.com/) API using [FastMCP](https://github.com/jlowin/fastmcp).

---

## What it does

```mermaid
flowchart LR
    A["MCP Client<br/>(Claude / LangGraph Agent)"] -->|"tools/call<br/>search_flights"| B["Flight Tool<br/>MCP Server"]
    B -->|"GET /v1/flights"| C["AviationStack API"]
    C -->|"live flight data"| B
    B -->|"structured JSON result"| A

    style A fill:#1f6feb,color:#fff
    style B fill:#238636,color:#fff
    style C fill:#9e6a03,color:#fff
```

Give it a departure and arrival airport (IATA code), and it returns real-time flight data — airline, flight number, scheduled/actual times, and status (scheduled, active, landed, cancelled).

---

## Tool: `search_flights`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `dep_iata` | `str` | ✅ | Departure airport IATA code, e.g. `"BBI"` (Bhubaneswar) |
| `arr_iata` | `str` | ✅ | Arrival airport IATA code, e.g. `"DEL"` (Delhi) |

**Returns:**
```json
{
  "success": true,
  "count": 40,
  "flights": [
    {
      "airline": "IndiGo",
      "flight_number": "6E6176",
      "departure_airport": "Bhubaneswar",
      "departure_time": "2026-08-10T15:40:00+00:00",
      "arrival_airport": "Indira Gandhi International",
      "arrival_time": "2026-08-10T18:00:00+00:00",
      "status": "scheduled"
    }
  ]
}
```

> **Note:** Only real-time/current flight data is supported on the free AviationStack tier — no historical or future-dated search. A `flight_date` filter was originally planned but dropped, since date-based queries aren't reliably supported on the free plan.

---

## Setup

### 1. Clone and install dependencies
```bash
pip install fastmcp requests python-dotenv
```

### 2. Add your API key
Create a `.env` file:
```env
AVIATIONSTACK_API_KEY=your_aviationstack_key_here
```
Get a free key at [aviationstack.com](https://aviationstack.com/).

### 3. Run locally
```bash
python main.py
```
By default this runs over `stdio`, ready to be picked up by any local MCP client (e.g. Claude Desktop config, MCP Inspector).

---

## Deploying to Render

Switch the transport to SSE/HTTP so it can run as a persistent web service:

```python
if __name__ == "__main__":
    mcp.run(transport="sse", host="0.0.0.0", port=8000)
```

Then on Render:
1. Create a new **Web Service**, connect this repo
2. Set the start command: `python main.py`
3. Add `AVIATIONSTACK_API_KEY` under **Environment Variables**
4. Deploy — your MCP server will be live at `https://your-service.onrender.com`

---

## Free-Tier Constraints (AviationStack)

Keep these in mind while extending this server:

- ✅ `http://` only — `https://` is **not** supported on the free plan
- ✅ `/v1/flights` (real-time data) works on free tier
- ❌ `/v1/routes`, `/v1/airports`, `/v1/airlines` return `function_access_restricted` — paid plans only
- ❌ Historical / future `flight_date` filtering is unreliable on free tier
- ⚠️ 100 requests/month limit — test sparingly

---

## Tech Stack

- **FastMCP** — MCP server framework
- **AviationStack API** — live flight data
- **Requests** — HTTP client
- **python-dotenv** — environment config

---

## Roadmap

- [ ] Deploy to Render as a persistent SSE endpoint
- [ ] Wire into Trip-Friend's LangGraph flight_agent via `langchain-mcp-adapters`
- [ ] Add guardrails (rate limiting, input validation)
- [ ] Explore paid-tier upgrade for route/airport lookup tools

---

## License

See [LICENSE](./LICENSE).