re：以直接代码而不是submodule形式添加内置插件

2025-12-06 00:50:23 +08:00
parent 8d7d7f0fb2
commit 1aaf129d46
12 changed files with 6556 additions and 31 deletions
--- a/plugins/MaiBot_MCPBridgePlugin/README.md
+++ b/plugins/MaiBot_MCPBridgePlugin/README.md
@@ -0,0 +1,220 @@
+# MCP 桥接插件
+
+将 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器的工具桥接到 MaiBot，使麦麦能够调用外部 MCP 工具。
+
+<img width="3012" height="1794" alt="image" src="https://github.com/user-attachments/assets/ece56404-301a-4abf-b16d-87bd430fc977" />
+
+## 🚀 快速开始
+
+### 1. 安装
+
+```bash
+# 克隆到 MaiBot 插件目录
+cd /path/to/MaiBot/plugins
+git clone https://github.com/CharTyr/MaiBot_MCPBridgePlugin.git MCPBridgePlugin
+
+# 安装依赖
+pip install mcp
+
+# 复制配置文件
+cd MCPBridgePlugin
+cp config.example.toml config.toml
+```
+
+### 2. 添加服务器
+
+编辑 `config.toml`，在 `[servers]` 的 `list` 中添加服务器：
+
+**免费服务器：**
+```json
+{"name": "time", "enabled": true, "transport": "streamable_http", "url": "https://mcp.api-inference.modelscope.cn/server/mcp-server-time"}
+```
+
+**带鉴权的服务器（v1.4.2）：**
+```json
+{"name": "my-server", "enabled": true, "transport": "streamable_http", "url": "https://mcp.xxx.com/mcp", "headers": {"Authorization": "Bearer 你的密钥"}}
+```
+
+**本地服务器（需要 uvx）：**
+```json
+{"name": "fetch", "enabled": true, "transport": "stdio", "command": "uvx", "args": ["mcp-server-fetch"]}
+```
+
+### 3. 启动
+
+重启 MaiBot，或发送 `/mcp reconnect`
+
+---
+
+## 📚 去哪找 MCP 服务器？
+
+| 平台 | 说明 |
+|------|------|
+| [mcp.modelscope.cn](https://mcp.modelscope.cn/) | 魔搭 ModelScope，免费推荐 |
+| [smithery.ai](https://smithery.ai/) | MCP 服务器注册中心 |
+| [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | 官方服务器列表 |
+
+---
+
+## 💡 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `/mcp` | 查看连接状态 |
+| `/mcp tools` | 查看可用工具 |
+| `/mcp reconnect` | 重连服务器 |
+| `/mcp trace` | 查看调用记录 |
+| `/mcp cache` | 查看缓存状态 |
+| `/mcp perm` | 查看权限配置 |
+| `/mcp import <json>` | 🆕 导入 Claude Desktop 配置 |
+| `/mcp export [claude]` | 🆕 导出配置 |
+| `/mcp search <关键词>` | 🆕 搜索工具 |
+
+---
+
+## ✨ 功能特性
+
+### 核心功能
+- 🔌 多服务器同时连接
+- 📡 支持 stdio / SSE / HTTP / Streamable HTTP
+- 🔄 自动重试、心跳检测、断线重连
+- 🖥️ WebUI 完整配置支持
+
+### v1.7.0 新增
+- ⚡ **断路器模式** - 故障服务器快速失败，避免拖慢整体响应
+- 🔄 **状态实时刷新** - WebUI 自动更新连接状态（可配置间隔）
+- 🔍 **工具搜索** - `/mcp search <关键词>` 快速查找工具
+
+### v1.6.0 新增
+- 📥 **配置导入** - 从 Claude Desktop 格式一键导入
+- 📤 **配置导出** - 导出为 Claude Desktop / Kiro / MaiBot 格式
+
+### v1.4.0 新增
+- 🚫 **工具禁用** - WebUI 直接禁用不想用的工具
+- 🔍 **调用追踪** - 记录每次调用详情，便于调试
+- 🗄️ **调用缓存** - 相同请求自动缓存
+- 🔐 **权限控制** - 按群/用户限制工具使用
+
+### 高级功能
+- 📦 Resources 支持（实验性）
+- 📝 Prompts 支持（实验性）
+- 🔄 结果后处理（LLM 摘要提炼）
+
+---
+
+## ⚙️ 配置说明
+
+### 服务器配置
+
+```json
+[
+  {
+    "name": "服务器名",
+    "enabled": true,
+    "transport": "streamable_http",
+    "url": "https://..."
+  }
+]
+```
+
+| 字段 | 说明 |
+|------|------|
+| `name` | 服务器名称（唯一） |
+| `enabled` | 是否启用 |
+| `transport` | `stdio` / `sse` / `http` / `streamable_http` |
+| `url` | 远程服务器地址 |
+| `headers` | 🆕 鉴权头（如 `{"Authorization": "Bearer xxx"}`） |
+| `command` / `args` | 本地服务器启动命令 |
+
+### 权限控制（v1.4.0）
+
+**快捷配置（推荐）：**
+```toml
+[permissions]
+perm_enabled = true
+quick_deny_groups = "123456789"      # 禁用的群号
+quick_allow_users = "111111111"      # 管理员白名单
+```
+
+**高级规则：**
+```json
+[{"tool": "mcp_*_delete_*", "denied": ["qq:123456:group"]}]
+```
+
+### 工具禁用
+
+```toml
+[tools]
+disabled_tools = '''
+mcp_filesystem_delete_file
+mcp_filesystem_write_file
+'''
+```
+
+### 调用缓存
+
+```toml
+[settings]
+cache_enabled = true
+cache_ttl = 300
+cache_exclude_tools = "mcp_*_time_*"
+```
+
+---
+
+## ❓ 常见问题
+
+**Q: 工具没有注册？**
+- 检查 `enabled = true`
+- 检查 MaiBot 日志错误信息
+- 确认 `pip install mcp`
+
+**Q: JSON 格式报错？**
+- 多行 JSON 用 `'''` 三引号包裹
+- 使用英文双引号 `"`
+
+**Q: 如何手动重连？**
+- `/mcp reconnect` 或 `/mcp reconnect 服务器名`
+
+---
+
+## 📥 配置导入导出（v1.6.0）
+
+### 从 Claude Desktop 导入
+
+如果你已有 Claude Desktop 的 MCP 配置，可以直接导入：
+
+```
+/mcp import {"mcpServers":{"time":{"command":"uvx","args":["mcp-server-time"]},"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}
+```
+
+支持的格式：
+- Claude Desktop 格式（`mcpServers` 对象）
+- Kiro MCP 格式
+- MaiBot 格式（数组）
+
+### 导出配置
+
+```
+/mcp export           # 导出为 Claude Desktop 格式（默认）
+/mcp export claude    # 导出为 Claude Desktop 格式
+/mcp export kiro      # 导出为 Kiro MCP 格式
+/mcp export maibot    # 导出为 MaiBot 格式
+```
+
+### 注意事项
+- 导入时会自动跳过同名服务器
+- 导入后需要发送 `/mcp reconnect` 使配置生效
+- 支持 stdio、sse、http、streamable_http 全部传输类型
+
+---
+
+## 📋 依赖
+
+- MaiBot >= 0.11.6
+- Python >= 3.10
+- mcp >= 1.0.0
+
+## 📄 许可证
+
+AGPL-3.0