# MCP Open Client

本项目来自 https://github.com/alejoair/mcp-open-client
原项目是西班牙语，作为英文化翻译。

> 一个基于 Web 的现代化聊天应用，实现了模型上下文协议（Model Context Protocol, MCP），用于 LLM 与外部工具的无缝集成。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.8+-green.svg)](https://github.com/jlowin/fastmcp)

## 🚀 什么是 MCP Open Client？

**MCP Open Client** 是一个基于 NiceGUI 构建的聊天应用，通过**模型上下文协议（MCP）**在 AI 模型与外部工具之间架起桥梁。可以把它理解为 **"AI 的 USB-C"** —— 一个通用接口，允许任何兼容的 LLM 安全地与外部数据源、工具和服务交互。

### 核心特性

- 🤖 **多 LLM 支持**：兼容 OpenAI、Claude、DeepSeek 以及任何 OpenAI 兼容的 API
- 🔧 **MCP 集成**：连接 MCP 服务器获得增强功能（文件系统、网络搜索、数据库、自定义工具）
- 💬 **现代化聊天界面**：基于 NiceGUI 构建的简洁、响应式 Web UI
- 📚 **对话管理**：保存、加载和组织聊天历史
- ⚙️ **简易配置**：基于 Web 的设置管理
- 🌐 **本地与远程**：支持本地模型（Ollama、LM Studio）和云端 API
- 🔒 **安全**：所有配置本地存储
- 🛠️ **元工具系统**：用于 UI 交互和服务器控制的自定义工具系统

## 🏗️ 架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web 客户端    │◄──►│   MCP 客户端    │◄──►│  MCP 服务器     │
│   (NiceGUI)     │    │  (FastMCP)      │    │  (工具/API)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
    聊天界面               API 集成                  外部工具
    • 对话管理            • OpenAI API              • 文件系统
    • 历史记录            • Claude API              • 数据库
    • 设置                • 本地模型                • Web 服务
                                                    • 自定义工具
```

## 📦 安装

### 前置要求

- Python 3.8 或更高版本
- pip（Python 包管理器）
- 现代浏览器

### 快速安装

```bash
# 克隆仓库
git clone https://github.com/yourusername/mcp-open-client.git
cd mcp-open-client

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows 系统: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 安装包
pip install -e .
```



## 🚀 快速开始

### 1. 启动应用

```bash
# 激活虚拟环境
source venv/bin/activate  # Windows 系统: venv\Scripts\activate

# 运行应用
python -m mcp_open_client.main
```

应用将启动并显示访问 URL（通常为 `http://localhost:8091`）。

### 2. 配置 API 设置

进入 mcp-open-client/mcp_open_client/settings/ 目录：
cp user-settings.json.example user-settings.json
编辑user-settings.json，如下，修改api_key为你的deepseek api key
```json
{
  "api_key": "your-api-key-here",
  "base_url": "https://api.deepseek.com",
  "model": "deepseek-chat",
  "system_prompt": "你是一个有用的助手。",
  "max_tokens": 4000,
  "tool_choice_required": false
}
```

**支持的提供商**：
- **OpenAI**: `https://api.openai.com/v1`
- **Anthropic Claude**: `https://api.anthropic.com`
- **DeepSeek**: `https://api.deepseek.com`
- **本地 Ollama**: `http://localhost:11434/v1`
- **LM Studio**: `http://localhost:1234/v1`

### 3. 设置 MCP 服务器（可选）
进入 mcp-open-client/mcp_open_client/settings/ 目录：
cp mcp-config.json.example mcp-config.json
编辑mcp-config.json
增加一个段
"hexstrike-ai": {
      "disabled": false,
      "command": "python3",
      "args": [
        "PATH/hexstrike_mcp.py",
        "--server",
        "http://IP:PORT"
      ]
    },

```json
{
  "mcpServers": {
         "hexstrike-ai": {
      "disabled": false,
      "command": "python3",
      "args": [
        "PATH/hexstrike_mcp.py",
        "--server",
        "http://IP:PORT"
      ]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
    },
    "web-search": {
      "command": "uvx",
      "args": ["mcp-requests"]
    }
  }
}
```

### 4. 开始聊天！

在主聊天界面开始对话。如果配置了 MCP 服务器，AI 可以在需要时自动使用这些工具。

## ⚙️ 配置

### API 配置

编辑 `mcp_open_client/settings/user-settings.json` 或使用 Web UI：

| 参数 | 说明 | 示例 |
|------|------|------|
| `api_key` | 你的 LLM API 密钥 | `sk-...` |
| `base_url` | API 端点 URL | `https://api.deepseek.com` |
| `model` | 模型标识符 | `deepseek-chat` |
| `system_prompt` | 系统提示词 | `你是一个有用的助手。` |
| `max_tokens` | 最大响应长度 | `4000` |
| `tool_choice_required` | 强制使用工具 | `false` |

### MCP 服务器配置

编辑 `mcp_open_client/settings/mcp-config.json` 或使用 Web UI：

```json
{
  "mcpServers": {
    "服务器名称": {
      "command": "python3",
      "args": ["/path/to/server.py"],
      "env": {
        "API_KEY": "可选的环境变量"
      }
    }
  }
}
```

**重要提示**：
- FastMCP 会自动检测传输协议（stdio/sse）
- 不要添加 `transport`、`description` 或 `timeout` 字段（会导致错误）
- 设置 `"disabled": true` 可临时禁用服务器而无需删除配置

## 🛠️ 支持的 MCP 服务器

客户端可与任何符合 MCP 规范的服务器配合使用。常用选项：

### 官方 MCP 服务器

```bash
# 文件系统操作
npx -y @modelcontextprotocol/server-filesystem /workspace/path

# GitHub 集成
npx -y @modelcontextprotocol/server-github

# 网络搜索（Brave）
npx -y @modelcontextprotocol/server-brave-search

# PostgreSQL 数据库
npx -y @modelcontextprotocol/server-postgres
```

### 社区 MCP 服务器

- **mcp-requests**: HTTP 请求能力
- **mcp-code-editor**: 文件编辑和代码操作
- **HexStrike AI**: 150+ 安全工具用于渗透测试
- 自定义服务器：使用 [FastMCP](https://github.com/jlowin/fastmcp) 构建你自己的服务器

## 🧰 元工具系统

MCP Open Client 包含**元工具系统**用于 UI 交互和服务器控制：

- `meta-ui_notify`: 在 UI 中显示通知
- `meta-mcp_toggle_server`: 动态启用/禁用 MCP 服务器
- `meta-mcp_list_servers`: 列出所有已配置的 MCP 服务器
- `meta-mcp_restart_all_servers`: 重新初始化 MCP 连接
- `meta-respond_to_user`: 使用颜色和样式格式化响应
- `meta-conversation_context`: 向消息注入对话上下文

### 创建自定义元工具

```python
from mcp_open_client.meta_tools import meta_tool

@meta_tool(
    name="custom_tool",
    description="执行自定义操作",
    parameters_schema={
        "type": "object",
        "properties": {
            "param": {"type": "string", "description": "参数"}
        },
        "required": ["param"]
    }
)
def my_custom_tool(param: str):
    # 你的实现
    return f"结果: {param}"
```

## 📖 使用示例

### 基础聊天

```
你: 今天天气怎么样？
AI: 如果你提供位置，我可以帮你查询天气。

你: 北京
AI: [使用天气 MCP 工具] 北京当前天气是...
```

### 文件操作（使用文件系统 MCP 服务器）

```
你: 列出工作区中的所有 Python 文件
AI: [使用文件系统工具] 找到 15 个 Python 文件：
    - main.py
    - api_client.py
    ...
```

### 网络搜索（使用网络搜索 MCP 服务器）

```
你: AI 领域的最新进展有哪些？
AI: [使用网络搜索工具] 根据最近的文章，以下是 AI 的最新进展...
```

## 🐛 故障排查

### 常见问题

**问题**: "ModuleNotFoundError: No module named 'mcp_open_client'"
```bash
# 解决方案：确保虚拟环境已激活并安装包
source venv/bin/activate
pip install -e .
```

**问题**: MCP 工具不可用
```bash
# 解决方案 1：检查服务器是否运行
curl http://server-url/health

# 解决方案 2：验证配置
cat mcp_open_client/settings/mcp-config.json

# 解决方案 3：检查不支持的字段
# 移除：\"transport\"、\"description\"、\"timeout\"

# 解决方案 4：清除缓存并重启
rm -rf .nicegui/storage-*.json
python -m mcp_open_client.main
```

**问题**: API 调用失败
```bash
# 解决方案：验证 API 配置
cat mcp_open_client/settings/user-settings.json
# 确保 api_key 和 base_url 正确
```

### 调试模式

```bash
# 使用详细日志运行
export PYTHONUNBUFFERED=1
export FASTMCP_DEBUG=1
python -u -m mcp_open_client.main
```

## 🧪 开发

### 项目结构

```
mcp_open_client/
├── main.py                    # 应用入口
├── api_client.py              # LLM API 通信
├── mcp_client.py              # MCP 协议处理器
├── config_utils.py            # 配置工具
├── settings/                  # 配置文件
│   ├── user-settings.json     # API 设置
│   └── mcp-config.json        # MCP 服务器配置
├── ui/                        # 用户界面组件
│   ├── home.py                # 主页
│   ├── chat_interface.py      # 聊天 UI
│   ├── chat_handlers.py       # 聊天逻辑
│   ├── configure.py           # 设置 UI
│   ├── mcp_servers.py         # MCP 管理 UI
│   └── message_parser.py      # 消息渲染
└── meta_tools/                # 自定义元工具系统
    ├── meta_tool.py           # 工具注册表
    ├── notify_user.py         # UI 通知
    ├── server_control.py      # MCP 服务器控制
    └── conversation_context.py # 上下文注入
```

### 运行测试

```bash
# 测试 MCP 客户端初始化
python test_client_init.py

# 测试 MCP 集成
python test_manual_mcp.py
```

### 贡献

1. Fork 仓库
2. 创建功能分支（`git checkout -b feature/amazing-feature`）
3. 提交更改（`git commit -m '添加某个功能'`）
4. 推送到分支（`git push origin feature/amazing-feature`）
5. 开启 Pull Request

## 📋 依赖要求

- Python 3.8+
- 现代浏览器（Chrome、Firefox、Safari、Edge）
- 互联网连接（用于云端 API）或本地模型设置

### 核心依赖

- `nicegui==2.21.1` - Web UI 框架
- `fastmcp>=2.8.0` - MCP 协议实现
- `openai==1.97.1` - LLM API 客户端
- `pydantic>=2.8.0,<2.11.0` - 数据验证
- `fastapi==0.116.1` - Web 服务器

完整依赖列表请参见 `requirements.txt`。

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- 使用 [NiceGUI](https://nicegui.io/) 构建 Web 界面
- 使用 [FastMCP](https://github.com/jlowin/fastmcp) 实现 MCP 协议
- 灵感来自 [模型上下文协议](https://modelcontextprotocol.io/) 规范
- 感谢 Anthropic 开发 MCP 标准

## 🔗 相关链接

- **开发文档**: 参见 [CLAUDE.md](CLAUDE.md) 获取开发者文档
- **MCP 规范**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
- **FastMCP**: [github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp)
- **MCP 服务器目录**: [mcp.run](https://mcp.run/)

## 🌟 功能路线图

- [ ] 自定义 UI 组件的插件系统
- [ ] 支持多用户和身份验证
- [ ] 高级对话搜索和过滤
- [ ] 导出对话到多种格式
- [ ] 移动端响应式设计改进
- [ ] 流式响应可视化
- [ ] 多语言支持

## 💬 支持

如有问题、建议或意见：

- 在 GitHub 上开启 issue
- 查看现有讨论
- 查阅 [CLAUDE.md](CLAUDE.md) 中的开发者文档

---

**用 ❤️ 为 AI 和开源社区打造**