# Airline Flight Delays MCP Server

**AI-Powered Customer Service Automation for Weather-Related Flight Disruptions**

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-0.4.0-green.svg)](https://github.com/jlowin/fastmcp)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## 📋 Overview

This project presents a Model Context Protocol (MCP) server-based system designed to reduce customer support costs for Indigo airline during weather-related flight delays. The airline operates a major hub in Mumbai with over 5,000 daily flights and faces peak support demand, long wait times, customer dissatisfaction, and high operational costs during delays.

### Key Innovations

- **Mood-Aware Communication**: Adapts tone based on passenger sentiment (frustrated, concerned, calm, excited)
- **Proactive Engagement**: Entertainment activities scaled to delay duration (30min to 3+ hours)
- **Personalized Service**: Prioritizes frequent flyer members and provides customized recommendations
- **Seamless Human Handoff**: Full conversation context preservation for specialist escalation
- **Real-Time Intelligence**: Live flight status, rebooking options, and destination insights

### Expected Results

- **60-70% reduction** in routine customer service inquiries through automation
- **Instant response times** for common queries
- **Intelligent routing** of complex cases to human specialists
- **Enhanced customer satisfaction** through personalized, empathetic service

---

## 🏗️ Architecture

The solution uses a microservices architecture with **six specialized MCP servers** coordinated by a main orchestrator:

```
┌─────────────────────────────────────────────────────────────┐
│                   Main MCP Orchestrator                      │
│                  (FastMCP Server - Python)                   │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│Authentication│    │   Flight     │    │    Mood      │
│   Server     │    │ Information  │    │  Analysis    │
│              │    │   Server     │    │   Server     │
└──────────────┘    └──────────────┘    └──────────────┘
        │                     │                     │
        ▼                     ▼                     ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ Engagement/  │    │ Itinerary/   │    │    Human     │
│   Games      │    │    Food      │    │    Agent     │
│   Server     │    │   Server     │    │   Transfer   │
└──────────────┘    └──────────────┘    └──────────────┘
```

### 1. **Authentication Server**
- Secure passenger login and session management
- PNR/email/frequent flyer number authentication
- JWT token generation
- Passenger profile retrieval

### 2. **Flight Information Server**
- Real-time flight status and delay information
- Gate details and terminal navigation
- Alternative flight options for rebooking
- Connection impact analysis
- Weather delay notifications

### 3. **Mood Analysis Server**
- Sentiment detection using VADER and TextBlob
- LLM-powered emotional intelligence analysis
- Communication tone recommendations
- Escalation trigger detection
- Sentiment trend tracking

### 4. **Engagement/Games Server**
- Delay-appropriate entertainment activities
- Interactive games, trivia, and quizzes
- Destination virtual tours
- Relaxation and mindfulness exercises
- Airport exploration suggestions

### 5. **Itinerary/Food Server**
- Airport restaurant recommendations
- Destination dining guides
- Attraction and activity planning
- Personalized itinerary generation
- Dietary restriction handling

### 6. **Human Agent Transfer Server**
- Context-aware escalation to specialists
- Complete conversation history preservation
- Priority queue management
- Passenger profile and sentiment handoff
- Intelligent routing based on issue complexity

---

## 🚀 Quick Start

### Prerequisites

- **Python**: 3.9 or higher
- **PostgreSQL**: 12+ with pgvector extension
- **Redis**: 6+ (optional, for caching)
- **LLM API**: OpenAI, Azure OpenAI, or Anthropic API key

### Installation

1. **Clone the Repository**

```bash
cd /path/to/your/workspace
git clone <repository-url>
cd airline-delays-mcp-server
```

2. **Create Virtual Environment**

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. **Install Dependencies**

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

4. **Setup Database**

```sql
-- Connect to PostgreSQL
psql -U postgres

-- Create database
CREATE DATABASE airline_delays_db;

-- Connect to database
\c airline_delays_db

-- Enable pgvector extension (if using vector operations)
CREATE EXTENSION IF NOT EXISTS vector;
```

5. **Configure Environment**

Create a `.env` file (copy from `env.example`):

```bash
cp env.example .env
```

Edit `.env` with your configuration:

```env
# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=airline_delays_db

# OpenAI (or use Azure/Anthropic)
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4-turbo-preview

# Server
PORT=3003
TRANSPORT=httpStream
ENVIRONMENT=development
```

6. **Initialize Database Schema**

```bash
python -c "import asyncio; from src.config.database import init_database; asyncio.run(init_database())"
```

7. **Run the Server**

```bash
python run.py
```

The server will start on `http://localhost:3003/mcp`

---

## 💻 Usage

### Available Tools

The MCP server exposes 6 tools that can be called by AI assistants:

#### 1. `authenticate_passenger`

Authenticate a passenger and create a session.

```json
{
  "pnr": "ABC123",
  "last_name": "Smith",
  "email": "smith@example.com"
}
```

#### 2. `get_flight_information`

Get real-time flight status and rebooking options.

```json
{
  "flight_number": "6E-123",
  "passenger_id": "P12345",
  "include_alternatives": true
}
```

#### 3. `analyze_mood`

Analyze passenger sentiment and get communication recommendations.

```json
{
  "session_id": "session_abc123",
  "message": "This delay is completely unacceptable!",
  "analyze_trend": true
}
```

#### 4. `suggest_engagement`

Suggest entertainment activities for delayed passengers.

```json
{
  "delay_minutes": 120,
  "passenger_mood": "frustrated",
  "destination": "DEL",
  "activity_type": "any"
}
```

#### 5. `recommend_services`

Recommend airport/destination dining and activities.

```json
{
  "service_type": "airport_food",
  "airport_code": "BOM",
  "dietary_restrictions": ["vegetarian"],
  "budget": "moderate"
}
```

#### 6. `transfer_to_human`

Transfer to human agent with full context.

```json
{
  "session_id": "session_abc123",
  "reason": "high_frustration",
  "urgency": "high",
  "summary": "Passenger frustrated with long delay and missed connection"
}
```

---

## 📁 Project Structure

```
airline-delays-mcp-server/
├── src/
│   ├── config/
│   │   ├── __init__.py
│   │   ├── environment.py      # Environment variable management
│   │   ├── database.py         # PostgreSQL connection pool
│   │   └── llm.py              # LLM client (OpenAI/Azure/Anthropic)
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── authentication.py   # Authentication Server
│   │   ├── flight_information.py  # Flight Information Server
│   │   ├── mood_analysis.py    # Mood Analysis Server
│   │   ├── engagement_games.py # Engagement/Games Server
│   │   ├── itinerary_food.py   # Itinerary/Food Server
│   │   └── human_handoff.py    # Human Agent Transfer Server
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── logger.py           # Structured logging
│   │   └── helpers.py          # Utility functions
│   ├── interfaces/
│   │   └── __init__.py         # Type definitions
│   ├── __init__.py
│   └── server.py               # Main MCP server orchestrator
├── docs/
│   └── ARCHITECTURE.md         # Detailed architecture documentation
├── tests/
│   └── (test files)
├── .env                        # Environment configuration (create from env.example)
├── env.example                 # Example environment configuration
├── requirements.txt            # Python dependencies
├── run.py                      # Server startup script
├── Dockerfile                  # Docker container definition
├── docker-compose.yml          # Docker Compose configuration
└── README.md                   # This file
```

---

## 🔧 Configuration

### Environment Variables

See `env.example` for all available configuration options.

Key variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | 3003 |
| `TRANSPORT` | Transport type (stdio/httpStream) | httpStream |
| `DB_HOST` | PostgreSQL host | localhost |
| `OPENAI_API_KEY` | OpenAI API key | - |
| `MOOD_FRUSTRATION_THRESHOLD` | Frustration threshold for escalation | 0.6 |
| `DELAY_GAME_THRESHOLD_MINUTES` | Min delay for games | 30 |
| `FREQUENT_FLYER_MIN_FLIGHTS` | Min flights for FF status | 10 |

### Feature Flags

Enable/disable features via environment:

```env
ENABLE_MOOD_ANALYSIS=true
ENABLE_GAMES=true
ENABLE_FOOD_RECOMMENDATIONS=true
ENABLE_HUMAN_HANDOFF=true
```

---

## 🐳 Docker Deployment

### Build Docker Image

```bash
docker build -t airline-delays-mcp-server .
```

### Run with Docker Compose

```bash
docker-compose up -d
```

This starts:
- MCP Server (port 3003)
- PostgreSQL database
- Redis cache

### Stop Services

```bash
docker-compose down
```

---

## 🧪 Testing

Run tests:

```bash
pytest tests/ -v
```

Run with coverage:

```bash
pytest tests/ --cov=src --cov-report=html
```

---

## 📊 Monitoring & Observability

### Logging

The server uses structured JSON logging. Set log level via:

```env
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FORMAT=json # json or text
```

### Metrics

Key metrics tracked:
- Tool execution times
- Sentiment scores and trends
- Escalation rates
- Response times
- Database query performance

---

## 🔐 Security

- **JWT Authentication**: Secure session management
- **Input Sanitization**: XSS and injection prevention
- **Rate Limiting**: Prevent abuse (configure via environment)
- **Database SSL**: Encrypted connections to database
- **API Key Management**: Secure credential storage

---

## 🎯 Use Cases

### 1. Weather Delay Scenario

**Passenger**: "My flight is delayed. What's happening?"

**System Flow**:
1. ✅ Authenticate passenger (Authentication Server)
2. ✅ Get flight status (Flight Information Server)
3. ✅ Analyze mood (Mood Analysis Server)
4. ✅ Provide alternatives and rebooking options
5. ✅ Suggest activities if long delay (Engagement Server)
6. ✅ Recommend airport dining (Itinerary/Food Server)

### 2. Frustrated Passenger Escalation

**Passenger**: "This is unacceptable! I demand to speak to a manager!"

**System Flow**:
1. ✅ Detect high frustration (Mood Analysis Server)
2. ✅ Attempt to de-escalate with empathetic response
3. ✅ Offer compensation/alternatives
4. ✅ If frustration persists → Transfer to human (Human Handoff Server)
5. ✅ Agent receives full context, no repetition needed

### 3. Multi-Hour Delay

**Delay**: 3+ hours

**System Actions**:
1. ✅ Proactive engagement with entertainment options
2. ✅ Destination planning assistance
3. ✅ Airport restaurant recommendations
4. ✅ Meal voucher information
5. ✅ Regular status updates
6. ✅ Hotel arrangements if needed

---

## 🤝 Integration

### Claude Desktop Integration

Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "airline-delays": {
      "command": "python",
      "args": ["/path/to/airline-delays-mcp-server/run.py"],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}
```

### API Integration

For HTTP integration:

```python
import requests

response = requests.post(
    "http://localhost:3003/mcp",
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "get_flight_information",
            "arguments": {
                "flight_number": "6E-123"
            }
        }
    }
)

