411 lines
8.3 KiB
Markdown
411 lines
8.3 KiB
Markdown
# MCP Client Vue 开发指南
|
||
|
||
## 📋 目录
|
||
|
||
- [当前状态](#当前状态)
|
||
- [快速开始](#快速开始)
|
||
- [功能详解](#功能详解)
|
||
- [配置指南](#配置指南)
|
||
- [常见问题](#常见问题)
|
||
- [故障排除](#故障排除)
|
||
|
||
## 🎉 当前状态
|
||
|
||
基于v1.0.0的重要稳定性和功能改进，主要完成了以下工作：
|
||
|
||
### ✨ 主要改进
|
||
|
||
1. **完善的服务器管理** 🖥️
|
||
- 编辑功能完全可用
|
||
- 表单数据正确填充
|
||
- 模态框显示正常
|
||
|
||
2. **可靠的连接功能** 🔗
|
||
- HTTP和SSE双协议支持
|
||
- 自动URL转换
|
||
- 智能连接测试
|
||
|
||
3. **自动重连机制** 🔄
|
||
- 页面刷新自动恢复连接
|
||
- 并行重连多个服务器
|
||
- 错误容错处理
|
||
|
||
4. **改进的用户体验** 🎨
|
||
- 美观的界面设计
|
||
- 实时状态显示
|
||
- 详细的错误提示
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 启动开发服务器
|
||
|
||
```bash
|
||
# 进入web目录
|
||
cd mcp-client-vue/web
|
||
|
||
# 启动开发服务器（默认端口5173）
|
||
npm run dev
|
||
|
||
# 或指定端口
|
||
npx vite --port 5174
|
||
```
|
||
|
||
### 2. 访问应用
|
||
|
||
打开浏览器访问：`http://localhost:5173`
|
||
|
||
### 3. 添加MCP服务器
|
||
|
||
#### 添加HTTP服务器
|
||
|
||
1. 点击"添加服务器"按钮
|
||
2. 填写配置信息：
|
||
```
|
||
名称: XHS HTTP Server
|
||
类型: http
|
||
URL: http://localhost:3100
|
||
描述: XHS登录服务器（HTTP模式）
|
||
```
|
||
3. 点击"保存"
|
||
4. 点击"连接"按钮
|
||
|
||
#### 添加SSE服务器
|
||
|
||
1. 点击"添加服务器"按钮
|
||
2. 填写配置信息：
|
||
```
|
||
名称: XHS SSE Server
|
||
类型: sse
|
||
URL: http://localhost:3200/sse
|
||
描述: XHS登录服务器（SSE模式）
|
||
```
|
||
3. 点击"保存"
|
||
4. 点击"连接"按钮
|
||
|
||
## 📖 功能详解
|
||
|
||
### 服务器管理
|
||
|
||
#### 添加服务器
|
||
|
||
支持两种传输协议：
|
||
|
||
**HTTP模式**
|
||
- 使用标准的HTTP请求/响应
|
||
- 端点：`/mcp`
|
||
- 适合短连接、无状态场景
|
||
|
||
**SSE模式**
|
||
- 使用Server-Sent Events长连接
|
||
- 端点：`/sse`
|
||
- 适合需要服务器推送的场景
|
||
|
||
#### 编辑服务器
|
||
|
||
1. 点击服务器卡片上的"编辑"按钮
|
||
2. 在弹出的详情页面中修改配置
|
||
3. 配置工具、提示、资源的启用状态
|
||
4. 点击"保存"保存更改
|
||
|
||
#### 连接测试
|
||
|
||
点击服务器卡片上的"测试"图标：
|
||
|
||
- **HTTP服务器**：发送MCP初始化请求
|
||
- **SSE服务器**：建立EventSource连接测试
|
||
|
||
#### 删除服务器
|
||
|
||
1. 如果服务器已连接，先点击"断开"
|
||
2. 点击"删除"按钮
|
||
3. 确认删除操作
|
||
|
||
### 自动重连功能
|
||
|
||
**工作原理：**
|
||
|
||
1. 页面加载时，从localStorage读取服务器配置
|
||
2. 识别之前已连接的服务器
|
||
3. 自动并行重连所有服务器
|
||
4. 显示连接结果
|
||
|
||
**日志输出：**
|
||
|
||
```
|
||
🚀 MCPSettings 组件已挂载，开始自动重连...
|
||
🔄 开始自动重连...
|
||
📝 从存储加载的服务器: 2 个
|
||
🔍 发现之前已连接的服务器: ["xhs-http", "xhs-sse"]
|
||
📡 开始重连服务器: xhs-http
|
||
📡 开始重连服务器: xhs-sse
|
||
✅ 服务器重连成功: xhs-http
|
||
✅ 服务器重连成功: xhs-sse
|
||
✅ 自动重连完成，成功: 2, 失败: 0
|
||
```
|
||
|
||
### 连接状态管理
|
||
|
||
**状态类型：**
|
||
|
||
- 🔴 **未连接** (disconnected)
|
||
- 🟡 **连接中** (connecting)
|
||
- 🟢 **已连接** (connected)
|
||
- ❌ **连接失败** (error)
|
||
|
||
**状态持久化：**
|
||
|
||
- 连接状态保存在localStorage
|
||
- 页面刷新后自动恢复
|
||
- 断开连接会清除状态
|
||
|
||
## ⚙️ 配置指南
|
||
|
||
### URL配置规则
|
||
|
||
#### HTTP服务器
|
||
|
||
**支持的格式：**
|
||
|
||
```
|
||
✅ http://localhost:3100
|
||
✅ http://localhost:3100/mcp
|
||
✅ http://0.0.0.0:3100
|
||
✅ http://127.0.0.1:3100
|
||
```
|
||
|
||
**自动处理：**
|
||
|
||
- 自动添加`/mcp`路径（如果没有）
|
||
- 自动转换`0.0.0.0` → `localhost`
|
||
- 自动转换`127.0.0.1` → `localhost`
|
||
|
||
**最终请求URL：**
|
||
|
||
```
|
||
输入: http://localhost:3100
|
||
实际: http://localhost:3100/mcp
|
||
|
||
输入: http://0.0.0.0:3100
|
||
实际: http://localhost:3100/mcp
|
||
```
|
||
|
||
#### SSE服务器
|
||
|
||
**支持的格式：**
|
||
|
||
```
|
||
✅ http://localhost:3200/sse
|
||
✅ http://0.0.0.0:3200/sse
|
||
✅ http://127.0.0.1:3200/sse
|
||
```
|
||
|
||
**注意事项：**
|
||
|
||
- ⚠️ 必须包含`/sse`路径
|
||
- ⚠️ 不会自动添加路径
|
||
- ✅ 会自动转换地址
|
||
|
||
**最终请求URL：**
|
||
|
||
```
|
||
输入: http://localhost:3200/sse
|
||
实际: http://localhost:3200/sse
|
||
|
||
输入: http://0.0.0.0:3200/sse
|
||
实际: http://localhost:3200/sse
|
||
```
|
||
|
||
### 环境变量配置
|
||
|
||
在服务器配置中，可以添加环境变量：
|
||
|
||
```json
|
||
{
|
||
"env": {
|
||
"API_KEY": "your-api-key",
|
||
"DEBUG": "true",
|
||
"TIMEOUT": "30000"
|
||
}
|
||
}
|
||
```
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q1: 为什么编辑按钮点击没反应？
|
||
|
||
**A:** 这个问题已在v1.3.5中修复。如果仍然遇到问题：
|
||
|
||
1. 清除浏览器缓存
|
||
2. 刷新页面
|
||
3. 检查浏览器控制台是否有错误
|
||
|
||
### Q2: 为什么模态框显示空白？
|
||
|
||
**A:** 这个问题已在v1.3.5中修复。组件高度已改为`min-height: 500px`。
|
||
|
||
### Q3: 为什么表单字段不显示数据？
|
||
|
||
**A:** 这个问题已在v1.3.5中修复。watch监听器现在使用`deep: true`选项。
|
||
|
||
### Q4: 为什么页面刷新后服务器显示未连接？
|
||
|
||
**A:** v1.3.5新增了自动重连功能，页面加载时会自动恢复连接状态。
|
||
|
||
### Q5: HTTP服务器连接失败，提示406错误？
|
||
|
||
**A:** 这个问题已在v1.3.5中修复。所有HTTP请求现在包含正确的Accept头：
|
||
|
||
```
|
||
Accept: application/json, text/event-stream
|
||
```
|
||
|
||
### Q6: SSE服务器连接失败，提示404错误？
|
||
|
||
**A:** 检查URL是否包含`/sse`路径：
|
||
|
||
```
|
||
❌ 错误: http://localhost:3200
|
||
❌ 错误: http://localhost:3200/mcp
|
||
✅ 正确: http://localhost:3200/sse
|
||
```
|
||
|
||
### Q7: 为什么使用0.0.0.0地址连接失败？
|
||
|
||
**A:** 浏览器无法直接访问`0.0.0.0`地址。v1.3.5会自动转换：
|
||
|
||
```
|
||
0.0.0.0 → localhost
|
||
127.0.0.1 → localhost
|
||
```
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 连接问题
|
||
|
||
#### 症状：连接测试失败
|
||
|
||
**检查清单：**
|
||
|
||
1. ✅ MCP服务器是否正在运行？
|
||
```bash
|
||
# 检查HTTP服务器（端口3100）
|
||
lsof -ti:3100
|
||
|
||
# 检查SSE服务器（端口3200）
|
||
lsof -ti:3200
|
||
```
|
||
|
||
2. ✅ URL配置是否正确？
|
||
- HTTP: 包含`/mcp`路径或让系统自动添加
|
||
- SSE: 必须包含`/sse`路径
|
||
|
||
3. ✅ 是否有CORS问题？
|
||
- 打开浏览器开发者工具
|
||
- 查看Network标签
|
||
- 检查是否有CORS错误
|
||
|
||
4. ✅ 服务器日志有错误吗？
|
||
- 查看MCP服务器的控制台输出
|
||
- 检查是否有404、406等错误
|
||
|
||
#### 症状：自动重连失败
|
||
|
||
**检查清单：**
|
||
|
||
1. ✅ 打开浏览器控制台，查看日志
|
||
2. ✅ 检查localStorage中是否有服务器配置
|
||
```javascript
|
||
// 在控制台执行
|
||
console.log(localStorage.getItem('mcp_servers'))
|
||
```
|
||
3. ✅ 确认服务器之前的连接状态是"connected"
|
||
|
||
### UI问题
|
||
|
||
#### 症状：编辑按钮无响应
|
||
|
||
**解决方案：**
|
||
|
||
1. 清除浏览器缓存
|
||
2. 刷新页面（Ctrl/Cmd + Shift + R）
|
||
3. 检查控制台是否有JavaScript错误
|
||
|
||
#### 症状：模态框空白
|
||
|
||
**解决方案：**
|
||
|
||
1. 确保已更新到v1.3.5
|
||
2. 检查组件样式是否正确加载
|
||
3. 查看控制台是否有CSS错误
|
||
|
||
### 构建问题
|
||
|
||
#### 症状：TypeScript编译错误
|
||
|
||
**解决方案：**
|
||
|
||
使用跳过类型检查的构建命令：
|
||
|
||
```bash
|
||
npm run build:skip-check
|
||
```
|
||
|
||
或者正常构建（会有警告但不影响功能）：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
## 📊 调试技巧
|
||
|
||
### 查看详细日志
|
||
|
||
所有关键操作都有emoji日志：
|
||
|
||
- 🔍 调试信息
|
||
- ✅ 成功操作
|
||
- ❌ 错误信息
|
||
- 🔄 转换/处理
|
||
- 📡 网络请求
|
||
|
||
### 检查网络请求
|
||
|
||
1. 打开开发者工具（F12）
|
||
2. 切换到Network标签
|
||
3. 筛选XHR/Fetch请求
|
||
4. 查看请求头、响应内容
|
||
|
||
### 检查存储状态
|
||
|
||
```javascript
|
||
// 查看服务器配置
|
||
console.log(localStorage.getItem('mcp_servers'))
|
||
|
||
// 查看连接状态
|
||
console.log(localStorage.getItem('mcp_connections'))
|
||
```
|
||
|
||
## 🎯 最佳实践
|
||
|
||
1. **服务器命名**：使用有意义的名称，便于识别
|
||
2. **URL格式**：使用localhost而不是0.0.0.0
|
||
3. **定期测试**：使用连接测试功能验证服务器状态
|
||
4. **查看日志**：遇到问题先查看浏览器控制台
|
||
5. **保存配置**：修改后记得点击保存按钮
|
||
|
||
## 📞 获取帮助
|
||
|
||
如果遇到问题：
|
||
|
||
1. 查看本文档的[常见问题](#常见问题)章节
|
||
2. 查看浏览器控制台的错误信息
|
||
3. 查看MCP服务器的日志输出
|
||
4. 查阅项目其他文档：
|
||
- `CHANGELOG.md` - 版本更新记录
|
||
- `README.md` - 项目总览
|
||
- `debug-ui.md` - UI调试指南
|
||
|
||
---
|
||
|
||
**祝您使用愉快！** 🚀
|