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

Related MCP server: Agentic MCP Itinerary

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

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