# MCP Vue 客户端

> **版本：1.0.0** | 基础版本 + 最新改进

作者：Gavin Chan

基于 **Vue 3** 和 **MCP 协议**构建的现代化 MCP 客户端界面，支持HTTP和SSE双传输协议。
比较粗糙，但跑通了模型 API 的对接使用，和 MCP server 的调用。

## 🎉 最新改进（开发中）

- ✅ **完善的服务器管理** - 编辑功能完全可用，表单数据正确填充
- ✅ **可靠的连接功能** - 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协议客户端** 🚀