使用说明
MCP-UI旅行计划-学习项目
一个需要学习的实践项目 MCP（模型上下文协议） 和 MCP-UI 通过构建旅行计划应用程序。
🎯 学习目标
- 了解MCP及其如何启用AI工具
- 学习MCP-UI创建交互式组件
- 比较基于文本的工具与基于UI的工具
- 构建实例
- 记录优点、缺点和设计影响
📁 项目结构
MCPUITest/
├── server/ # MCP Server (Node.js + TypeScript)
│ ├── src/
│ │ ├── index.ts # MCP server (provides tools)
│ │ ├── bridge-server.ts # HTTP bridge (connects client to MCP)
│ │ └── tools/ # Tool definitions (to be added)
│ ├── build/ # Compiled TypeScript
│ ├── package.json # Server dependencies
│ └── tsconfig.json # Server TypeScript config
├── client/ # Web Client (React + Vite)
│ ├── src/
│ │ ├── App.tsx # React app
│ │ ├── main.tsx # Entry point
│ │ └── *.css # Styles
│ ├── dist/ # Built client (production)
│ ├── package.json # Client dependencies
│ ├── tsconfig.json # Client TypeScript config
│ ├── vite.config.ts # Vite configuration
│ └── index.html # HTML template
└── package.json # Workspace root (npm workspaces)
为什么要分开文件夹？
✅ 明确区分关注点 -服务器和客户端是不同的应用程序 ✅ 独立依赖关系 -每个人都只有自己需要的东西 ✅ 更好的可扩展性 -可以单独部署/版本 ✅ 清洁发展 -没有混合的TypeScript配置 ✅ 行业标准 -带工作区的Monrepo模式
🏗️ 建筑
┌─────────────┐ HTTP ┌──────────────┐ stdio ┌──────────────┐
│ │ ───────────────>│ │ ───────────────>│ │
│ Web Client │ │ Bridge Server│ │ MCP Server │
│ (React) │ <───────────────│ (Express) │ <───────────────│ (Node.js) │
└─────────────┘ └──────────────┘ └──────────────┘
Port 3000 Port 3001 stdio transport
为什么是这种架构？
- MCP服务器 使用stdio（标准输入/输出）进行通信
- web客户端 需要HTTP/WebSocket进行浏览器通信
- 网桥服务器 在HTTP和stdio之间进行转换
🚀 快速开始
先决条件
- Node.js（v18+）
- npm
安装
如果重新开始：
npm install # Installs all workspace dependencies
这使用 npm工作区 从根目录管理服务器和客户端的依赖关系。
运行应用程序
选项1：用一个命令运行所有内容 （推荐）
npm run dev
这将开始：
- 构建服务器
- 启动网桥服务器（端口3001）
- 启动web客户端开发服务器（端口3000）
然后打开： http://localhost:3000
选项2：单独运行组件 （用于调试）
终端1-具有监视模式的服务器：
npm run dev:server --workspace=server
终端2-网桥服务器：
npm run bridge
终端3-Web客户端：
npm run dev:client
🧪 测试设置
- 打开http://localhost:3000
- 输入您的姓名（例如“Sarah”）
- 选择“文本工具（纯MCP）”
- 点击“呼叫工具”
- 查看纯文本响应
现在试试： 6.选择“UI工具（MCP-UI）” 7.点击“呼叫工具” 8.查看带按钮的交互式UI组件
📚 当前工具
1. hello_world （基于文本）
- 简单的MCP工具
- 返回纯文本响应
- 演示基本工具结构
2. hello_world_ui （基于用户界面）
- MCP-UI工具
- 返回交互式HTML组件
- 演示UI资源创建
- 仅显示与文本的差异
🔍 接下来是什么？
第一阶段：了解基本原理
使用此工作设置探索：
- MCP工具的工作原理
- 如何创建UI资源
- 文本和UI响应之间的差异
- 安全模型（沙盒iframe）
第三阶段：构建旅行计划工具
添加真正的功能：
search_destinations-查找旅游目的地get_destination_info-获取详细信息create_itinerary-制定旅行计划
阶段4：添加丰富的UI组件
转化为互动体验：
- 带图像的目的地卡
- 交互式地图
- 日期选择器和表格
- 拖放行程生成器
第5阶段：记录学习
反思：
- 何时使用MCP-UI与文本
- 性能考虑
- 设计图案
- 利弊
🛠️ 开发命令
| 命令 | 描述 |
|---|---|
npm install |
安装所有依赖项（工作区） |
npm run dev |
运行一切（服务器+网桥+客户端） |
npm run build |
构建服务器和客户端 |
npm run build:server |
仅构建服务器 |
npm run build:client |
仅构建客户端 |
npm run bridge |
启动网桥服务器 |
npm run dev:client |
仅启动客户端开发服务器 |
npm run dev:server |
在监视模式下启动服务器 |
npm run start:server |
直接运行MCP服务器（stdio） |
🐛 故障排除
端口已在使用中
# Kill processes on ports
lsof -ti:3000 | xargs kill
lsof -ti:3001 | xargs kill
构建错误
# Clean and rebuild
rm -rf server/build/ client/dist/ node_modules/
npm install
npm run build
网桥服务器无法连接到MCP服务器
请确保您首先构建了服务器：
npm run build:server
工作空间问题
如果出现依赖性错误：
# Reinstall all workspace dependencies
rm -rf node_modules/ server/node_modules/ client/node_modules/
rm package-lock.json
npm install
📖 会话管理
这是一个具有内置可恢复性的多会话学习项目。
Slash命令（克劳德代码）
| 命令 | 描述 |
|---|---|
/resume |
从上次中断的地方继续 |
/status |
显示当前项目状态和进度 |
/update-session |
用当前进度更新会话文档 |
关键文件
| 文件 | 目的 |
|---|---|
ARCHITECTURE.md |
完整的系统架构和信号流 |
LEARNING_PLAN.md |
分阶段学习目标和见解 |
SESSION_RESUME.md |
当前状态和恢复的下一步 |
README.md |
此文件-设置和参考 |
会话之间
结束前：
- 跑
/update-session捕捉进展 - 如果使用git，则提交更改
恢复时：
- 跑
npm install（如果依赖关系发生变化） - 跑
npm run dev启动服务器 - 跑
/resume加载上下文 - 审查
SESSION_RESUME.md接下来的步骤
📖 了解更多
准备好学习了吗？ 从跑步开始 npm run dev 探索Hello World工具！
