# qq-bot-sender-mcp

一个面向个人 QQ 单聊场景的 MCP 服务，用来向好友发送文本、Markdown、图片和文件。

## 项目简介

`qq-bot-sender-mcp` 通过 MCP 协议封装 QQ 机器人私聊发送能力，适合这类场景：

- 把运行结果直接发到自己的 QQ
- 把截图、图片或文档推送到 QQ
- 在支持 MCP 的客户端里，通过工具调用完成消息发送

当前实现**只支持个人单聊（C2C）**，不支持群聊。

如果这个项目对你有帮助，欢迎点个 Star 支持一下。

## 应用场景

- 任务跑完后，把处理结果自动发到自己的 QQ
- 做代码修改、数据处理或脚本执行后，把阶段进展同步到 QQ
- 截图、报表、文档、压缩包等产物生成后，直接推送到 QQ
- 测试、构建、验证完成后，把结果作为简短通知发到 QQ
- 需要人工确认下一步时，先发一条 QQ 提醒，再回来继续处理

## 支持能力

服务当前支持发送：

- 普通文本消息
- Markdown 消息
- 图片文件：`.png`、`.jpg`、`.jpeg`、`.gif`、`.bmp`、`.webp`
- 普通文件：`.doc`、`.docx`、`.pdf`、`.txt`、`.xls`、`.xlsx`、`.ppt`、`.pptx`、`.zip`、`.rar`

同时提供状态检查工具，可查看当前配置是否完整、最近一次记录到的私聊用户是谁、是否已经具备默认发送目标。

## 目录说明

- `server.py`：MCP 服务主程序
- `config.example.json`：配置示例
- `config.json`：本地实际配置文件，**不入库**
- `tests/test_server.py`：测试用例

## 安装依赖

```bash
python -m pip install -r requirements.txt
```

## 配置方式

服务启动时会读取 `server.py` 同目录下的 `config.json`。

先复制示例配置：

```bash
copy config.example.json config.json
```

然后填写你自己的机器人配置。

如果你还没有 QQ Bot，可以先前往这里申请：<https://q.qq.com/qqbot/openclaw/login.html>

示例配置如下：

```json
{
  "appid": "your_appid",
  "client_secret": "your_client_secret",
  "token_file": "~/.workbuddy/qq_token.json",
  "openid_store_file": "~/.workbuddy/qq_openid_store.json",
  "api_base_url": "https://api.sgroup.qq.com",
  "token_refresh_url": "https://bots.qq.com/app/getAppAccessToken",
  "gateway_url": "https://api.sgroup.qq.com/gateway"
}
```

字段说明：

- `appid`：QQ 机器人 AppID，必填
- `client_secret`：QQ 机器人密钥，必填
- `token_file`：访问令牌缓存路径，可选
- `openid_store_file`：最近私聊用户信息缓存路径，可选
- `api_base_url`、`token_refresh_url`、`gateway_url`：默认已内置，通常不需要改

## 配置安全说明

- 仓库中只保留 `config.example.json`
- `config.json` 已被 `.gitignore` 忽略，不应提交真实凭据
- `token_file`、`openid_store_file` 对应的本地缓存文件也不应提交，建议放在仓库目录之外
- 请只在本地填写真实 `appid` 和 `client_secret`

## 启动服务

```bash
python -X utf8 server.py
```

服务通过标准输入输出处理 MCP 通信。

## 接入 MCP 客户端

如果你的 MCP 客户端支持通过命令启动本地服务，可以把 `qq-bot-sender-mcp` 配置为一个标准输入输出型服务。

通用示例：

```json
{
  "mcpServers": {
    "qq-bot-sender": {
      "command": "python",
      "args": ["-X", "utf8", "server.py"],
      "cwd": "D:/AI-BestPractice/mcp/qq-bot-sender-mcp"
    }
  }
}
```

说明：

