qq-onebot-mcp

Легковесный MCP-сервер: подключает QQ (NapCat / OneBot 11) к любому MCP-хосту (DSH, Claude, Cursor…). Ноль npm-зависимостей, чистый Node.js ≥ 20, только встроенный WebSocket.

• Личные сообщения (белый список владельца) → сообщение попадает в inbox → агент хоста обрабатывает (полные права на инструменты) → ответ.

• Групповой чат @бота (белый список групп) → мост отвечает напрямую через LLM API, минуя агента и не касаясь локальной машины.

Архитектура

QQ 老大 ──私聊──▶ NapCat(QQ小号) ──OneBot11/WS:3001──▶ qq-mcp-server.mjs ──MCP──▶ 宿主 agent
                                                                   ▲
                                                              (inbox / 工具)

Related MCP server: NapCat MCP Server

Быстрый старт

1. NapCat: установите и войдите в QQ-аккаунт-болванку, включите OneBot WS (по умолчанию ws://127.0.0.1:3001).

2. Конфигурация: cp .env.example .env, заполните QQ_BOT, QQ_ALLOWED_SENDERS (можно добавить LLM_API_KEY для группового чата).

3. Регистрация MCP: хост указывает на qq-mcp-server.mjs (stdio). Для DSH используйте шаблон dsh-bundle/, см. INSTALL-DSH.md.

4. Вход: скажите агенту «зайди в QQ» → следуйте skills/qq-online/SKILL.md для attach → ждите сообщения → отвечайте.

.env в git-игноре, никогда не коммитьте.

MCP-инструменты

Режим ожидания: сервер при запуске не подключается к NapCat, подключение происходит только при qq_attach, отключение — при qq_detach — нулевое потребление ресурсов.

Полностью автоматический замкнутый цикл (опционально)

Хотите, чтобы QQ-сообщения автоматически будили агента (без необходимости каждый раз говорить «зайди»): запустите qq-listener.mjs как отдельный процесс:

DSH_API_URL=http://127.0.0.1:3080 DSH_SESSION_ID=<session-id> \
  node qq-listener.mjs <tag> <workdir> 0

QQ 消息 → 监听器(wait_inbox) → 写入 <workdir>/inbox/ + POST http://127.0.0.1:3080/api/session.prompt
                                                                        │
                                                    agent 自动醒来处理 → <workdir>/outbox/ → qq_send 回复

• Слушатель работает постоянно независимо от сессии агента; session.prompt (mode: queue) инъектирует сообщение в сессию хоста, запуская раунд.

• Ответы кладутся в <workdir>/outbox/*.json ({type:"send", message}), слушатель отправляет их (при отсутствии chat target — напрямую через OneBot WS).

• Корректная остановка: запишите stop.flag в <workdir>.

⚠️ session.prompt не имеет аутентификации и работает только на loopback — используйте только в доверенном локальном окружении.

Безопасность

• Личные сообщения: только белый список; незнакомые личные сообщения отбрасываются.

• Групповой чат: чистый LLM, никогда не касается локальных файлов/команд.

• qq_send может отвечать только текущему собеседнику (в белом списке).

• Пользователь из белого списка добавляет бота в группу → автоматическое добавление в белый список и объявление.

Персонализация

Отредактируйте AGENTS.md (личность/обязанности/границы безопасности), мост перезагружает его в каждой сессии, без перезапуска.

Локальные приватные данные (например, важные личные связи) можно положить в data/ (git-игнор) и указать на них в AGENTS_MD — на GitHub не попадут.

Динамическое обнаружение сессии (замкнутый цикл)

Слушатель больше не зашивает DSH_SESSION_ID: при каждом сообщении сначала вызывает session.list, чтобы найти сессию со статусом running + заголовок содержит 上号/QQ/布卡, если не находит — откатывается на env. Так замкнутый цикл продолжает работать, даже если сессию «зайди» заменили или переоткрыли.

Разработка

npm test   # 全部入口语法检查

Файлы

├── qq-mcp-server.mjs   # MCP server（主入口）
├── onebot.mjs          # OneBot WS 客户端
├── group_llm.mjs       # 群聊 LLM 直答
├── bridge.mjs          # 独立触发桥（无 MCP 宿主）
├── bridge-acp.mjs      # ACP 连接器（持久 DSH 会话）
├── qq-listener.mjs     # 闭环监听器
├── qqctl.mjs           # 进程控制
├── dsh-bundle/         # DSH profile bundle 模板
├── skills/qq-online/   # 「上QQ号」技能
├── INSTALL-DSH.md      # 新用户自装指南
└── .env.example        # 配置模板

Лицензия

MIT