使用说明

快速入门指南

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集成：

配置您的AI客户端 （选择一个）：
- 克劳德桌面 → See PROJECT_WALKTROUGH.md-克劳德桌面集成
- Gemini CLI → See 项目_WALKTROUGH.md-谷歌双子座集成
- Codex CLI → See temp_docs/CODEX_CONFIG.md
测试一下：
- 打开你的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)    │ <───────────────────── │ (index.js)    │
└─────────────┘         stdout         └───────────────┘
                                              │
                                              ▼
                                        ┌─────────────┐
                                        │ database.js │
                                        │ (functions) │
                                        └─────────────┘

流程：

AI客户端通过stdin发送请求
MCP服务器处理请求
调用业务逻辑函数
通过stdout返回格式化的响应

了解更多： 看 PROJECT_WALKTROUGH.md-带标准实施的MCP 详细说明

关键概念

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

了解更多： 看 PROJECT_WALKTROUGH.md-创建MCP工具关于工具的工作原理

Web应用程序功能

航班搜索

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

航班显示

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

订票系统

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

电子邮件确认

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

预定管理

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

漂亮的设计

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

状态持久性演示

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

试试这个流程：

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!

这表明：

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

了解更多： 看 PROJECT_WALKSTHROugh.md-API函数和业务逻辑了解状态管理是如何工作的

后续步骤

了解更多

项目名称_WLKthrough.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-测试集成
检查一下 dist/index.js 存在于之后 npm run build
验证AI客户端配置路径是否为绝对路径

需要帮助？

检查 PROJECT_WALKTROUGH.md-故障排除章节
查看PROJECT_WALKTROUGH.md中的AI客户端配置指南

快速参考

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