# Amadeus Flight Availabilities MCP App

An MCP (Model Context Protocol) App with interactive dashboard UI that integrates with the Amadeus Flight Availabilities Search API. This application allows users to search for available flights and view seat availability in real-time.

## Current Status

| Component | Status |
|-----------|--------|
| Project Setup | ✅ Complete |
| MCP Server | ✅ Complete |
| React Dashboard | ✅ Complete |
| shadcn/ui Components | ✅ Complete |
| Single-file Build | ✅ Complete |
| Server-side API Proxy | ✅ Complete (Security fix) |
| Standalone Mode | ✅ Complete |
| Claude Code CLI Support | ✅ Complete |
| Claude Desktop Support | ✅ Complete |

## What It Does

The Amadeus Flight Availabilities Search API answers the question: **"How many seats are still available on this flight?"**

This MCP App provides:
- Interactive flight search form with IATA airport codes
- Real-time seat availability display per booking class
- Filter options by cabin class, airline, and number of stops
- Visual availability indicators (available, limited, full/waitlist)

## Features

- **Flight Search**: Search by origin/destination IATA codes and date
- **Seat Availability**: View available seats per booking class (Economy, Business, First)
- **Flight Details**: Carrier info, aircraft type, departure/arrival times, terminals
- **Filtering**: Filter by cabin class, airlines, and connection preferences
- **Interactive Dashboard**: Rich UI with expandable flight details

## Tech Stack

| Category | Technology |
|----------|------------|
| Framework | React 18 + TypeScript |
| UI Library | shadcn/ui + Tailwind CSS |
| MCP SDK | `@modelcontextprotocol/sdk` + `@modelcontextprotocol/ext-apps` |
| Bundler | Vite + `vite-plugin-singlefile` |
| Validation | Zod |
| Server | Express (HTTP transport) |
| Package Manager | bun |

## Prerequisites

- [Node.js](https://nodejs.org/) 18+
- [bun](https://bun.sh/) runtime
- Amadeus API credentials (Client ID and Client Secret)
- Claude Code CLI (recommended) OR Claude Desktop

## Quick Start

### 1. Clone and Install

```bash
# Navigate to project directory
cd amadeus-flights-mcp-app

# Install dependencies
bun install
```

### 2. Configure Environment

Copy `.env.example` to `.env` and add your Amadeus credentials:

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

Edit `.env`:
```env
AMADEUS_CLIENT_ID=your_api_key
AMADEUS_CLIENT_SECRET=your_api_secret
```

### 3. Build the Project

```bash
bun run build
```

### 4. Start the Server

```bash
bun run dev
```

The server will be available at `http://localhost:3001`.

## Claude Integration

### Option 1: Claude Code CLI (Recommended)

Claude Code CLI supports HTTP transport, which provides the best experience for interactive MCP Apps with UI.

```bash
# Add MCP server to Claude Code
claude mcp add amadeus-flights http://localhost:3001/mcp
```

Then ask Claude:
> "Search for flights from JFK to LHR on March 15, 2025"

### Option 2: Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "amadeus-flights": {
      "command": "bun",
      "args": ["PATH/TO/amadeus-flights-mcp-app/main.ts", "--stdio"],
      "env": {
        "AMADEUS_CLIENT_ID": "your_client_id",
        "AMADEUS_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

### Option 3: Standalone Mode (No Claude)

Simply open `http://localhost:3001` in your browser. The React dashboard works without Claude.

## Usage

### Standalone Mode (Browser)

1. **Start the server**: `bun run dev`
2. **Open browser**: Go to `http://localhost:3001`
3. **Use the dashboard**: Search for flights using the form
4. **API status**: Check if Amadeus API is configured via the status indicator

### Claude Mode

1. **Start the server**: `bun run dev` (for Claude Code) or `bun run serve` (for Claude Desktop)
2. **Open Claude** (Code CLI or Desktop)
3. **Ask Claude**: "Search for flights from JFK to LHR on 2024-12-15"
4. **View results**: Interactive dashboard shows available flights with seat counts
5. **Filter**: Use filters to narrow down by cabin class, carrier, or stops

## Which Claude to Use?

| Feature | Claude Code CLI | Claude Desktop |
|---------|-----------------|----------------|
| HTTP Transport | ✅ Yes | ❌ No (stdio only) |
| Interactive UI | ✅ Renders properly | ⚠️ May not render |
| Setup Complexity | Lower | Higher (path required) |

**Recommendation**: Use Claude Code CLI for the best experience with interactive MCP Apps.

## Security

**Important**: Amadeus API credentials are **never** exposed to the browser.

- Credentials are stored server-side in environment variables
- Frontend calls the `/api/flights` proxy endpoint
- The server handles OAuth2 authentication internally
- Built bundle contains no credentials (verified with `grep`)

### Security Features

| Feature | Description |
|---------|-------------|
| CORS | Restricted to localhost origins (configurable via `ALLOWED_ORIGINS`) |
| Security Headers | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection |
| Request Limit | 10KB max for API request body |
| Credentials | Never embedded in browser bundle |

## API Reference

- **Amadeus API**: [Flight Availabilities Search](https://developers.amadeus.com/self-service/category/air/api-doc/flight-availabilities-search)
- **Authentication**: OAuth 2.0 with client credentials
- **Test Environment**: `https://test.api.amadeus.com/v1`

## Project Structure

```
amadeus-flights-mcp-app/
├── src/
│   ├── components/           # React components
│   │   ├── ui/              # shadcn/ui components
│   │   └── Flight*.tsx      # Flight search & results
│   ├── lib/                 # Utilities
│   │   ├── amadeus.ts       # API client (server-side)
│   │   └── utils.ts         # Helper functions
│   ├── types/               # TypeScript types
│   └── styles/              # CSS
├── server.ts                # MCP server
├── main.ts                  # Entry point (Express server + API proxy)
├── dist/                    # Built frontend
├── docs/                    # Documentation
└── .env                     # Environment variables (not committed)
```

## Documentation

- [Getting Started](./docs/getting-started.md) - Detailed setup guide
- [Claude Setup](./docs/claudesetup.md) - Connect to Claude Code CLI or Claude Desktop
- [API Reference](./docs/api-reference.md) - Amadeus API documentation
- [Architecture](./docs/architecture.md) - System design
- [User Guide](./docs/guide.md) - Usage instructions

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history.

## License

MIT

## Resources

- [MCP Apps Documentation](https://modelcontextprotocol.io/extensions/apps)
- [Amadeus Developers Portal](https://developers.amadeus.com/)
- [shadcn/ui](https://ui.shadcn.com/)