Airline Flight Delays Server

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

Python Version FastMCP 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

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

2. Create Virtual Environment

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

3. Install Dependencies

pip install -r requirements.txt

4. Setup Database

-- 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):

cp env.example .env

Edit .env with your configuration:

# 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

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

7. Run the Server

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.

{
  "pnr": "ABC123",
  "last_name": "Smith",
  "email": "[email protected]"
}

2. get_flight_information

Get real-time flight status and rebooking options.

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

3. analyze_mood

Analyze passenger sentiment and get communication recommendations.

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

4. suggest_engagement

Suggest entertainment activities for delayed passengers.

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

5. recommend_services

Recommend airport/destination dining and activities.

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

6. transfer_to_human

Transfer to human agent with full context.

{
  "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:

ENABLE_MOOD_ANALYSIS=true
ENABLE_GAMES=true
ENABLE_FOOD_RECOMMENDATIONS=true
ENABLE_HUMAN_HANDOFF=true

---

🐳 Docker Deployment

Build Docker Image

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

Run with Docker Compose

docker-compose up -d

This starts:

• MCP Server (port 3003)
• PostgreSQL database
• Redis cache

Stop Services

docker-compose down

---

🧪 Testing

Run tests:

pytest tests/ -v

Run with coverage:

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

---

📊 Monitoring & Observability

Logging

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

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):

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

API Integration

For HTTP integration:

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 - Detailed system architecture
• API Reference - Complete API documentation
• Deployment Guide - Production deployment
• Troubleshooting - 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 file for details

---

👥 Contributors

• Development Team
• Airline Operations Team
• Customer Service Specialists

---

📞 Support

For issues and questions:

• GitHub Issues: Create an issue
• Email: [email protected]
• Documentation: Full docs

---

🙏 Acknowledgments

Built with:

• FastMCP - MCP server framework
• OpenAI API - LLM capabilities
• TextBlob - Sentiment analysis
• VADER Sentiment - Social media sentiment
• PostgreSQL - Database
• asyncpg - Async PostgreSQL driver

---

Made with ❤️ for better customer experiences during travel disruptions