# napcat-mcp

把 **NapCat / OneBot v11** 的接口暴露成 **MCP 工具**，并附带一个 **LLM 驱动的智能 QQ 机器人**（SmartBot）。

- **MCP Server**：把 45 个 OneBot 动作注册为 MCP 工具，供任意 MCP 客户端调用。
- **SmartBot**：常驻 QQ 机器人。支持多群/私聊、长期记忆、知识库、工具调用、
  原生联网搜索、多模态识图、主动插话、权限（主人/管理）分级、审批加群/加好友、
  群文件操作、联通云盘（沃盘）集成等。

## 环境要求

- **Node.js ≥ 21**（依赖内置 `node:sqlite`；开发使用 Node 24 验证）
- 一个可用的 **NapCat**（或其它 OneBot v11 实现），开放 WebSocket 服务
- （可选）**DeepSeek** 或任意 OpenAI / Anthropic 兼容的 LLM API

## 快速开始

```bash
npm install

# 配置
cp config.example.json config.json
# 编辑 config.json：填 wsUrl / token、bot.owner、bot.admins、bot.llm.apiKey 等
# 人设：复制 persona.example.txt 为 persona.txt 并改写，config.json 用 bot.personaFile 指向它

npm run build

# 只跑 MCP server（stdio）
npm run start

# 跑 QQ 机器人
npm run start:bot:bg     # 后台启动（pid → .bot.pid，日志 → logs/bot.out.log）
npm run status:bot
npm run stop:bot
```

## 目录结构

```
src/
  index.ts            MCP server 入口
  config.ts log.ts onebot.ts download.ts types.ts
  tools/              MCP 工具（definitions / common / index）
  integrations/wopan/ 联通云盘纯 TS 实现（crypto / client / fs）
  bot/
    index.ts          SmartBot
    prompt.ts         系统提示词组装
    tools.ts          工具聚合入口
    tools/            支撑模块（requests / risk / own / images / catalog）
    toolsets/         按域拆分的工具集（admin/social/web/... + extended + wopan）
    brain.ts memory.ts kb.ts search.ts web.ts ssrf.ts fsaccess.ts fileserver.ts ...
docs/                 接口覆盖情况等文档
scripts/bot-bg.mjs    后台启停脚本
```

## 说明

- **工具系统**：bot 侧工具按风险分级（low / manage / high），执行前在代码里强制校验；
  工具较多时启用「工具字典」懒加载——模型用 `list_tools` 查目录、`describe_tool` 查用法，
  避免每轮把全部工具 schema 塞进上下文（见 `bot.lazyTools`）。
- **记忆 / 知识库**：SQLite（`memory.db` / `kb.db`），全局时间线 + 摘要压缩 + 用户画像。
- **联通云盘**：`src/integrations/wopan` 为纯 TypeScript 实现（协议参考见 `docs/wopan/`）。
  配置在 `config.json` 的 `bot.wopan`：
  ```json
  "wopan": { "enabled": true, "tokenFile": "vendor/wo_cnpan/tokens.json", "space": "personal" }
  ```
  `tokenFile` 也可用环境变量 `WOPAN_TOKENS` 指定；`space` 可选 `personal`/`family`（家庭云再配 `familyId`）。
  相关工具全部 `risk=high`（仅主人可用）；`enabled:false` 则不注册这些工具。
- **隐私**：`config.json`、`persona.txt`、`*.db`、`logs/`、`downloads/`、`sandbox/`、
  `.private/` 均已在 `.gitignore` 中，不会入库。

## License

[MIT](LICENSE)

## 免责声明

- 本项目仅供个人学习与技术研究使用。
- 联通云盘（沃盘）部分基于对公开 Web 端的协议分析，请遵守对应服务条款，不要用于批量抓取、
  规避限速或其它违规用途；其中的 `CLIENT_ID` / `CLIENT_SECRET` 为官方客户端常量。
- 使用本机器人时请遵守所在平台规则，并注意不要泄露他人隐私数据。