Mcpui Travel Planner

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

这将开始：

1. 构建服务器
2. 启动网桥服务器（端口3001）
3. 启动web客户端开发服务器（端口3000）

然后打开： http://localhost:3000

选项2：单独运行组件 （用于调试）

终端1-具有监视模式的服务器：

npm run dev:server --workspace=server

终端2-网桥服务器：

npm run bridge

终端3-Web客户端：

npm run dev:client

🧪 测试设置

1. 打开http://localhost:3000
2. 输入您的姓名（例如“Sarah”）
3. 选择“文本工具（纯MCP）”
4. 点击“呼叫工具”
5. 查看纯文本响应

现在试试： 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与文本
• 性能考虑
• 设计图案
• 利弊

🛠️ 开发命令

🐛 故障排除

端口已在使用中

# 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命令（克劳德代码）

关键文件

会话之间

结束前：

1. 跑 /update-session 捕捉进展
2. 如果使用git，则提交更改

恢复时：

1. 跑 npm install （如果依赖关系发生变化）
2. 跑 npm run dev 启动服务器
3. 跑 /resume 加载上下文
4. 审查 SESSION_RESUME.md 接下来的步骤

📖 了解更多

• MCP文件
• MCP-UI网站
• MCP-UI指南

______________________________________________________________________

准备好学习了吗？ 从跑步开始 npm run dev 探索Hello World工具！