# mcp_client-demo

**Repository Path**: Yokers/mcp_client-demo

## Basic Information

- **Project Name**: mcp_client-demo
- **Description**: 一个功能强大的多服务器模型上下文协议（MCP）客户端，支持连接多个本地和远程MCP服务器，并集成多种AI模型（如DeepSeek等）进行智能对话和工具调用。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP 客户端

一个功能强大的多服务器 MCP (Model Context Protocol) 客户端，支持连接多个本地和远程 MCP 服务器，并与多种 AI 模型（DeepSeek、Qwen 等）进行交互。

## ✨ 功能特性

### 🌐 多服务器管理
- **本地服务器支持**：通过 STDIO 连接本地 MCP 服务器
- **远程服务器支持**：通过 SSE 连接远程 MCP 服务器
- **健康检查**：自动监控服务器健康状态
- **自动重连**：服务器断开时自动重连（支持指数退避）
- **服务器切换**：支持在多个服务器间切换
- **工具聚合**：自动聚合所有服务器的工具供模型使用

### 🤖 多模型支持
- **DeepSeek 模型**：支持 `deepseek-chat` 和 `deepseek-reasoner`（思考模式）
- **自定义模型**：支持添加任意 OpenAI 兼容的模型
- **模型配置管理**：支持保存和加载模型配置
- **参数自定义**：支持自定义温度、最大 token 数等参数

### 🔧 工具调用
- **自动工具发现**：自动发现所有连接服务器的工具
- **工具调用重试**：工具调用失败时自动重试
- **多服务器工具**：支持跨服务器调用工具
- **工具缓存**：缓存工具列表以提高性能

### 📚 对话管理
- **历史记录**：自动保存对话历史
- **历史持久化**：对话历史保存到 JSON 文件
- **历史查看**：支持查看最近的对话历史
- **历史清理**：支持清除对话历史

### 📊 统计和监控
- **使用统计**：记录模型和服务器使用情况
- **性能监控**：跟踪平均响应时间
- **错误统计**：记录服务器错误和重连次数
- **健康状态**：实时显示服务器健康状态

## 📋 前置要求

- Python 3.8+
- pip

## 🚀 安装

1. **克隆或下载项目**

```bash
cd mcp-client
```

2. **安装依赖**

```bash
pip install openai mcp aiohttp aiofiles python-dotenv
```

3. **配置环境变量**

创建 `.env` 文件（可选，用于设置默认 API 密钥）：

```env
DEEPSEEK_API_KEY=your_deepseek_api_key_here
```

## 📖 使用方法

### 启动客户端

```bash
python mcp-client.py
```

### 基本流程

1. **添加服务器**
   - 启动后会提示添加服务器
   - 选择本地服务器（STDIO）或远程服务器（SSE）
   - 输入服务器信息

2. **选择模型**
   - 如果没有设置模型，会提示选择模型
   - 可以使用默认的 DeepSeek 模型或添加自定义模型

3. **开始对话**
   - 直接输入问题开始对话
   - 客户端会自动使用所有服务器的工具来回答问题

### 交互式命令

#### 模型管理
- `models` - 查看/切换模型
- `add_model` - 添加自定义模型
- `edit_model` - 编辑模型参数
- `remove_model` - 移除模型配置

#### 服务器管理
- `servers` - 查看服务器状态
- `server_details` - 查看服务器详细状态
- `add_server` - 添加新服务器
- `remove_server` - 移除服务器
- `switch_server` - 切换活动服务器
- `test_server` - 测试服务器连接
- `reconnect_all` - 重连所有服务器

#### 工具和资源
- `tools` - 查看所有服务器的工具
- `resources` - 查看所有服务器的资源

#### 历史和统计
- `history` - 查看对话历史
- `clear` - 清除历史记录
- `stats` - 查看统计信息

#### 退出
- `quit` 或 `exit` - 退出程序

## 🔧 配置说明

### 模型配置