print(response.json())
```

---

## 📚 Additional Documentation

- [**Architecture Guide**](docs/ARCHITECTURE.md) - Detailed system architecture
- [**API Reference**](docs/API.md) - Complete API documentation
- [**Deployment Guide**](docs/DEPLOYMENT.md) - Production deployment
- [**Troubleshooting**](docs/TROUBLESHOOTING.md) - Common issues and solutions

---

## 🛣️ Roadmap

- [ ] Multi-language support (Hindi, regional languages)
- [ ] Voice integration for phone-based support
- [ ] Mobile app integration
- [ ] Advanced analytics dashboard
- [ ] ML-powered delay prediction
- [ ] Integration with more airlines
- [ ] Automated compensation processing

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details

---

## 👥 Contributors

- Development Team
- Airline Operations Team
- Customer Service Specialists

---

## 📞 Support

For issues and questions:
- **GitHub Issues**: [Create an issue](https://github.com/your-org/airline-delays-mcp-server/issues)
- **Email**: support@example.com
- **Documentation**: [Full docs](https://docs.example.com)

---

## 🙏 Acknowledgments

Built with:
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [OpenAI API](https://openai.com/) - LLM capabilities
- [TextBlob](https://textblob.readthedocs.io/) - Sentiment analysis
- [VADER Sentiment](https://github.com/cjhutto/vaderSentiment) - Social media sentiment
- [PostgreSQL](https://www.postgresql.org/) - Database
- [asyncpg](https://github.com/MagicStack/asyncpg) - Async PostgreSQL driver

---

**Made with ❤️ for better customer experiences during travel disruptions**