- `command` 需要指向你本机可用的 Python 命令，例如 `python` 或 Python 绝对路径
- 建议统一加上 `-X utf8`，避免在 Windows 中文环境下出现标准输入输出或日志编码问题
- `cwd` 应该指向本仓库目录，这样服务才能读取同目录下的 `config.json`
- 如果你的客户端不支持 `cwd`，也可以直接把 `args` 写成 `-X`, `utf8`, `D:/AI-BestPractice/mcp/qq-bot-sender-mcp/server.py` 的组合

完成接入后，重启 MCP 客户端，让它重新加载工具列表。

## MCP 工具

### `get_status`

查看当前配置和默认发送目标状态。

返回信息包括：

- `config_path`：当前配置文件路径
- `appid_masked`：脱敏后的 AppID
- `token_file`：Token 缓存路径
- `openid_store_file`：最近联系人存储路径
- `recent_openid`：最近记录到的个人用户 openid
- `recent_username`：最近记录到的用户名
- `last_seen_at`：最近记录时间
- `can_send`：当前是否已经具备默认发送目标

### `send_text`

发送普通文本消息。

参数：

- `content`：要发送的文本内容，必填
- `openid`：目标个人用户 openid，选填；不传时使用最近私聊用户

### `send_markdown`

发送 Markdown 消息。

参数：

- `content`：Markdown 内容，必填
- `openid`：目标个人用户 openid，选填

说明：自定义 Markdown 发送依赖平台权限，如果平台拒绝会直接返回错误。

### `send_image`

发送图片文件。

参数：

- `file_path`：图片完整路径，必填
- `caption`：图片说明文字，选填
- `openid`：目标个人用户 openid，选填

### `send_file`

发送普通文件。

参数：

- `file_path`：文件完整路径，必填
- `content`：文件说明文字，选填
- `openid`：目标个人用户 openid，选填

## 推荐使用流程

1. 安装依赖
2. 复制 `config.example.json` 为 `config.json`
3. 在 `config.json` 中填写真实 `appid` 和 `client_secret`
4. 启动服务：`python -X utf8 server.py`
5. 让目标 QQ 用户先给机器人发送一条私聊消息
6. 调用 `get_status`，确认 `can_send` 为 `true`
7. 再调用 `send_text`、`send_markdown`、`send_image` 或 `send_file`

## 默认目标是怎么来的

这个服务不再在代码里硬编码某个 `openid`。

默认发送目标来自最近一次收到的 QQ 私聊事件：

- 当用户先给机器人发送一条私聊消息时
- 服务会自动记录该用户的个人 `openid`
- 后续如果工具调用里不显式传 `openid`，就默认发给这个最近联系人

如果你想临时发给别的用户，也可以在工具参数里手动传入 `openid`。

## 限制说明

- 仅支持单聊（C2C），不支持群聊
- 图片大小最大 8MB
- 文件大小最大 100MB
- 主动消息发送频率受 QQ 平台规则限制

## 常见问题

### 1. 为什么 `can_send` 是 `false`？

通常表示当前 `openid_store_file` 里还没有最近联系人。让目标 QQ 用户先发一条私聊消息，再调用 `get_status` 检查。

### 2. 为什么不支持群聊？

当前实现的接口调用、默认目标解析和本地存储都围绕个人用户 `openid` 设计，没有实现群聊链路。

### 3. 为什么必须先收到一条私聊？

因为默认发送目标需要从最近一次私聊事件中提取个人 `openid`。如果你不手动传 `openid`，服务就必须先知道要发给谁。

### 4. 什么时候需要手动传 `openid`？

当你要临时指定目标用户，或者不想使用“最近私聊用户”作为默认发送目标时，可以在发送工具里显式传入 `openid`。

### 5. 如果启动时报配置错误怎么办？

优先检查：

- `config.json` 是否存在
- `appid` 是否已填写
- `client_secret` 是否已填写
- 路径字段是否可写

## 测试

```bash
pytest
```

当前测试覆盖了配置加载、状态查询、默认目标解析等核心逻辑。

发送图片或文件时，请自行准备本地测试文件；仓库内不再附带示例发送素材。