Amadeus-QQ-MCP

关键词

QQNapCatOneBot聊天机器人JSON-RPC

使用说明（Markdown 格式）

  • 项目简介

    • 这是一个基于 MCP（Model Context Protocol）的服务器实现，运行在 QQ 端，通过 NapCat 的 OneBot v11 HTTP/API 与 QQ 通信。服务器提供标准化的资源、工具与提示模板管理能力，允许 LLM 客户端通过 JSON-RPC 与之对话、查询上下文、调用工具、压缩上下文等。
    • 架构要点包括：MCP Client（stdio）与 MCP 服务器交互、后端通过 WebSocket 监听 QQ 消息、缓冲区管理上下文、提供多种工具接口、以及可扩展的通讯传输。

  • 主要功能点

    • MCP 服务端实现：使用 FastMCP 注册多组工具，遵循 JSON-RPC 请求/响应模式。
    • 工具集成：check_status、get_group_list、get_recent_context、batch_get_recent_context、send_message、compress_context 等。
    • 上下文管理：通过 WebSocket 实时监听 QQ 消息，提供消息缓冲、回填历史、按 target（群/私聊）分组管理。
    • 自动化消息拆分与打字延迟：发送消息时自动分 chunk，并模拟人类打字节奏。
    • 白名单与访问控制：对群组、好友进行监控和访问控制，防止越权操作。
    • 压缩与摘要：将历史消息压缩为摘要，替换为摘要块以节省资源。
    • 兼容性与传输：支持标准 IO（stdio）作为 MCP 客户端入口，NapCat HTTP/WebSocket 支持的交互，以及后端对 WebSocket 的自动重连。

  • 安装步骤（简要）

    • Linux
      • 运行脚本安装依赖与环境：scripts/install-linux.sh
      • 配置 NapCat：scripts/setup-linux.sh
      • 启动 NapCat：scripts/start-docker-linux.sh
      • 测试 MCP 连接：uv run python 脚本/scripts/test-mcp-linux.py
      • 启动 MCP 服务器：uv run qq-agent-mcp --qq <你的 QQ 号>（最小参数）或带更多选项
    • Windows
      • 配置 NapCat：scripts/setup-windows.ps1
      • 启动 NapCat：脚本 start-docker-windows.ps1
      • 启动 MCP 服务器：uv run qq-agent-mcp --qq <你的 QQ 号>
    • 通用要点
      • 该服务器通过 stdio 作为 MCP 服务器入口，客户端需要提供一个配置来连接服务器的启动命令与参数（示例见下文 JSON 配置部分）。
      • NapCat 提供 QQ 上下文与 OneBot v11 的接口，服务器端会通过 HTTP API 与 WebSocket 进行交互。

  • 服务器配置（MCP 客户端需要的配置示例） 说明：MCP 客户端（LLM 前端）需要知道如何启动并连接到 MCP 服务器。本示例给出一个 JSON 结构，包含服务器名称、启动命令和参数。请将实际参数替换为你的环境配置。 配置示例（JSON 形式）： { "mcpServers": { "qq-agent": { "server_name": "qq-agent-mcp", "command": "uv", "args": "run qq-agent-mcp --qq <你的QQ号> --napcat-host 127.0.0.1 --napcat-port 3000 --ws-port 3001" } // 备注：若直接使用 Python 启动，可将 command 换成 Python 可执行路径与模块启动参数，例如： // "command": "python", "args": " -m qq_agent_mcp --qq <你的QQ号>" } }

  • 基本使用方法

    • 启动前提：确保 NapCat/OneBot 已正确运行并可访问，QQ 账号已登录，服务器具备网络访问权限。
    • 启动 MCP 服务器后，LLM 客户端通过 MCP 协议向服务器发送请求，如 initialize、tools/list、tools/call 等来探测能力、调用工具并获取上下文。
    • 使用示例流程（由客户端发起，服务器端响应）：
      • initialize：建立会话、协商协议版本与能力。
      • tools/list：获取可用的工具清单。
      • tools/call：调用像 check_status、get_recent_context 等工具，获取 QQ 群/私聊的上下文、实时消息等信息。
      • get_recent_context / batch_get_recent_context：获取目标的最近消息上下文，用于 LLM 进行上下文推理。
      • send_message：向群组或私聊发送分段消息，带打字节奏、可设定回复目标、分段策略等。
      • compress_context：对指定目标的消息缓冲区进行摘要压缩，释放历史缓冲以节省资源。
    • 客户端配置完成后，LLM 客户端即可通过 MCP 协议与服务器对话，获取上下文、执行工具、获取和渲染 Prompt 模板等。

  • 其他注意

    • 本实现包含集成测试脚本（tests/ 目录下的测试），用于验证握手、工具列表、上下文获取等功能，实际生产应关闭测试或在受控环境中运行。
    • 该服务器能在多种场景下工作，包括群组与私聊的上下文管理、消息分段发送与摘要压缩，方便将 LLM 的上下文服务与 QQ 聊天场景对接。

  • 小结

    • 该仓库实现了一个完整的 MCP 服务器端，具备核心 MCP 功能、工具注册、上下文缓冲、历史回填、消息分段发送与摘要压缩等能力，且通过 NapCat QQ 实现与 OneBot v11 的实际对接，能够为 LLM 客户端提供标准化的上下文服务。

服务器信息

访问项目