first commit
This commit is contained in:
douboer
410
DEVELOPMENT_GUIDE.md
Normal file
410
DEVELOPMENT_GUIDE.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# 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调试指南
|
||||
|
||||
---
|
||||
|
||||
**祝您使用愉快！** 🚀
|
||||
Reference in New Issue
Block a user