363 lines
11 KiB
Markdown
363 lines
11 KiB
Markdown
````markdown
|
||
# MCP Vue 客户端
|
||
|
||
> **版本：2.0.0** | 架构重构版 - 更清晰、更可维护、更高性能
|
||
|
||
基于 **Vue 3** 和 **MCP 协议**构建的现代化 MCP 客户端界面，支持多模型服务、流式对话、MCP 工具调用。
|
||
|
||
## 🎉 v2.0.0 重大更新（2025-10-16）
|
||
|
||
### 🏗️ 架构重构
|
||
- ✅ **服务拆分** - 将 1,147 行单体服务拆分为 5 个独立服务
|
||
- ✅ **单一职责** - MessageService、ConversationService、StreamProcessor、ToolExecutor、ChatOrchestrator
|
||
- ✅ **统一日志** - Logger 系统，支持日志级别和命名空间
|
||
- ✅ **错误处理** - AppError 体系，类型化错误（ValidationError、NetworkError、ServiceError 等）
|
||
- ✅ **性能优化** - 批量输出、上下文限制、性能监控
|
||
|
||
### 🚀 核心改进
|
||
- ✅ **代码可维护性** - 单文件最大行数从 1,147 降至 580（↓49%）
|
||
- ✅ **易于测试** - 每个服务独立可测，支持依赖注入
|
||
- ✅ **更好的性能** - 批量输出减少 60%+ 重渲染，首字延迟监控
|
||
- ✅ **完善文档** - 架构文档、重构报告、API 文档
|
||
|
||
📖 **重构详情**: 查看 [REFACTOR_COMPLETE.md](./REFACTOR_COMPLETE.md)
|
||
📚 **架构文档**: 查看 [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
|
||
📋 **版本说明**: 查看 [release.md](./release.md)
|
||
|
||
## ✨ 核心特性
|
||
|
||
### 聊天功能
|
||
- 💬 **多模型支持** - 阿里通义、火山方舟等多模型服务
|
||
- 🌊 **流式对话** - 实时流式响应，打字机效果
|
||
- 🔧 **MCP 工具调用** - 支持工具链、递归调用
|
||
- 📝 **对话管理** - 创建、编辑、删除、置顶、收藏、归档
|
||
- <20> **持久化** - localStorage 存储，页面刷新保持状态
|
||
|
||
### 架构特性（v2.0）
|
||
- 🏗️ **模块化架构** - 5 个独立服务，单一职责
|
||
- 📊 **统一日志** - Logger 系统，分级管理（DEBUG/INFO/WARN/ERROR）
|
||
- ⚠️ **类型化错误** - AppError 体系，更好的错误处理
|
||
- ⚡ **性能优化** - 批量输出、上下文限制、性能监控
|
||
- 🧪 **易于测试** - 服务解耦，支持单元测试
|
||
|
||
### 用户体验
|
||
- 🎨 **美观界面** - 基于 Naive UI 的现代化设计
|
||
- 📱 **响应式设计** - 适配桌面和移动设备
|
||
- ⚡ **实时状态** - 连接状态、发送状态实时显示
|
||
- 🎯 **快捷操作** - 复制、删除、重新生成消息
|
||
|
||
## 🏗️ 项目架构（v2.0 重构版）
|
||
|
||
```
|
||
mcp-client-vue/
|
||
├── src/ # 后端服务
|
||
│ ├── server/ # Node.js 服务器
|
||
│ │ ├── index.ts # Express 服务器入口
|
||
│ │ ├── MCPManager.ts # MCP 服务器管理
|
||
│ │ └── LLMService.ts # 模型服务集成
|
||
│ └── types/ # 后端类型定义
|
||
├── web/ # Vue 3 前端（重构版）
|
||
│ ├── src/
|
||
│ │ ├── components/ # UI 组件
|
||
│ │ │ ├── Chat/ # 聊天组件
|
||
│ │ │ ├── Settings/ # 设置组件
|
||
│ │ │ └── Common/ # 通用组件
|
||
│ │ ├── services/ # 业务服务层 ⭐ 重构重点
|
||
│ │ │ ├── chat/ # 聊天服务（新架构）
|
||
│ │ │ │ ├── MessageService.ts # 消息 CRUD
|
||
│ │ │ │ ├── ConversationService.ts # 对话管理
|
||
│ │ │ │ ├── StreamProcessor.ts # 流式处理
|
||
│ │ │ │ ├── ToolExecutor.ts # 工具执行
|
||
│ │ │ │ ├── ChatOrchestrator.ts # 协调器
|
||
│ │ │ │ └── index.ts # 导出
|
||
│ │ │ ├── modelServiceManager.ts
|
||
│ │ │ └── MCPClientService.ts
|
||
│ │ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── utils/ # 工具函数 ⭐ 新增
|
||
│ │ │ ├── logger.ts # 统一日志系统
|
||
│ │ │ ├── error.ts # 错误处理体系
|
||
│ │ │ └── index.ts # 导出
|
||
│ │ ├── types/ # 类型定义
|
||
│ │ └── views/ # 页面视图
|
||
│ └── package.json
|
||
├── docs/ # 文档 ⭐ 新增
|
||
│ └── ARCHITECTURE.md # 架构文档
|
||
└── package.json
|
||
```
|
||
|
||
### 服务层架构（v2.0 核心改进）
|
||
|
||
```
|
||
ChatOrchestrator (协调器)
|
||
├── MessageService (消息 CRUD - 245 行)
|
||
├── ConversationService (对话管理 - 145 行)
|
||
├── StreamProcessor (流式处理 - 305 行)
|
||
└── ToolExecutor (工具执行 - 285 行)
|
||
|
||
工具层：
|
||
├── Logger (统一日志 - 138 行)
|
||
└── AppError + ErrorHandler (错误处理 - 200 行)
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 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
|
||
描述: 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) - 文档索引
|
||
|
||
## 📈 v2.0 架构重构成果
|
||
|
||
### 代码质量提升
|
||
| 指标 | v1.0 | v2.0 | 改进 |
|
||
|------|------|------|------|
|
||
| 单文件最大行数 | 1,147 | 580 | ↓ 49% |
|
||
| 服务职责数量 | 6+ | 1 | 单一职责 |
|
||
| 日志系统 | console.log | Logger 类 | 分级管理 |
|
||
| 错误处理 | 不统一 | AppError 体系 | 类型化 |
|
||
| 可测试性 | 困难 | 容易 | 独立测试 |
|
||
|
||
### 性能优化
|
||
- ✅ **批量输出** - 减少 60%+ UI 重渲染
|
||
- ✅ **上下文限制** - 限制最近 20 条消息，减少 token 消耗
|
||
- ✅ **性能监控** - 追踪首字延迟、总耗时、chunk 数
|
||
|
||
### 开发体验
|
||
- ✅ **清晰架构** - 易于理解和维护
|
||
- ✅ **完善文档** - 架构文档、API 文档、重构报告
|
||
- ✅ **类型安全** - 完整的 TypeScript 类型定义
|
||
|
||
## 📈 下一步计划
|
||
|
||
### Phase 2: 持续优化（Day 3-4）
|
||
- [ ] 替换所有 console.log 为 logger
|
||
- [ ] 实现虚拟滚动优化消息列表
|
||
- [ ] 添加数据库索引（IndexedDB 迁移）
|
||
- [ ] 优化重渲染（shallowRef）
|
||
- [ ] 添加请求缓存和去重
|
||
|
||
### Phase 3: 新功能开发（Week 2+）
|
||
- [ ] 添加单元测试（目标 80%+ 覆盖率）
|
||
- [ ] 消息搜索功能
|
||
- [ ] 对话导出功能
|
||
- [ ] 多端同步支持
|
||
- [ ] 插件系统
|
||
- [ ] 工具调用历史记录
|
||
|
||
## ❓ 常见问题
|
||
|
||
### 连接问题
|
||
|
||
**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
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- 📋 [release.md](./release.md) - 版本发布说明
|
||
- 📖 [REFACTOR_COMPLETE.md](./REFACTOR_COMPLETE.md) - v2.0 重构完成报告
|
||
- 🏗️ [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) - 架构设计文档
|
||
- 📝 [refactor.md](./refactor.md) - 重构分析与优化方案
|
||
- 📋 [CHANGELOG.md](./CHANGELOG.md) - 更新日志
|
||
- 📚 [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md) - 开发指南
|
||
|
||
---
|
||
|
||
**MCP Client Vue v2.0.0 - 架构清晰、性能优异、易于维护的现代化 MCP 客户端** 🚀
|
||
````
|
||
`````
|
||
```` |