gavin/map-client-vue
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 3 Wiki Activity
Files
e5f69b3aef8f3c659cb2dd2369ea6869cd95c826
map-client-vue/DEVELOPMENT_GUIDE.md
douboer d93bc02772 first commit
2025-10-14 14:18:20 +08:00

8.3 KiB
Raw Blame History

MCP Client Vue 开发指南

📋 目录

🎉 当前状态

基于v1.0.0的重要稳定性和功能改进，主要完成了以下工作：

✨ 主要改进

  1. 完善的服务器管理 🖥️

    • 编辑功能完全可用
    • 表单数据正确填充
    • 模态框显示正常

  2. 可靠的连接功能 🔗

    • HTTP和SSE双协议支持
    • 自动URL转换
    • 智能连接测试

  3. 自动重连机制 🔄

    • 页面刷新自动恢复连接
    • 并行重连多个服务器
    • 错误容错处理

  4. 改进的用户体验 🎨

    • 美观的界面设计
    • 实时状态显示
    • 详细的错误提示

🚀 快速开始

1. 启动开发服务器

# 进入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

环境变量配置

在服务器配置中，可以添加环境变量：

{
  "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服务器是否正在运行？

    # 检查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中是否有服务器配置 
    // 在控制台执行
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编译错误

解决方案：

使用跳过类型检查的构建命令：

npm run build:skip-check

或者正常构建（会有警告但不影响功能）：

npm run build

📊 调试技巧

查看详细日志

所有关键操作都有emoji日志：

  • 🔍 调试信息
  • ✅ 成功操作
  • ❌ 错误信息
  • 🔄 转换/处理
  • 📡 网络请求

检查网络请求

  1. 打开开发者工具（F12）
  2. 切换到Network标签
  3. 筛选XHR/Fetch请求
  4. 查看请求头、响应内容

检查存储状态

// 查看服务器配置
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调试指南

祝您使用愉快！ 🚀