Quick Start Guide

New to MCP? Start here! This guide gets you up and running in minutes.
For detailed documentation, see 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)
• 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
• 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

# 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

# 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

npm run api

Terminal 2: Start Web App

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
   • Gemini CLI → See 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

npm start

Terminal 2: Web App

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

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 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 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 to understand how state management works

---

Next Steps

Learn More

• 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
• Check that dist/index.js exists after npm run build
• Verify AI client configuration path is absolute

Need help?

• Check 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

---

Ready to dive deeper? → PROJECT_WALKTHROUGH.md has everything you need!