模型配置保存在 `model_configs.json` 文件中，格式如下：

```json
{
  "model-name": {
    "provider": "deepseek",
    "model_name": "deepseek-chat",
    "api_base": "https://api.deepseek.com/v1",
    "api_key": "your_api_key",
    "temperature": 0.7,
    "max_tokens": 2000,
    "stream": false,
    "extra_params": {
      "enable_thinking": false
    }
  }
}
```

### 对话历史

对话历史保存在 `conversation_history.json` 文件中，包含：
- 用户消息
- 助手回复
- 工具调用记录
- 时间戳
- 使用的模型和服务器

## 💡 使用示例

### 示例 1：连接本地 MCP 服务器

```
💬 你: add_server
➕ 添加服务器连接
1. 本地服务器 (STDIO)
2. 远程服务器 (SSE)
请选择 (1/2/3): 1

服务器名称: math-server
服务器脚本路径: /path/to/math_server.py
执行命令 (默认: python): python
服务器描述 (可选): web_research服务器
```

### 示例 2：添加自定义模型

```
💬 你: add_model
➕ 添加自定义模型配置

模型名称: my-custom-model
提供商: custom
API基础地址: https://api.example.com/v1
API密钥: your_api_key
温度参数: 0.7
最大token数: 2000
启用流式传输? (y/n): n
```


## 🏗️ 项目结构

```
mcp-client/
├── mcp-client.py          # 主程序文件
├── model_configs.json     # 模型配置文件
├── conversation_history.json  # 对话历史文件
├── .env                   # 环境变量文件（可选）
└── README.md              # 本文件
```

## 🔍 核心类说明

### `RobustMultiServerMCPClient`
主客户端类，负责管理服务器连接、模型配置和对话处理。

### `ModelConfig`
模型配置类，存储模型的 API 信息、参数等。

### `ServerConnection`
服务器连接类，管理单个服务器的连接状态、工具列表等。

### `ConversationHistory`
对话历史条目，记录单条消息的完整信息。

### `ServerHealth`
服务器健康状态，跟踪服务器的连接状态、响应时间等。

## ⚙️ 高级功能

### DeepSeek 思考模式

当使用 `deepseek-reasoner` 模型时，会自动启用思考模式。思考模式允许模型进行更深入的推理，但需要注意：

- 思考模式下建议关闭流式传输
- 历史消息需要包含 `reasoning_content` 字段
- 客户端会自动处理这些格式要求

### 健康检查

客户端会定期检查服务器健康状态：
- 默认检查间隔：30 秒
- 超时时间：10 秒
- 连续失败 2 次后会尝试自动重连

### 自动重连

服务器断开连接时：
- 自动尝试重连（最多 3 次）
- 使用指数退避策略（延迟逐渐增加）
- 如果活动服务器断开，会自动切换到其他健康服务器

## 🐛 故障排除

### 问题：无法连接到服务器

**解决方案**：
1. 检查服务器脚本路径是否正确
2. 确认服务器脚本可以正常运行
3. 使用 `test_server` 命令测试连接
4. 查看服务器详细状态：`server_details`

### 问题：模型 API 调用失败

**解决方案**：
1. 检查 API 密钥是否正确
2. 确认 API 地址可访问
3. 查看模型配置：`models`
4. 尝试编辑模型参数：`edit_model`

### 问题：工具调用失败

**解决方案**：
1. 检查服务器是否健康：`servers`
2. 查看工具列表：`tools`
3. 测试服务器连接：`test_server`
4. 尝试重连服务器：`reconnect_all`

## 📝 注意事项

1. **API 密钥安全**：不要在代码中硬编码 API 密钥，使用环境变量或配置文件
2. **服务器稳定性**：确保 MCP 服务器稳定运行，避免频繁断开连接
3. **历史记录大小**：默认只保留最近 15 轮对话，避免历史记录过大
4. **并发限制**：注意 API 提供商的并发请求限制

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**享受使用 MCP 客户端！** 🚀