# 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 客户端** 🚀

````