# 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调试指南

---

**祝您使用愉快！** 🚀