快速入门指南

新接触MCP？ 从这里开始！本指南将在几分钟内让你上手。
如需详细文档，请参阅 PROJECT_WALKTHROUGH.md。

我们正在构建什么

一个完整的全栈旅行预订应用程序，包括：

后端（MCP服务器）

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

前端（Web应用）

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

文档

• 综合指南（参见 PROJECT_WALKTHROUGH.md）
• 所有AI客户端的设置指南
• 深入代码讲解
• 架构解释

先决条件

在开始之前，请确保你拥有：

• Node.js（v18或更高版本） - 下载
• npm（随Node.js一起提供）
• Git（可选，用于克隆）

推荐但非必需：

• 已配置的AI客户端（Claude桌面版、Codex CLI或Gemini CLI）
• 对TypeScript/JavaScript的基本熟悉

项目结构

travel-mcp-server/
│
├── BACKEND MCP SERVER
│   ├── index.ts              # 主MCP服务器（工具定义及处理器）
│   ├── database.ts           # 业务逻辑及数据管理
│   ├── package.json          # 依赖项及脚本
│   ├── tsconfig.json         # TypeScript配置
│   ├── api-server.js         # 可选的独立API服务器
│   │
│   ├── data/                 # 模拟数据文件
│   │   ├── flights.json      # 航班数据
│   │   └── bookings.json     # 预订记录
│   │
│   └── dist/                 # 构建输出（由`npm run build`生成）
│       ├── index.js          # 编译后的MCP服务器（供AI客户端使用）
│       ├── database.js       # 编译后的数据库函数
│       └── data/             # 复制的数据文件
│           ├── flights.json
│           └── bookings.json
│
└── FRONTEND WEB APP
    ├── src/                  # React应用程序
    │   ├── App.jsx           # 主React组件
    │   ├── main.jsx          # React入口点
    │   ├── App.css           # 样式
    │   ├── FlightSearch.jsx  # 搜索界面
    │   ├── FlightList.jsx    # 航班显示
    │   ├── BookingForm.jsx   # 预订表单
    │   ├── BookingsList.jsx  # 预订显示
    │   └── MockEmailModal.jsx # 邮件确认模态框
    │
    ├── index.html            # HTML入口点
    └── vite.config.js        # Vite构建配置

开始

第一步：安装依赖项

# 导航到项目目录
cd travel-mcp-server

# 安装所有依赖项
npm install

这会做什么： 安装TypeScript、MCP SDK、React、Vite以及所有所需包。

第二步：构建后端

# 将TypeScript编译为JavaScript
npm run build

这会做什么： 将index.ts和database.ts编译成dist/index.js和dist/database.js，供AI客户端使用。

预期输出：

✓ 构建成功

第三步：选择你的设置路径

你有三种选项（选择适合你的需求）：

快速启动：仅Web应用

适用于学习和演示 - 不需要设置AI客户端！

终端1：启动API服务器

npm run api

终端2：启动Web应用

npm run dev:web

在http://localhost:3000打开 - 你可以开始了！

AI集成：仅MCP服务器

适用于AI CLI集成：

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

   • Claude桌面版 → 查看 PROJECT_WALKTHROUGH.md - Claude桌面版集成
   • Gemini CLI → 查看 PROJECT_WALKTHROUGH.md - Google Gemini集成
   • Codex CLI → 查看 temp_docs/CODEX_CONFIG.md

2. 测试它：

   • 打开你的AI客户端
   • 尝试："从纽约飞往洛杉矶的航班搜索"

全栈：Web应用+MCP服务器

适用于完整演示：

终端1：MCP服务器

npm start

终端2：Web应用

npm run dev:web

终端3：AI客户端

• 打开Claude桌面版、Codex CLI或Gemini CLI
• Web UI和AI客户端看到相同的数据！

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

了解项目

它是如何工作的

┌─────────────┐         stdin          ┌───────────────┐
│ AI客户端   │ ─────────────────────> │ MCP服务器    │
│ (Claude)   │ <───────────────────── │ (index.js)    │
└─────────────┘         stdout         └───────────────┘
                                              │
                                              ▼
                                        ┌─────────────┐
                                        │ database.js │
                                        │ (函数)      │
                                        └─────────────┘

流程：

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

了解更多： 请参阅 PROJECT_WALKTHROUGH.md - MCP与Stdio实现以获得详细解释

关键概念

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

了解更多： 请参阅 PROJECT_WALKTHROUGH.md - 创建MCP工具以了解工具的工作原理

Web应用功能

航班搜索

• 按出发/到达城市搜索航班
• 快速演示按钮（纽约→洛杉矶）
• 结果按价格排序
• 实时可用性

航班显示

• 具有航空公司品牌的漂亮航班卡片
• 显示航空公司、时间、时长、停靠站、价格
• 可用性指示器（剩余座位数）
• 快速“立即预订”按钮

预订系统

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

邮件确认

• 邮件预览模态框
• 显示完整的预订详情
• 专业邮件模板
• 可关闭模态框

预订管理

• 在一处查看所有预订
• 随时取消
• 取消时自动释放座位
• 所有视图的实时更新

美丽的设计

• 现代渐变标题
• 响应式卡片
• 平滑动画
• 状态颜色编码（已确认/待定/已取消）
• 移动友好型响应式设计

状态持久性演示

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

尝试这个流程：

1. 搜索航班
   → FL004显示22个可用座位

2. 预订FL004
   → 后端减少可用性
   → FL004现在有21个座位

3. 再次搜索
   → FL004仍然显示21个座位
   → 数据更改被保存！

4. 取消预订
   → FL004恢复到22个座位
   → 座位被释放！

这展示了什么：

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

了解更多： 请参阅 PROJECT_WALKTHROUGH.md - API函数和业务逻辑以理解状态管理如何工作

---

下一步

学习更多

• PROJECT_WALKTHROUGH.md - 完整文档包含：
  • 如何创建MCP工具
  • 业务逻辑实现
  • 函数依赖关系
  • Stdio通信细节
  • 完整的AI客户端集成指南

探索代码

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

故障排除

Web应用无法启动？

• 检查Node.js版本：node --version（需要v18+）
• 删除node_modules和package-lock.json，然后npm install

MCP服务器不起作用？

• 查看 PROJECT_WALKTHROUGH.md - 测试集成
• 确保npm run build后存在dist/index.js
• 验证AI客户端配置路径是绝对路径

需要帮助？

• 查看 PROJECT_WALKTHROUGH.md - 故障排除部分
• 查看PROJECT_WALKTHROUGH.md中的AI客户端配置指南

---

快速参考

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

---

准备好深入了吗？ → PROJECT_WALKTHROUGH.md包含了你需要的一切！