Mofox-Core/docs/mcp-sse-guide.md

MCP Server-Sent Events (SSE) 使用指南

📖 概述

MCP SSE 客户端是 MaiBot 的一个扩展功能，提供与 MCP (Model Context Protocol) 服务器的实时事件订阅能力。通过 Server-Sent Events (SSE) 技术，MaiBot 可以接收来自 MCP 服务器的实时事件推送，实现低延迟的交互响应。

✨ 功能特性

• 🔗 实时连接: 与 MCP 服务器建立持久的 SSE 连接
• 🔄 自动重连: 支持指数退避策略的断线重连机制
• 🎯 事件订阅: 灵活的事件类型订阅和处理系统
• 🔐 安全认证: 支持 Bearer Token 和 SSL/TLS 认证
• 📊 监控统计: 提供连接状态和事件统计信息
• 🛡️ 错误处理: 完善的异常处理和日志记录

🚀 快速开始

第一步：启用 MCP SSE 功能

1. 打开 config/bot_config.toml 配置文件
2. 找到 [mcp_sse] 配置段，如果没有请添加：

[mcp_sse]
enable = true  # 启用 MCP SSE 功能
server_url = "http://your-mcp-server.com:8080/events"  # MCP 服务器 SSE 端点
auth_key = "your-auth-token"  # 认证密钥（可选）

第二步：配置连接参数

[mcp_sse]
# 基本配置
enable = true
server_url = "http://localhost:8080/events"
auth_key = ""

# 连接配置
connection_timeout = 30  # 连接超时时间（秒）
read_timeout = 60       # 读取超时时间（秒）

# 重连配置
enable_reconnect = true           # 启用自动重连
max_reconnect_attempts = 10       # 最大重连次数（-1 表示无限重连）
initial_reconnect_delay = 1.0     # 初始重连延迟（秒）
max_reconnect_delay = 60.0        # 最大重连延迟（秒）
reconnect_backoff_factor = 2.0    # 重连延迟指数退避因子

# 事件处理配置
event_buffer_size = 1000          # 事件缓冲区大小
enable_event_logging = true       # 启用事件日志记录

# 订阅配置
subscribed_events = []            # 订阅的事件类型（空列表表示订阅所有事件）
# 示例：只订阅特定事件
# subscribed_events = ["chat.message", "user.login", "system.status"]

# 高级配置
user_agent = "MaiBot-MCP-SSE-Client/1.0"  # 用户代理字符串

# SSL 配置
verify_ssl = true        # 是否验证 SSL 证书
ssl_cert_path = ""       # SSL 客户端证书路径（可选）
ssl_key_path = ""        # SSL 客户端密钥路径（可选）

第三步：启动 MaiBot

正常启动 MaiBot，系统会自动初始化 MCP SSE 客户端：

python bot.py

启动日志中会显示 MCP SSE 相关信息：

[INFO] 初始化 MCP SSE 管理器
[INFO] 连接到 MCP 服务器: http://localhost:8080/events
[INFO] 成功连接到 MCP 服务器
[INFO] MCP SSE 系统初始化成功

📝 配置详解

基本配置

配置项	类型	默认值	说明
enable	bool	false	是否启用 MCP SSE 功能
server_url	string	""	MCP 服务器 SSE 端点 URL
auth_key	string	""	认证密钥，用于 Bearer Token 认证

连接配置

配置项	类型	默认值	说明
connection_timeout	int	30	连接超时时间（秒）
read_timeout	int	60	读取超时时间（秒）

重连配置

配置项	类型	默认值	说明
enable_reconnect	bool	true	是否启用自动重连
max_reconnect_attempts	int	10	最大重连次数，-1 表示无限重连
initial_reconnect_delay	float	1.0	初始重连延迟时间（秒）
max_reconnect_delay	float	60.0	最大重连延迟时间（秒）
reconnect_backoff_factor	float	2.0	重连延迟指数退避因子

事件处理配置

配置项	类型	默认值	说明
event_buffer_size	int	1000	事件缓冲区大小
enable_event_logging	bool	true	是否启用事件日志记录
subscribed_events	list	[]	订阅的事件类型列表

🎯 事件类型

MCP SSE 支持多种事件类型，常见的包括：

系统事件

• system.status - 系统状态变化
• system.heartbeat - 系统心跳
• system.shutdown - 系统关闭

用户事件

• user.login - 用户登录
• user.logout - 用户登出
• user.action - 用户行为

聊天事件

• chat.message - 聊天消息
• chat.typing - 正在输入
• chat.reaction - 消息反应

通知事件

• notification.info - 信息通知
• notification.warning - 警告通知
• notification.error - 错误通知

🔧 高级用法

自定义事件处理器

如果您需要对特定事件进行自定义处理，可以通过插件系统或直接修改代码来注册事件处理器：

from src.mcp import get_mcp_sse_manager

# 获取 MCP SSE 管理器
manager = get_mcp_sse_manager()

if manager:
    # 注册聊天消息事件处理器
    def handle_chat_message(event):
        print(f"收到聊天消息: {event.data}")
        # 在这里添加您的自定义逻辑
    
    manager.register_event_handler("chat.message", handle_chat_message)
    
    # 注册全局事件处理器
    def handle_all_events(event):
        print(f"收到事件: {event.event_type} - {event.data}")
    
    manager.register_global_event_handler(handle_all_events)

获取连接状态

from src.mcp import get_mcp_sse_manager

manager = get_mcp_sse_manager()
if manager:
    # 检查连接状态
    if manager.is_connected():
        print("MCP SSE 客户端已连接")
    
    # 获取详细统计信息
    stats = manager.get_stats()
    print(f"连接状态: {stats['connected']}")
    print(f"运行状态: {stats['running']}")
    print(f"总接收事件数: {stats['total_events_received']}")
    print(f"重连次数: {stats['reconnect_attempts']}")

查看最近事件

from src.mcp import get_mcp_sse_manager

manager = get_mcp_sse_manager()
if manager:
    # 获取最近 10 个事件
    recent_events = manager.get_recent_events(10)
    
    for event in recent_events:
        print(f"{event.timestamp}: {event.event_type}")
        print(f"数据: {event.data}")
        print("---")

🧪 测试功能

项目包含了完整的测试工具，您可以使用它们来验证 MCP SSE 功能：

基本功能测试

# 进入项目目录
cd /path/to/MaiBot

# 运行基本功能测试
python -m src.mcp.test_client

重连功能测试

# 测试断线重连功能
python -m src.mcp.test_client reconnect

测试脚本会输出详细的测试结果，包括：

• 连接状态
• 接收到的事件数量
• 事件类型统计
• 连接时长和性能指标

🔍 故障排除

常见问题

1. 连接失败

问题: 无法连接到 MCP 服务器

解决方案:

• 检查 server_url 配置是否正确
• 确认 MCP 服务器是否正在运行
• 检查网络连接和防火墙设置
• 验证端口是否可访问

2. 认证失败

问题: 收到 401 认证错误

解决方案:

• 检查 auth_key 配置是否正确
• 确认认证密钥是否有效
• 联系 MCP 服务器管理员获取正确的认证信息

3. SSL 证书错误

问题: SSL 证书验证失败

解决方案:

• 检查服务器 SSL 证书是否有效
• 临时设置 verify_ssl = false 进行测试
• 配置正确的客户端证书路径

4. 频繁重连

问题: 客户端不断重连

解决方案:

• 检查网络连接稳定性
• 调整重连参数（增加延迟时间）
• 检查服务器端是否有连接限制

5. 事件丢失

问题: 部分事件没有收到

解决方案:

• 增加 event_buffer_size 配置
• 检查事件处理器是否有异常
• 确认 subscribed_events 配置是否正确

日志调试

MCP SSE 相关日志使用以下标签：

• mcp.sse_client - SSE 客户端日志
• mcp.event_handler - 事件处理器日志
• mcp.manager - 管理器日志

您可以通过调整日志级别来获取更详细的调试信息：

[log]
console_log_level = "DEBUG"  # 设置为 DEBUG 级别查看详细日志

📚 API 参考

MCPSSEManager

主要的管理器类，提供以下方法：

• is_running() - 检查是否正在运行
• is_connected() - 检查是否已连接
• get_stats() - 获取统计信息
• get_recent_events(count) - 获取最近的事件
• register_event_handler(event_type, handler) - 注册事件处理器
• register_global_event_handler(handler) - 注册全局事件处理器

MCPEvent

事件对象，包含以下属性：

• event_type - 事件类型
• data - 事件数据（字典格式）
• timestamp - 事件时间戳
• event_id - 事件 ID（可选）
• retry - 重试间隔（可选）

🤝 贡献

如果您在使用过程中遇到问题或有改进建议，欢迎：

1. 提交 Issue 报告问题
2. 提交 Pull Request 贡献代码
3. 完善文档和示例

📄 许可证

本功能遵循 MaiBot 项目的许可证协议。