Ts Travel MCP Server

快速入门指南

MCP新手？ 从这里开始！本指南可让您在几分钟内上手。\ 有关详细文档，请参阅 项目名称_WLKthrough.md.

我们正在建造什么

A. 完整的全栈旅行预订应用程序 与：

后端（MCP服务器）

• 带有8个工具的TypeScript MCP服务器
• 具有实时状态的模拟飞行数据库
• 具有状态持久性的预订系统
• 多客户支持（Claude、Codex、Gemini）

前端（Web应用程序）

• 具有现代设计的漂亮React UI
• 航班搜索界面
• 预订管理仪表板
• 电子邮件确认预览
• 实时状态更新
• 完全响应式设计

文档

• 综合指南（参见 项目名称_WLKthrough.md)
• 所有AI客户端的设置指南
• 深入代码演练
• 架构说明

先决条件

在开始之前，请确保您已经：

• Node.js （v18或更高版本）- 下载
• npm （附带Node.js）
• Git （可选，用于克隆）

可选但推荐：

• 已配置AI客户端（Claude Desktop、Codex CLI或Gemini CLI）
• 基本熟悉Types/JavaScript

️ 项目结构

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

入门指南

步骤1：安装依赖项

# Navigate to project directory
cd travel-mcp-server

# Install all dependencies
npm install

这有什么作用： 安装TypeScript、MCP SDK、React、Vite和所有必需的软件包。

第二步：构建后端

# Compile TypeScript to JavaScript
npm run build

这有什么作用： 编译 index.ts 和 database.ts 进入 dist/index.js 和 dist/database.js AI客户端将使用。

预期产量：

✓ Built successfully

步骤3：选择安装路径

您有三个选择（选择适合您需求的选项）：

快速入门：仅限Web应用程序

非常适合学习和演示-无需设置AI客户端！

终端1：启动API服务器

npm run api

终端2：启动Web应用程序

npm run dev:web

开放时间： http://localhost:3000 -你准备好了！

AI集成：仅限MCP服务器

非常适合AI CLI集成：

1. 配置您的AI客户端 （选择一个）：

- 克劳德桌面 → See PROJECT_WALKTROUGH.md-克劳德桌面集成 - Gemini CLI → See 项目_WALKTROUGH.md-谷歌双子座集成 - Codex CLI → See temp_docs/CODEX_CONFIG.md

1. 测试一下：

- 打开你的AI客户端 - 尝试：“搜索从纽约到洛杉矶的航班”

全栈：Web应用程序+MCP服务器

非常适合完整演示：

终端1:MCP服务器

npm start

终端2：Web应用程序

npm run dev:web

终端3:AI客户端

• 打开克劳德桌面、Codex CLI或Gemini CLI
• web UI和AI客户端都看到相同的数据！

提示： 有关详细的设置说明，请参阅 PROJECT_WALKTROUGH.md-与AI客户端集成

了解项目

运作原理

┌─────────────┐         stdin          ┌───────────────┐
│ AI Client   │ ─────────────────────> │ MCP Server    │
│ (Claude)    │  **了解更多：** 看 [PROJECT_WALKTROUGH.md-带标准实施的MCP](PROJECT_WALKTHROUGH.md#mcp-with-stdio-implementation) 详细说明

### 关键概念

- **MCP工具**：AI客户端可以调用的8个工具（搜索、预订、取消等）
- **状态持久性**：预订和座位可用性在会议期间持续存在
- **业务逻辑**：所有逻辑 `database.ts`，工具在 `index.ts`
- **模拟数据**：JSON文件 `data/` 目录

> **了解更多：** 看 [PROJECT_WALKTROUGH.md-创建MCP工具](PROJECT_WALKTHROUGH.md#creating-mcp-tools) 关于工具的工作原理

## Web应用程序功能

### 航班搜索

- 按出发/到达城市搜索航班
- NYC快速演示按钮→ LAX
- 按价格排序的结果
- 实时可用性

### 航班显示

- 带有航空公司品牌的精美航班卡
- 显示航空公司、时间、持续时间、站点、价格
- 可用性指示器（剩余座位）
- 快速“立即预订”按钮

### 订票系统

- 乘客姓名和电子邮件表格
- 输入验证
- 实时可用性更新
- 即时预订确认

### 电子邮件确认

- 模拟电子邮件预览模式
- 显示完整的预订详细信息
- 专业电子邮件模板
- 可解雇模态

### 预定管理

- 在一个地方查看所有预订
- 随时取消
- 取消时座椅自动释放
- 所有视图的实时更新

### 漂亮的设计

- 现代渐变标头
- 响应卡
- 流畅的动画
- 颜色编码状态（已确认/待定/取消）
- 移动友好的响应式设计

## 状态持久性演示

这是 **关键教学时刻** -演示真正的后端状态管理！

### 试试这个流程：

1. Search flights

→ FL004 shows 22 seats available

1. Book FL004

→ Backend decreases availability → FL004 now has 21 seats

1. Search again

→ FL004 still shows 21 seats → Change persisted!

1. Cancel the booking

→ FL004 back to 22 seats → Seat released!

### 这表明：

- **真实后端状态** -不仅仅是前端状态
- **突变和更新** -数据实际发生了变化
- **数据一致性** -所有视图中的数据相同
- **业务逻辑执行** -服务器端执行的规则

> **了解更多：** 看 [PROJECT_WALKSTHROugh.md-API函数和业务逻辑](PROJECT_WALKTHROUGH.md#api-functions-and-business-logic) 了解状态管理是如何工作的

______________________________________________________________________

## 后续步骤

### 了解更多

- **[项目名称_WLKthrough.md](PROJECT_WALKTHROUGH.md)** -完整的文档包括：
  - 如何创建MCP工具
  - 业务逻辑实现
  - 函数依赖
  - 标准通信详细信息
  - 完整的AI客户端集成指南

### 探索代码

- **`index.ts`** -MCP服务器和工具定义
- **`database.ts`** -业务逻辑和数据管理
- **`src/`** -web应用程序的React组件

### 故障排除

**Web应用程序无法启动？**

- 检查Node.js版本： `node --version` （需要v18+）
- 删除 `node_modules` 和 `package-lock.json`那么 `npm install`

**MCP服务器不工作？**

- 看 [PROJECT_WALKTROUGH.md-测试集成](PROJECT_WALKTHROUGH.md#testing-the-integration)
- 检查一下 `dist/index.js` 存在于之后 `npm run build`
- 验证AI客户端配置路径是否为绝对路径

**需要帮助？**

- 检查 [PROJECT_WALKTROUGH.md-故障排除](PROJECT_WALKTHROUGH.md#troubleshooting) 章节
- 查看PROJECT_WALKTROUGH.md中的AI客户端配置指南

______________________________________________________________________

## 快速参考

|任务|命令|
|------|---------|
|安装依赖项| `npm install` |
|构建后端| `npm run build` |
|启动MCP服务器| `npm start` |
|运行web应用程序| `npm run dev:web` |
|查看文档|打开 [项目名称_WLKthrough.md](PROJECT_WALKTHROUGH.md) |

______________________________________________________________________

**准备好潜得更深了吗？** → [项目名称_WLKthrough.md](PROJECT_WALKTHROUGH.md) 有你需要的一切！