# Flight Search MCP

Full-stack flight search application demonstrating the Model Context Protocol (MCP) with real-time Google Flights data.

![AI Flight Search Assistant](docs/flight_search_mcp.png)

## Overview

This is a monorepo featuring a Next.js frontend and Spring Boot MCP server that provides live flight search capabilities using SerpAPI's Google Flights API.

**Tech Stack:**
- **Frontend**: Next.js 16 + React 19 + TypeScript + Tailwind CSS
- **Backend**: Spring Boot 3.4.5 + Spring AI 1.1.0 + Java 17
  - MCP Flight Server (port 8080) - Flight search tools
  - MCP Client Service (port 8081) - AI chat integration
- **Protocol**: Model Context Protocol (MCP) over HTTP Streaming
- **AI**: Anthropic Claude Sonnet 4.5
- **API**: SerpAPI Google Flights

## Quick Start

### Prerequisites

- **Frontend**: Node.js 18+ and npm
- **Backend**: Java 17+ and Maven 3.6+
- **API Keys**:
  - SerpAPI key (get one at [serpapi.com](https://serpapi.com))
  - Anthropic API key (get one at [console.anthropic.com](https://console.anthropic.com))

### Setup

1. **Clone the repository:**
   ```bash
   git clone https://github.com/apappascs/mcp-flight-search.git
   cd flight-search-mcp
   ```

2. **Set environment variables:**
   ```bash
   export SERP_GOOGLE_FLIGHTS_API_KEY=your_serpapi_key_here
   export ANTHROPIC_API_KEY=your_anthropic_key_here
   ```

3. **Start everything (recommended):**
   ```bash
   ./start-all.sh
   ```

   This script will:
   - Verify both API keys
   - Start MCP Flight Server on port 8080
   - Start MCP Client Service on port 8081
   - Start frontend on port 3000
   - Open browser automatically
   - Display logs in real-time

### Manual Start

**Terminal 1 - MCP Flight Server:**
```bash
cd backend/mcp-flight-server
./mvnw spring-boot:run
```

**Terminal 2 - MCP Client Service:**
```bash
cd backend/mcp-client-service
./mvnw spring-boot:run
```

**Terminal 3 - Frontend:**
```bash
cd frontend
npm install  # First time only
npm run dev
```

**Browser:**
```bash
open http://localhost:3000
```

## Project Structure

```
flight-search-mcp/
├── frontend/                        # Next.js application (port 3000)
│   ├── app/                        # App router pages
│   ├── components/                 # React components
│   ├── lib/                        # MCP & AI chat clients
│   ├── types/                      # TypeScript types
│   └── README.md                   # Frontend documentation
│
├── backend/
│   ├── mcp-flight-server/          # MCP Flight Server (port 8080)
│   │   ├── src/main/java/          # Flight search service
│   │   ├── src/main/resources/     # Configuration
│   │   └── README.md               # Server documentation
│   │
│   └── mcp-client-service/         # MCP Client Service (port 8081)
│       ├── src/main/java/          # AI chat integration
│       ├── src/main/resources/     # Configuration
│       └── README.md               # Client documentation
│
├── start-all.sh                    # One-command launcher
├── logs/                           # Application logs
├── README.md                       # This file
└── CLAUDE.md                       # Claude Code guide
```

## Features

- **Dual Search Modes**: Classic form-based search + AI chat powered by Claude
- **MCP Flight Server**: Provides flight search tools via Model Context Protocol
- **AI Integration**: Natural language flight queries using Claude Sonnet 4.5
- **Real-time Data**: Live flight information from Google Flights via SerpAPI
- **Lufthansa Focus**: Optimized for Lufthansa Group airlines

## Development

### Frontend Scripts

```bash
cd frontend

npm run dev      # Start development server
npm run build    # Build for production
npm run lint     # Run linter
npm run clean    # Clean build artifacts
npm run rebuild  # Full rebuild
```

### Backend Scripts

```bash
cd backend/mcp-flight-server

./mvnw clean package        # Build
./mvnw spring-boot:run      # Run server
./start-server.sh           # Run with startup script
```

## Testing

### Health Checks

```bash
# Backend health
curl http://localhost:8080/actuator/health

# Frontend API health
curl http://localhost:3000/api/flights/search
```

### Example Search

Search Frankfurt (FRA) to Berlin (BER):
```bash
curl -X POST http://localhost:3000/api/flights/search \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "Frankfurt/Main International",
    "destination": "Berlin - Brandenburg",
    "departureDate": "2025-12-01",
    "returnDate": "2025-12-08",
    "tripType": "roundTrip",
    "travelClass": "Economy",
    "travelers": 1
  }'
```

## Architecture

### Classic Search Flow
```
User Browser (localhost:3000)
    ↓ HTTP POST
Next.js API Route
    ↓ MCP over HTTP Streaming
MCP Flight Server (localhost:8080)
    ↓ REST API
SerpAPI (Google Flights)
```

### AI Chat Search Flow
```
User Browser (localhost:3000)
    ↓ HTTP POST
Next.js API Route
    ↓ HTTP
MCP Client Service (localhost:8081)
    ↓ Anthropic API
Claude Sonnet 4.5
    ↓ MCP Tool Calls
MCP Flight Server (localhost:8080)
    ↓ REST API
SerpAPI (Google Flights)
```

## Configuration

### Frontend

No configuration required. Default MCP server: `http://localhost:8080/mcp`

### Backend

Edit `backend/mcp-flight-server/src/main/resources/application.properties`:

```properties
server.port=8080
spring.ai.mcp.server.path=/mcp
serpapi.api.key=${SERP_GOOGLE_FLIGHTS_API_KEY}
serpapi.localization.country=de
serpapi.localization.language=en
serpapi.localization.currency=EUR
```

## Troubleshooting

### API Key Issues

```bash
# Verify keys are set
echo $SERP_GOOGLE_FLIGHTS_API_KEY
echo $ANTHROPIC_API_KEY

# Set if missing
export SERP_GOOGLE_FLIGHTS_API_KEY=your_serpapi_key
export ANTHROPIC_API_KEY=your_anthropic_key
```

### Port Conflicts

```bash
# Check if ports are in use
lsof -i :3000  # Frontend
lsof -i :8080  # MCP Flight Server
lsof -i :8081  # MCP Client Service

# Kill processes if needed
kill -9 <PID>
```

### Build Issues

```bash
# Frontend
cd frontend
npm run clean
npm install
npm run build

# Backend
cd backend/mcp-flight-server
./mvnw clean package
```

### Connection Issues

Ensure backend is running before starting frontend:
```bash
curl http://localhost:8080/actuator/health
```

## Documentation

- **[Frontend README](frontend/README.md)** - Frontend setup and development
- **[MCP Flight Server README](backend/mcp-flight-server/README.md)** - Flight search MCP tools
- **[MCP Client Service README](backend/mcp-client-service/README.md)** - AI chat integration


This is a demonstration project showcasing MCP integration patterns. Feel free to use it as a reference for building your own MCP applications.