QQ-MCP-Server: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

项目概述

QQ-MCP-Server 把一个已登录的 NapCatQQ 机器人封装成 MCP Streamable HTTP 服务：对外讲 MCP（JSON-RPC over HTTP），对内调用用户自备的 NapCatQQ OneBot HTTP API。本项目只实现 MCP 服务本身，不负责安装/登录/维护 NapCatQQ。

命令

开发环境为 Windows + PowerShell，仓库自带 .venv。下列命令可直接用 python，或显式用 .\.venv\Scripts\python.exe。

pip install -e ".[dev]"                 # 安装运行 + 开发依赖（pytest）
pytest                                   # 跑全部测试
pytest tests/test_logic.py              # 跑单个文件
pytest tests/test_logic.py::test_send_group_message_parses_cq_at   # 跑单个用例
python tests/smoke_initialize.py        # 本地 MCP initialize 冒烟测试（不需真实 NapCat）
python -m qq_mcp_server                  # 本地启动服务（需先配置 .env）
bash deploy.sh                           # Linux 一键部署（装依赖 + 生成配置 + systemd）

• 测试用 asyncio_mode = "auto"（见 pyproject.toml），async 测试不需要写 @pytest.mark.asyncio。
• 运行前至少要有 QQ_MCP_ACCESS_TOKEN 和 NAPCAT_BASE_URL 两个环境变量（缺失会在 Config.from_env() 直接报错退出），可从 .env.example 复制。

架构

三层分明，依赖方向单向（server → logic → napcat）：

• config.py — Config 冻结 dataclass，全部配置来自环境变量，入口是 Config.from_env()。代码里不硬编码任何服务器/token/QQ 号。
• napcat.py — NapCatClient.call(action, payload) 是对 OneBot HTTP（POST <base_url>/<action>）的唯一异步封装。它只返回 OneBot 响应里的 data 字段，并把传输错误、鉴权失败、API 级失败统一抛成 NapCatError(ToolError 子类)。调用方永远不用关心 HTTP 细节。
• logic.py — 真正的工具逻辑：参数校验、编排 NapCat 调用、整理返回结构。刻意与框架无关：每个函数接收 NapCatClient + Config，返回纯 dict 或抛 ToolError，因此能用 tests/conftest.py 里的 FakeNapCat 在不起 HTTP 的情况下单测。
• server.py — 用 FastMCP 注册工具。每个 @mcp.tool 都是薄包装：解出 client/config 后委托给 logic，并统一经 _execute() 包装结果。build_mcp() 的 lifespan 负责创建/关闭 NapCatClient；create_app() 把 ASGI app 包上 AuthMiddleware 并追加无鉴权的 /health。
• auth.py — ASGI 中间件，对除 /health 外的所有 HTTP 请求校验 token，支持三种传递方式（Authorization: Bearer / X-API-Key / ?token=），用 hmac.compare_digest 常量时间比较，无 token 配置时一律拒绝（fail closed）。
• errors.py — 统一响应信封与稳定错误码。成功 {"ok": true, "data": ...}，失败 {"ok": false, "error": {"code", "message", "detail"}}。