qq-onebot-mcp

軽量 MCPサーバー：QQ（NapCat / OneBot 11）を任意の MCP ホスト（DSH、Claude、Cursor…）に接続します。 npm 依存ゼロ、純粋な Node.js ≥ 20、内蔵 WebSocket のみ使用。

• プライベートチャット（ホワイトリスト管理者）→ メッセージは inbox へ → ホスト agent が処理（完全なツール権限）→ 返信。

• グループチャット @bot（ホワイトリストグループ）→ ブリッジが直接 LLM API で回答、agent を経由せず、ローカルに触れません。

アーキテクチャ

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. オンライン：agent に「QQにログインして」と指示 → skills/qq-online/SKILL.md に従って attach → メッセージを待つ → 返信。

.env は git で無視されています。絶対にコミットしないでください。

MCP ツール

待機モード：サーバー起動時は NapCat に接続せず、qq_attach で接続、qq_detach で切断 —— リソース消費ゼロ。

全自動クローズドループ（オプション）

QQ メッセージで agent を自動起動させたい場合（毎回「ログイン」と言わなくて済む）：独立プロセスで 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 回复

• リスナーは agent セッションから独立して常駐。session.prompt（mode: queue）でメッセージをホストセッションに注入しターンをトリガー。

• 返信は <workdir>/outbox/*.json（{type:"send", message}）に配置。リスナーが送信（chat target がない場合は OneBot WS に直接接続）。

• グレースフル停止：<workdir> に stop.flag を書き込む。

⚠️ session.prompt は認証なし・ループバック限定。ローカルの信頼できる環境でのみ使用してください。

セキュリティ

• プライベートチャット：ホワイトリストのみ。見知らぬプライベートチャットは破棄。

• グループチャット：純 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        # 配置模板

License

MIT