admin/AIPentest
1
0
Fork 0
mirror of https://github.com/SunZhimin2021/AIPentest.git synced 2025-11-05 10:53:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
AIPentest/mcp-open-client/README.md

399 lines
11 KiB
Markdown
Raw Normal View History

添加 mcp-open-client: 基于 MCP 协议的现代化聊天应用 - 支持多 LLM（OpenAI、Claude、DeepSeek 等） - 完整的 MCP 协议集成 - 现代化 Web UI（基于 NiceGUI） - 元工具系统 - 中文文档 来源：https://github.com/alejoair/mcp-open-client
2025-10-19 15:43:07 +08:00
# 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:8080`）。
### 2. 配置 API 设置
在浏览器中打开显示的 URL，进入 **配置 → API 设置**：
```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 服务器** 添加外部工具：
```json
{
"mcpServers": {
"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 和开源社区打造**
Reference in New Issue Copy Permalink