admin/AIPentest

Fork 0

mirror of https://github.com/SunZhimin2021/AIPentest.git synced 2025-11-04 18:32:47 +00:00

AiShell 77581c56d6

Update README.md

2025-10-20 21:11:01 +08:00

12 KiB

Raw Blame History

MCP Open Client

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

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

🚀 什么是 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 包管理器）
现代浏览器

快速安装

# 克隆仓库
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. 启动应用

# 激活虚拟环境
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

{
  "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" ] },

{
  "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：

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

重要提示：

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

🛠️ 支持的 MCP 服务器

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

官方 MCP 服务器

# 文件系统操作
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 构建你自己的服务器

🧰 元工具系统

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: 向消息注入对话上下文

创建自定义元工具

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'"

# 解决方案：确保虚拟环境已激活并安装包
source venv/bin/activate
pip install -e .

问题: MCP 工具不可用

# 解决方案 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 调用失败

# 解决方案：验证 API 配置
cat mcp_open_client/settings/user-settings.json
# 确保 api_key 和 base_url 正确

调试模式

# 使用详细日志运行
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 # 上下文注入

运行测试

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

# 测试 MCP 集成
python test_manual_mcp.py

贡献

Fork 仓库
创建功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m '添加某个功能'）
推送到分支（git push origin feature/amazing-feature）
开启 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 文件。

🙏 致谢

使用 NiceGUI 构建 Web 界面
使用 FastMCP 实现 MCP 协议
灵感来自模型上下文协议规范
感谢 Anthropic 开发 MCP 标准

🔗 相关链接

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

🌟 功能路线图

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

💬 支持

如有问题、建议或意见：

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

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

12 KiB Raw Blame History Unescape Escape