ts-travel-mcp-server

martinoyovo/ts-travel-mcp-server

3.3

If you are the rightful owner of ts-travel-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Travel MCP Server is a Model Context Protocol server designed to facilitate flight search and booking operations for AI assistants.

Tools
8
Resources
0
Prompts
0

Quick Start Guide

New to MCP? Start here! This guide gets you up and running in minutes.
For detailed documentation, see .

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

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

Next Steps

Learn More

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

Need help?

  • Check section
  • Review AI client configuration guides in PROJECT_WALKTHROUGH.md

Quick Reference

TaskCommand
Install dependenciesnpm install
Build backendnpm run build
Start MCP servernpm start
Run web appnpm run dev:web
View docsOpen

Ready to dive deeper? → has everything you need!