# Quick Start Guide

> **New to MCP?** Start here! This guide gets you up and running in minutes.  
> For detailed documentation, see [PROJECT_WALKTHROUGH.md](PROJECT_WALKTHROUGH.md).

## What We're Building

A **complete full-stack travel booking application** with:

### Backend (MCP Server)
- TypeScript MCP server with 8 tools
- Mock flight database with real-time state
- Booking system with state persistence
- Multi-client support (Claude, Codex, Gemini)

### Frontend (Web App)
- Beautiful React UI with modern design
- Flight search interface
- Booking management dashboard
- Email confirmation preview
- Real-time state updates
- Fully responsive design

### Documentation
- Comprehensive guides (see [PROJECT_WALKTHROUGH.md](PROJECT_WALKTHROUGH.md))
- Setup guides for all AI clients
- In-depth code walkthroughs
- Architecture explanations

## Prerequisites

Before you begin, make sure you have:
- **Node.js** (v18 or higher) - [Download](https://nodejs.org/)
- **npm** (comes with Node.js)
- **Git** (optional, for cloning)

**Optional but recommended:**
- An AI client configured (Claude Desktop, Codex CLI, or Gemini CLI)
- Basic familiarity with TypeScript/JavaScript

## ️ Project Structure

```
travel-mcp-server/
│
├── BACKEND MCP SERVER
│   ├── index.ts              # Main MCP server (tool definitions & handlers)
│   ├── database.ts           # Business logic & data management
│   ├── package.json          # Dependencies & scripts
│   ├── tsconfig.json         # TypeScript configuration
│   ├── api-server.js         # Standalone API server (optional)
│   │
│   ├── data/                 # Mock data files
│   │   ├── flights.json      # Flight data
│   │   └── bookings.json     # Booking records
│   │
│   └── dist/                 # Build output (generated by `npm run build`)
│       ├── index.js          # Compiled MCP server (used by AI clients)
│       ├── database.js       # Compiled database functions
│       └── data/             # Copied data files
│           ├── flights.json
│           └── bookings.json
│
└── FRONTEND WEB APP
    ├── src/                  # React application
    │   ├── App.jsx           # Main React component
    │   ├── main.jsx          # React entry point
    │   ├── App.css           # Styles
    │   ├── FlightSearch.jsx  # Search interface
    │   ├── FlightList.jsx    # Flight display
    │   ├── BookingForm.jsx   # Booking form
    │   ├── BookingsList.jsx  # Bookings display
    │   └── MockEmailModal.jsx # Email confirmation modal
    │
    ├── index.html            # HTML entry point
    └── vite.config.js        # Vite build configuration
```

## Getting Started

### Step 1: Install Dependencies

```bash
# Navigate to project directory
cd travel-mcp-server

# Install all dependencies
npm install
```

**What this does:** Installs TypeScript, MCP SDK, React, Vite, and all required packages.

### Step 2: Build the Backend

```bash
# Compile TypeScript to JavaScript
npm run build
```

**What this does:** Compiles `index.ts` and `database.ts` into `dist/index.js` and `dist/database.js` that AI clients will use.

**Expected output:**
```
✓ Built successfully
```

### Step 3: Choose Your Setup Path

You have three options (choose what fits your needs):

#### Quick Start: Web App Only
Perfect for learning and demos - no AI client setup needed!

**Terminal 1: Start API Server**
```bash
npm run api
```

**Terminal 2: Start Web App**
```bash
npm run dev:web
```

Opens at `http://localhost:3000` - you're ready to go!

#### AI Integration: MCP Server Only
Perfect for AI CLI integration:

1. **Configure your AI client** (choose one):
   - **Claude Desktop** → See [PROJECT_WALKTHROUGH.md - Claude Desktop Integration](PROJECT_WALKTHROUGH.md#claude-desktop-integration)
   - **Gemini CLI** → See [PROJECT_WALKTHROUGH.md - Google Gemini Integration](PROJECT_WALKTHROUGH.md#google-gemini-integration)
   - **Codex CLI** → See `temp_docs/CODEX_CONFIG.md`

2. **Test it:**
   - Open your AI client
   - Try: "Search for flights from New York to Los Angeles"

#### Full Stack: Both Web App + MCP Server
Perfect for complete demonstrations:

**Terminal 1: MCP Server**
```bash
npm start
```

**Terminal 2: Web App**
```bash
npm run dev:web
```

**Terminal 3: AI Client**
- Open Claude Desktop, Codex CLI, or Gemini CLI
- Both web UI and AI client see the same data!

> **Tip:** For detailed setup instructions, see [PROJECT_WALKTHROUGH.md - Integrating with AI Clients](PROJECT_WALKTHROUGH.md#integrating-with-ai-clients)

## Understanding the Project

### How It Works

```
┌─────────────┐         stdin          ┌───────────────┐
│ AI Client   │ ─────────────────────> │ MCP Server    │
│ (Claude)    │ <───────────────────── │ (index.js)    │
└─────────────┘         stdout         └───────────────┘
                                              │
                                              ▼
                                        ┌─────────────┐
                                        │ database.js │
                                        │ (functions) │
                                        └─────────────┘
```

**The Flow:**
1. AI client sends request via stdin
2. MCP server processes request
3. Calls business logic functions
4. Returns formatted response via stdout

> **Learn more:** See [PROJECT_WALKTHROUGH.md - MCP with Stdio Implementation](PROJECT_WALKTHROUGH.md#mcp-with-stdio-implementation) for detailed explanation

### Key Concepts

- **MCP Tools**: 8 tools that AI clients can call (search, book, cancel, etc.)
- **State Persistence**: Bookings and seat availability persist across sessions
- **Business Logic**: All logic in `database.ts`, tools in `index.ts`
- **Mock Data**: JSON files in `data/` directory

> **Learn more:** See [PROJECT_WALKTHROUGH.md - Creating MCP Tools](PROJECT_WALKTHROUGH.md#creating-mcp-tools) for how tools work


## Web App Features

### Flight Search
- Search flights by departure/arrival cities
- Quick demo button for NYC → LAX
- Results sorted by price
- Real-time availability

### Flight Display
- Beautiful flight cards with airline branding
- Shows airline, times, duration, stops, price
- Availability indicator (seats remaining)
- Quick "Book Now" button

### Booking System
- Passenger name & email form
- Input validation
- Real-time availability update
- Instant booking confirmation

### Email Confirmations
- Mock email preview modal
- Shows complete booking details
- Professional email template
- Dismissable modal

### Booking Management
- View all bookings in one place
- Cancel anytime
- Seat automatically released on cancel
- Real-time updates across all views

### Beautiful Design
- Modern gradient headers
- Responsive cards
- Smooth animations
- Color-coded status (confirmed/pending/cancelled)
- Mobile-friendly responsive design

## State Persistence Demo

This is the **key teaching moment** - demonstrating real backend state management!

### Try This Flow:

```
1. Search flights
   → FL004 shows 22 seats available

2. Book FL004
   → Backend decreases availability
   → FL004 now has 21 seats

3. Search again
   → FL004 still shows 21 seats
   → Change persisted!

4. Cancel the booking
   → FL004 back to 22 seats
   → Seat released!
```

### What This Demonstrates:

- **Real backend state** - Not just frontend state  
- **Mutations and updates** - Data actually changes  
- **Data consistency** - Same data across all views  
- **Business logic execution** - Rules enforced server-side

> **Learn more:** See [PROJECT_WALKTHROUGH.md - API Functions and Business Logic](PROJECT_WALKTHROUGH.md#api-functions-and-business-logic) to understand how state management works

---

## Next Steps

### Learn More

- **[PROJECT_WALKTHROUGH.md](PROJECT_WALKTHROUGH.md)** - Complete documentation with:
  - How MCP tools are created
  - Business logic implementation
  - Function dependencies
  - Stdio communication details
  - Full AI client integration guides

### Explore the Code

- **`index.ts`** - MCP server and tool definitions
- **`database.ts`** - Business logic and data management
- **`src/`** - React components for the web app

### Troubleshooting

**Web app won't start?**
- Check Node.js version: `node --version` (need v18+)
- Delete `node_modules` and `package-lock.json`, then `npm install`

**MCP server not working?**
- See [PROJECT_WALKTHROUGH.md - Testing the Integration](PROJECT_WALKTHROUGH.md#testing-the-integration)
- Check that `dist/index.js` exists after `npm run build`
- Verify AI client configuration path is absolute

**Need help?**
- Check [PROJECT_WALKTHROUGH.md - Troubleshooting](PROJECT_WALKTHROUGH.md#troubleshooting) section
- Review AI client configuration guides in PROJECT_WALKTHROUGH.md

---

## Quick Reference

| Task | Command |
|------|---------|
| Install dependencies | `npm install` |
| Build backend | `npm run build` |
| Start MCP server | `npm start` |
| Run web app | `npm run dev:web` |
| View docs | Open [PROJECT_WALKTHROUGH.md](PROJECT_WALKTHROUGH.md) |

---

**Ready to dive deeper?** → [PROJECT_WALKTHROUGH.md](PROJECT_WALKTHROUGH.md) has everything you need!