267 lines
6.6 KiB
Markdown
267 lines
6.6 KiB
Markdown
````markdown
|
||
# MCP Vue 客户端
|
||
|
||
> **版本：1.0.0** | 基础版本 + 最新改进
|
||
|
||
基于 **Vue 3** 和 **MCP 协议**构建的现代化 MCP 客户端界面，支持HTTP和SSE双传输协议。
|
||
|
||
## 🎉 最新改进（开发中）
|
||
|
||
- ✅ **完善的服务器管理** - 编辑功能完全可用，表单数据正确填充
|
||
- ✅ **可靠的连接功能** - HTTP/SSE双协议支持，自动URL转换
|
||
- ✅ **自动重连机制** - 页面刷新自动恢复连接状态
|
||
- ✅ **改进的用户体验** - 美观界面，实时状态显示，详细错误提示
|
||
|
||
📖 **改进详情**: 查看 [CHANGELOG.md](./CHANGELOG.md)
|
||
📚 **使用指南**: 查看 [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md)
|
||
|
||
## ✨ 核心特性
|
||
|
||
- 🎨 **美观界面** - 基于 Naive UI 的现代化设计
|
||
- 🔧 **双协议支持** - HTTP 和 SSE 传输模式
|
||
- 🔄 **自动重连** - 页面刷新后自动恢复连接状态
|
||
- ⚡ **实时状态** - 连接状态实时监控和显示
|
||
- <20> **完整管理** - 服务器配置、编辑、测试一体化
|
||
- 📱 **响应式设计** - 适配桌面和移动设备
|
||
|
||
## 🏗️ 项目架构
|
||
|
||
```
|
||
mcp-client-vue/
|
||
├── src/ # 后端服务
|
||
│ ├── server/ # Express + Socket.IO 服务器
|
||
│ │ ├── index.ts # 主服务器入口
|
||
│ │ ├── MCPManager.ts # 基于 SmartMCPClient 的服务器管理
|
||
│ │ └── LLMService.ts # OpenAI 集成服务
|
||
│ └── types/ # TypeScript 类型定义
|
||
├── web/ # Vue 3 前端
|
||
│ ├── src/
|
||
│ │ ├── components/ # Vue 组件
|
||
│ │ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── views/ # 页面视图
|
||
│ │ └── types/ # 前端类型
|
||
│ └── package.json # 前端依赖
|
||
└── package.json # 后端依赖
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cd mcp-client-vue/web
|
||
npm install
|
||
```
|
||
|
||
### 2. 启动开发服务器
|
||
|
||
```bash
|
||
# 默认端口 5173
|
||
npm run dev
|
||
|
||
# 或指定端口
|
||
npx vite --port 5174
|
||
```
|
||
|
||
### 3. 访问应用
|
||
|
||
- 🌐 **前端界面**: http://localhost:5173
|
||
|
||
### 4. 配置MCP服务器
|
||
|
||
#### HTTP服务器示例
|
||
```
|
||
名称: XHS HTTP Server
|
||
类型: http
|
||
URL: http://localhost:3100/mcp
|
||
描述: HTTP传输模式
|
||
```
|
||
|
||
#### SSE服务器示例
|
||
```
|
||
名称: XHS SSE Server
|
||
类型: sse
|
||
URL: http://localhost:3200/sse
|
||
描述: SSE传输模式
|
||
```
|
||
|
||
## 🎯 主要功能
|
||
|
||
### 服务器管理
|
||
- ✅ 添加/编辑/删除 MCP 服务器
|
||
- ✅ 支持 HTTP 和 SSE 传输协议
|
||
- ✅ 实时连接状态监控
|
||
- ✅ 连接测试功能
|
||
- ✅ 自动重连机制
|
||
|
||
### 传输协议
|
||
- 🔌 **HTTP模式** - 标准HTTP请求/响应，使用`/mcp`端点
|
||
- 📡 **SSE模式** - Server-Sent Events长连接，使用`/sse`端点
|
||
- 🔄 **自动转换** - 地址自动转换（0.0.0.0 → localhost）
|
||
|
||
### 工具管理
|
||
- ✅ 动态展示服务器工具
|
||
- ✅ 工具详情和参数配置
|
||
- ✅ 工具启用/禁用控制
|
||
- ✅ 工具调用和结果显示
|
||
|
||
### 配置管理
|
||
- <20> **本地存储** - 配置持久化到localStorage
|
||
- 🔄 **状态恢复** - 页面刷新自动恢复连接
|
||
- 📝 **环境变量** - 支持环境变量配置
|
||
|
||
## 🔗 与现有项目集成
|
||
|
||
### 使用您的 SmartMCPClient
|
||
|
||
```typescript
|
||
// 项目已集成您的 SmartMCPClient
|
||
import { SmartMCPClient } from '../../../dist/smart-client.js';
|
||
|
||
// MCPManager 基于您的客户端构建
|
||
const client = new SmartMCPClient({
|
||
name: 'MCP-Client-Vue',
|
||
version: '1.0.0'
|
||
});
|
||
|
||
// 支持 HTTP 和 WebSocket
|
||
await client.connectHTTP('http://localhost:3100/mcp');
|
||
```
|
||
|
||
### 连接 xhslogin 服务器
|
||
|
||
```bash
|
||
# 确保 xhslogin 服务器运行
|
||
cd /path/to/xhslogin
|
||
./runmcp.sh http
|
||
|
||
# 在界面中添加服务器
|
||
# 名称: XHS Login Server
|
||
# URL: http://localhost:3100/mcp
|
||
# 类型: HTTP
|
||
```
|
||
|
||
## 📝 开发指南
|
||
|
||
### 添加新组件
|
||
|
||
```bash
|
||
# 创建新的 Vue 组件
|
||
touch web/src/components/MyComponent.vue
|
||
|
||
# 创建新的页面视图
|
||
touch web/src/views/MyView.vue
|
||
```
|
||
|
||
### 扩展 API
|
||
|
||
```typescript
|
||
// 在 src/server/index.ts 中添加新路由
|
||
app.get('/api/my-endpoint', async (req, res) => {
|
||
// 实现逻辑
|
||
});
|
||
```
|
||
|
||
### 状态管理
|
||
|
||
```typescript
|
||
// 使用 Pinia 创建新 store
|
||
// web/src/stores/myStore.ts
|
||
export const useMyStore = defineStore('my-store', () => {
|
||
// 状态和逻辑
|
||
});
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 启动项目
|
||
npm run dev
|
||
|
||
# 测试与 xhslogin 服务器连接
|
||
# 1. 启动 xhslogin 服务器
|
||
# 2. 在界面中添加服务器配置
|
||
# 3. 测试工具调用和资源读取
|
||
```
|
||
|
||
## 🛠️ 技术栈
|
||
|
||
### 前端框架
|
||
- **Vue 3.4.15** - Composition API，响应式设计
|
||
- **TypeScript 5.3.3** - 类型安全
|
||
- **Naive UI 2.43.1** - 美观的组件库
|
||
- **Pinia 2.1.7** - 状态管理
|
||
- **Vite 7.1.9** - 快速构建工具
|
||
|
||
### MCP协议
|
||
- **HTTP传输** - JSON-RPC over HTTP
|
||
- **SSE传输** - Server-Sent Events
|
||
- **自定义客户端** - 原生实现MCP协议
|
||
|
||
### 开发工具
|
||
- **vue-tsc 2.0.6** - Vue TypeScript编译
|
||
- **unplugin** - 自动导入和组件注册
|
||
|
||
## 🎨 界面设计
|
||
|
||
界面完全参考您提供的截图设计：
|
||
|
||
- 📋 **服务器卡片** - 清晰的信息展示
|
||
- 🔀 **分类标签** - 工具、资源、提示分类
|
||
- 🎛️ **开关控制** - 启用/禁用功能
|
||
- 📝 **动态表单** - 根据工具模式生成参数表单
|
||
- 🎯 **实时状态** - 连接状态可视化
|
||
|
||
## 📚 文档
|
||
|
||
- 📋 [CHANGELOG.md](./CHANGELOG.md) - 更新日志
|
||
- 📚 [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md) - 开发使用指南
|
||
- <20> [CURRENT_STATUS.md](./CURRENT_STATUS.md) - 当前状态概览
|
||
- 🎯 [IMPROVEMENTS.md](./IMPROVEMENTS.md) - 改进详细说明
|
||
- <20>️ [DOCS_INDEX.md](./DOCS_INDEX.md) - 文档索引
|
||
|
||
## <20>📈 下一步计划
|
||
|
||
- [ ] 修复所有TypeScript类型错误
|
||
- [ ] 添加工具调用历史记录
|
||
- [ ] 实现资源管理功能
|
||
- [ ] 添加提示词（Prompts）管理
|
||
- [ ] 配置文件导入/导出
|
||
- [ ] 添加性能监控面板
|
||
- [ ] 支持WebSocket传输协议
|
||
|
||
## ❓ 常见问题
|
||
|
||
### 连接问题
|
||
|
||
**Q: HTTP服务器返回406错误？**
|
||
A: 已修复。确保使用最新代码。
|
||
|
||
**Q: SSE服务器返回404错误？**
|
||
A: 检查URL是否包含`/sse`路径，例如：`http://localhost:3200/sse`
|
||
|
||
**Q: 页面刷新后服务器显示未连接？**
|
||
A: 已新增自动重连功能，会自动恢复连接状态。
|
||
|
||
### UI问题
|
||
|
||
**Q: 编辑按钮点击无响应？**
|
||
A: 已修复。清除浏览器缓存后刷新页面。
|
||
|
||
**Q: 模态框显示空白页面？**
|
||
A: 已修复。组件高度已调整为min-height。
|
||
|
||
查看更多问题解答：[DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md#常见问题)
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
**MCP Client Vue v1.0.0 - 功能完善、稳定可靠的MCP协议客户端** 🚀
|
||
```` |