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 ``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:

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

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

Understanding the Project

How It Works

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

The Flow:

AI client sends request via stdin
MCP server processes request
Calls business logic functions
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!

ts-travel-mcp-server