Skip to content

About

This project provides a AI client for Airline-Web-App project.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

14 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

SE4458 Assignment 2 — AI-Powered Flight Assistant

A full-stack conversational flight assistant built with a Model Context Protocol (MCP) server, a Claude-powered agent backend, and a React chat frontend. Users can search for flights, book tickets, and check in using natural language.

Demo Video

https://youtu.be/PsQQJ_7k9Ww


Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         User (Browser)                              │
│                    React + Tailwind Chat UI                         │
│                   (S3 + CloudFront / localhost)                     │
└────────────────────────────┬────────────────────────────────────────┘
                             │ WebSocket (wss://)
┌────────────────────────────▼────────────────────────────────────────┐
│                       Agent Backend                                 │
│               Node.js + Express + WebSocket Server                  │
│                   Claude Sonnet 4 (Anthropic API)                   │
│                   (AWS EC2 / localhost:8080)                        │
└────────────────────────────┬────────────────────────────────────────┘
                             │ Tool calls (in-process)
┌────────────────────────────▼────────────────────────────────────────┐
│                         MCP Server                                  │
│              @modelcontextprotocol/sdk (StdioTransport)             │
│         Tools: query_flight · book_flight · check_in                │
└────────────────────────────┬────────────────────────────────────────┘
                             │ HTTPS + JWT Auth
┌────────────────────────────▼────────────────────────────────────────┐
│                  Flight API Gateway (AWS App Runner)                │
│         https://ipfcssutkw.eu-west-1.awsapprunner.com              │
└─────────────────────────────────────────────────────────────────────┘

Request Flow

  1. User types a message in the chat UI
  2. Frontend sends { type: "chat", message, history } over WebSocket
  3. Agent backend passes the message + history to Claude (with tool definitions)
  4. Claude decides to call a tool (e.g., query_flight)
  5. Backend executes the tool → MCP server → authenticated API call to Flight API
  6. Tool result is returned to Claude, which formulates a natural language response
  7. Backend sends { type: "message", role: "assistant", content } back over WebSocket
  8. Frontend renders the assistant's reply in the chat

Repository Structure

Assigment2/
├── mcp-server/               # Model Context Protocol server
│   ├── src/
│   │   ├── index.ts          # MCP server entry — tool definitions
│   │   └── apiClient.ts      # Axios instance with JWT auth interceptors
│   ├── package.json
│   ├── tsconfig.json
│   └── .env
│
├── agent-backend/            # WebSocket server + Claude agent loop
│   ├── src/
│   │   ├── index.ts          # HTTP health-check + WebSocket server
│   │   ├── agent.ts          # Claude agentic loop with tool execution
│   │   └── tools.ts          # Tool implementations (HTTP calls to Flight API)
│   ├── Dockerfile
│   ├── package.json
│   ├── tsconfig.json
│   └── .env
│
└── frontend/                 # React chat UI
    ├── src/
    │   ├── App.tsx
    │   ├── types.ts
    │   ├── components/
    │   │   ├── ChatWindow.tsx
    │   │   ├── MessageBubble.tsx
    │   │   ├── ToolCallBadge.tsx
    │   │   └── InputBar.tsx
    │   └── hooks/
    │       └── useWebSocket.ts
    ├── vite.config.ts
    ├── tailwind.config.js
    ├── .env                   # Development: ws://localhost:8080
    ├── .env.production        # Production: ws://<EC2-IP>:8080
    └── package.json

Tech Stack

Layer Technology
Frontend React 19, Vite 8, TypeScript, Tailwind CSS v3
Agent Backend Node.js, TypeScript, ws WebSocket library
AI Model Claude Sonnet 4 (claude-sonnet-4-20250514) via Anthropic SDK
MCP Server @modelcontextprotocol/sdk with StdioServerTransport
HTTP Client Axios with request/response interceptors
Auth JWT (auto-login + 401 retry)
Containerization Docker (node:20-alpine)
Deployment AWS EC2 (backend), AWS S3 + CloudFront (frontend)

MCP Tools

query_flight

Search for available flights between two airports.

Parameter Type Required Description
airportFrom string Yes Departure airport code (e.g. IST)
airportTo string Yes Arrival airport code (e.g. FRA)
dateFrom string Yes Start date YYYY-MM-DD
dateTo string Yes End date YYYY-MM-DD
numberOfPeople number Yes Passenger count
tripType string No ONE_WAY (default) or ROUND_TRIP
page number No Zero-indexed page (default 0)

Maps to: GET /api/v1/flights


book_flight

Book seats on a specific flight for one or more passengers.

Parameter Type Required Description
flightNumber string Yes Flight identifier (e.g. TK1523)
date string Yes Flight date YYYY-MM-DD
passengerNames string[] Yes Array of full passenger names

Maps to: POST /api/v1/tickets


check_in

Check in a passenger using their flight number, date, and name.

Parameter Type Required Description
flightNumber string Yes Flight identifier
date string Yes Flight date YYYY-MM-DD
passengerName string Yes Full passenger name

Maps to: POST /api/v1/checkin


Environment Variables

mcp-server/.env

API_GATEWAY_BASE_URL=https://ipfcssutkw.eu-west-1.awsapprunner.com
API_USERNAME=claude
API_PASSWORD=claude123

agent-backend/.env

ANTHROPIC_API_KEY=<your-anthropic-api-key>
PORT=8080
API_GATEWAY_BASE_URL=https://ipfcssutkw.eu-west-1.awsapprunner.com
API_USERNAME=claude
API_PASSWORD=claude123

frontend/.env (development)

VITE_WS_URL=ws://localhost:8080

frontend/.env.production

VITE_WS_URL=ws://<your-ec2-ip>:8080

Local Development

Prerequisites

  • Node.js 20+
  • npm 9+

1. Install dependencies

cd mcp-server && npm install
cd ../agent-backend && npm install
cd ../frontend && npm install

2. Start the agent backend

cd agent-backend
npm run dev
# Server starts on http://localhost:8080
# WebSocket available at ws://localhost:8080

The agent backend imports the MCP server's apiClient directly at build time — no separate MCP server process needed.

3. Start the frontend

cd frontend
npm run dev
# Open http://localhost:5173

Example Conversations

User:  Find me flights from IST to FRA on May 10
Agent: ⚙ Searching flights...
       Here are the available flights from IST to FRA on May 10:
       • TK1523 — Duration: 195 min — Available seats: 12
       • ...

User:  Book TK1523 on May 10 for John Doe
Agent: ⚙ Booking flight...
       Booking confirmed!
       • Ticket #TK1523-001 — John Doe

User:  Check in John Doe for TK1523 on May 10
Agent: ⚙ Checking in...
       Check-in successful!
       Passenger: John Doe — Seat: 14A

Building for Production

Agent Backend (Docker)

# From the repo root
docker build -f agent-backend/Dockerfile -t agent-backend .
docker run -p 8080:8080 --env-file agent-backend/.env agent-backend

The Dockerfile copies both mcp-server/ and agent-backend/ into the image because the backend imports shared code from the MCP server.

Frontend (Static)

cd frontend
npm run build
# Output in frontend/dist/

Deploy to S3:

aws s3 sync dist/ s3://<your-bucket-name> --delete

AWS Deployment

Agent Backend on EC2

  1. Launch an EC2 instance (Amazon Linux 2 / Ubuntu, t3.micro or larger)
  2. Install Docker: sudo yum install docker -y && sudo service docker start
  3. Copy the repo to the instance (or pull from ECR/DockerHub)
  4. Build and run the container:
    docker build -f agent-backend/Dockerfile -t agent-backend .
    docker run -d -p 8080:8080 --env-file agent-backend/.env agent-backend
  5. Open port 8080 in the EC2 security group

Frontend on S3 + CloudFront

  1. Create S3 bucket with static website hosting enabled
  2. Set frontend/.env.production with the EC2 WebSocket URL
  3. Build and upload:
    npm run build
    aws s3 sync dist/ s3://<bucket> --delete
    aws s3 website s3://<bucket> --index-document index.html --error-document index.html
  4. Create a CloudFront distribution pointing to the S3 website endpoint
    • Default root object: index.html
    • Custom error response: 404 → /index.html (required for SPA)

Note: CloudFront does NOT proxy WebSocket connections. The frontend connects directly to the EC2 WebSocket URL — CloudFront only serves the static files.


Authentication

The Flight API uses JWT. The apiClient in mcp-server/src/apiClient.ts handles this transparently:

  1. On the first API call, it logs in via POST /api/v1/auth/login
  2. The JWT is stored in memory and attached as Authorization: Bearer <token> on all requests
  3. If a 401 is received, it re-authenticates once and retries the original request automatically

No per-user auth is needed — a single shared service account is used for all tool calls.


WebSocket Protocol

Client → Server

{
  "type": "chat",
  "message": "Find flights from IST to FRA",
  "history": [
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ]
}

Server → Client (assistant reply)

{
  "type": "message",
  "role": "assistant",
  "content": "Here are the available flights..."
}

Server → Client (tool call indicator)

{
  "type": "tool_call",
  "tool": "query_flight",
  "input": { "airportFrom": "IST", "airportTo": "FRA", ... }
}

Server → Client (error)

{
  "type": "error",
  "message": "Something went wrong..."
}

Key Design Decisions

  • MCP server as a library, not a process: The agent backend imports apiClient directly from mcp-server/src/ rather than spawning a separate stdio process. This simplifies deployment while preserving the MCP tool abstractions.
  • Stateless sessions: Conversation history is maintained in-memory per WebSocket connection and resets on reconnect. No database needed.
  • Client-side history: The frontend sends its full conversation history with every message, allowing the backend to remain stateless across connections.
  • Exponential backoff reconnect: The frontend WebSocket hook retries up to 5 times with delays of 1s, 2s, 4s, 8s, 16s before giving up.
  • Single shared JWT: All API calls share one service-account JWT token in memory. On 401, it refreshes automatically without any user interaction.

About

This project provides a AI client for Airline-Web-App project.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages