qq_bot_MCP
基于 qq-botpy + MCP 的 QQ 机器人桥接服务。通过 MCP 工具协议暴露 QQ 消息收发能力，让外部项目无需依赖 QQ SDK 即可接入 QQ 消息流。
架构说明
qq_bot_mcp/config.py：配置加载（QQ 凭据）qq_bot_mcp/models.py：数据模型（事件、回复结果）qq_bot_mcp/adapters/qq_client.py：QQ 平台适配层（接收 AT/私信/C2C/群聊消息）qq_bot_mcp/services/message_hub.py：协程消息总线（待处理事件队列、历史记录、回复分发）qq_bot_mcp/mcp/server.py：MCP 工具层（暴露给 MCP 客户端调用）qq_bot_mcp/runtime.py：运行时装配（QQ Bot 生命周期管理）qq_bot_mcp/cli.py：CLI 入口
默认行为：只收消息不自动回复，由 MCP 客户端决定如何处理并回包。
依赖安装
uv sync或：
pip install -e .环境变量
在根目录创建 .env：
qq_bot_id=你的BotAppID
qq_bot_appsecret=你的BotSecret运行方式
一体化（QQ Bot + MCP Server）
uv run qq-bot-mcp --mode all仅 QQ Bot Runtime
uv run qq-bot-mcp --mode bot仅 MCP Server（不启动 QQ Bot）
uv run qq-bot-mcp --mode mcpMCP 工具清单
| 工具名 | 说明 |
|---|---|
qqbot_status | 运行状态、待处理数量、累计消息数 |
qqbot_list_pending(limit) | 拉取待处理事件 |
qqbot_wait_event(timeout_seconds) | 阻塞等待一条新事件 |
qqbot_reply_event(event_id, ...) | 按事件回复到 QQ（支持文本/图片/Markdown/Ark/Embed/Media） |
qqbot_discard_event(event_id) | 丢弃事件，不做回复 |
qqbot_list_history(limit) | 查看最近历史消息 |
qqbot_capabilities | 返回场景能力说明 |
MCP 客户端接入流程
- 以 stdio 方式启动本服务作为 MCP server
- 调用
qqbot_wait_event或qqbot_list_pending获取消息 - 根据业务逻辑生成回复
- 调用
qqbot_reply_event(event_id, content=...)回消息到 QQ
客户端实现由使用方自行完成。
测试
uv run pytest test/ -vAI 客户端 Demo（DeepSeek）
已提供最小客户端示例：test/ai_chat_client_demo.py。
先在 .env 增加：
LLM_API_KEY=你的DeepSeekKey
LLM_MODEL=deepseek-chat
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_TIMEOUT=30运行：
uv run python test/ai_chat_client_demo.py