mirror of https://github.com/Mai-with-u/MaiBot.git
221 lines
5.3 KiB
Markdown
221 lines
5.3 KiB
Markdown
# 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
|