roost-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,213 @@
+qq-bot-roost（栖 Roost）免费非商业许可协议 v2.0
+
+Copyright (c) 2026 tdcq9594
+
+本协议的结构参考 PolyForm Noncommercial License 1.0.0
+<https://polyformproject.org/licenses/noncommercial/1.0.0>，
+并按本项目「永久免费、禁止任何收费」的要求做了加严。
+
+================================================================
+一、接受
+================================================================
+
+要获得本协议授予的任何权利，你必须把本协议的全部条款
+作为你必须遵守的义务和获得许可的前提，完整地接受。
+
+================================================================
+二、定义
+================================================================
+
+「许可人」指提供本软件并给出本协议的个人或组织，即版权持有人。
+
+「本软件」指许可人在本协议下提供的软件，包括源代码、文档及其任何部分。
+
+「你」指接受本协议的个人或组织。
+
+「你的组织」指你受雇或任职的任何法律实体、个体经营者或其他形式的组织，
+以及控制该组织、受该组织控制、或与该组织处于共同控制之下的所有组织。
+「控制」指拥有某实体实质全部资产的所有权，或通过表决、合同或其他方式
+决定其管理与政策的权力，可以是直接或间接的。
+
+「使用」指你对本软件所做的、需要本协议授予许可的任何行为。
+
+================================================================
+三、永久免费，禁止任何收费
+================================================================
+
+本软件**永久免费提供**。
+
+任何个人或组织，在获取、使用或分发本软件（含原版、修改版及衍生作品）时，
+**不得收取任何形式的费用**，包括但不限于：
+
+  1. 软件本身的售价，或下载费、激活费、注册费；
+  2. 授权费、许可费、订阅费、会员费；
+  3. 以「技术支持」「培训」「咨询」「定制开发」等名义收取的费用；
+  4. 以「捐赠」「赞助」「打赏」等名义设置的付费门槛——
+     自愿且无附加条件的捐赠不属于收费，但不得将任何付费行为作为
+     获取或使用本软件的前提；
+  5. 通过捆绑销售、搭售或其他方式变相就本软件收费。
+
+简言之：这个软件必须免费，任何人都不能靠它收钱。
+
+================================================================
+四、许可授予
+================================================================
+
+**版权许可**：许可人授予你一项版权许可，允许你就本软件做一切
+在不获许可时会侵犯其版权的行为，但仅限于本协议允许的用途。
+你只能按第五条分发本软件，只能按第六条修改或创作新作品。
+
+**分发许可**：许可人额外授予你分发本软件副本的版权许可。
+你的分发许可涵盖分发经第六条允许的修改版和新作品。
+
+**专利许可**：许可人授予你一项专利许可，涵盖许可人能够许可、
+或将来能够许可的、你会因使用本软件而侵犯的专利权利要求。
+
+================================================================
+五、允许的用途
+================================================================
+
+以下用途均为本协议允许的用途：
+
+**非商业目的**：任何非商业性的目的。
+
+**个人使用**：为公共利益的知识增进、个人学习、私人娱乐、业余爱好、
+个人研究、试验与测试而使用，且**不带有任何预期的商业应用**。
+
+**非营利组织**：慈善组织、教育机构、公共研究机构、公共安全或公共卫生机构、
+环境保护组织、政府机构的使用，无论其资金来源如何、或资金附带何种义务。
+
+**合理使用**：你依法律可能享有的「合理使用」（fair use）权利不受本协议限制。
+
+================================================================
+六、修改与新作品
+================================================================
+
+许可人额外授予你一项版权许可，允许你为本协议允许的任何用途
+修改本软件、并基于本软件创作新作品。
+
+分发修改版或新作品时，必须：
+
+  1. 保留声明：完整保留本版权声明与本协议，不得删除或修改；
+  2. 沿用本协议：修改版和衍生作品必须继续适用本协议，不得改用更宽松的许可；
+  3. 标明修改：明确说明你对原作品做了哪些修改；
+  4. 不得背书：不得暗示许可人为你的产品或修改版提供担保或背书；
+  5. 保持免费：不得就本软件收取任何费用（见第三条）。
+
+================================================================
+七、禁止商业使用
+================================================================
+
+不得将本软件（含原版、修改版及衍生作品）用于任何商业目的。
+
+「商业目的」指以商业优势或金钱报酬为目的的任何用途，包括但不限于：
+
+  1. 出售、出租、许可本软件；
+  2. 将本软件作为收费服务、收费产品或收费功能的一部分提供；
+  3. 将本软件集成进以营利为目的的产品、系统或服务；
+  4. 通过本软件直接或间接获取广告收入、佣金、订阅费或其他商业收益；
+  5. 在你的组织内部用于其主营业务或经营活动。
+
+企业内部出于评估、测试目的的非生产性使用，不视为商业使用。
+
+================================================================
+八、不提供商业授权
+================================================================
+
+本软件**不提供任何形式的商业授权**。
+
+鉴于本协议禁止就本软件收取任何费用，也不允许任何商业使用，
+不存在通过付费取得商业使用权的途径。任何声称代表本项目出售授权、
+提供付费版本或收取商业许可费用的行为，均与许可人无关。
+
+================================================================
+九、通知义务
+================================================================
+
+你必须确保：任何从你处获得本软件任何部分副本的人，
+同时获得本协议的一份副本（或本协议的网址），
+以及许可人随本软件提供的、以「Required Notice:」开头的任何纯文本行。
+
+例如：
+
+> Required Notice: Copyright (c) 2026 tdcq9594
+
+================================================================
+十、专利防御
+================================================================
+
+如果你以书面形式主张本软件侵犯或协助侵犯任何专利，
+你依本协议获得的专利许可立即终止。如果你的组织提出此类主张，
+你为你的组织所做工作的专利许可立即终止。
+
+================================================================
+十一、无其他权利
+================================================================
+
+本协议不允许你再许可或转让你的任何许可给他人，
+也不阻止许可人向他人授予许可。本协议不暗示任何其他许可。
+
+================================================================
+十二、违约与补救
+================================================================
+
+你首次收到书面通知，指出你违反了本协议任何条款、
+或对本软件做了你的许可未涵盖的行为时，
+只要你在收到通知后 **32 天内**完全遵守本协议并采取实际步骤纠正此前的违约行为，
+你的许可仍可继续有效。
+
+逾期未补救的，你的全部许可立即终止。
+
+许可终止后，你必须停止使用本软件，并销毁你所持有的全部副本（含修改版）。
+终止不影响许可人就此前发生的违约行为追究责任。
+
+================================================================
+十三、免责
+================================================================
+
+在法律允许的最大范围内，本软件按「现状」提供，不附带任何明示或默示的
+担保或条件，包括但不限于对适销性、特定用途适用性、所有权和不侵权的担保。
+
+许可人不对因本协议、或因使用本软件及本软件的性质而产生的任何损害向你负责，
+无论基于何种法律主张，也无论是否已被告知此类损害的可能性。
+
+================================================================
+十四、附则
+================================================================
+
+本协议构成双方就本软件达成的完整约定。本协议任何条款被认定无效或
+不可执行时，不影响其余条款的效力。
+
+----------------------------------------------------------------
+English Summary (for reference only; the Chinese text above prevails)
+
+Copyright (c) 2026 tdcq9594. All rights reserved.
+
+This license follows the structure of the PolyForm Noncommercial License 1.0.0
+and adds a stricter no-fee requirement.
+
+The software is provided FREE OF CHARGE, PERMANENTLY. No one may charge any
+fee for it, in any form — sale price, download fee, activation fee, license
+fee, subscription, membership, paid support, training, customization, or any
+paid prerequisite for obtaining or using the software. Voluntary donations
+with no conditions attached are not a fee, but no payment may ever be required
+as a precondition for access or use.
+
+You may use, copy, modify and distribute the software for any permitted
+purpose. Permitted purposes include any noncommercial purpose, personal use
+for research, experiment, testing for the benefit of public knowledge,
+personal study, private entertainment, hobby projects, amateur pursuits or
+religious observance without any anticipated commercial application, and use
+by charitable, educational, public research, public safety or health,
+environmental protection, or government organizations.
+
+COMMERCIAL USE OF ANY KIND IS PROHIBITED. No commercial license is offered.
+
+You must pass these terms along with any copy, keep notices intact, disclose
+changes, distribute derivative works under the same terms, and imply no
+endorsement. If you first receive written notice of a violation, your licenses
+continue if you come into full compliance within 32 days.
+
+THE SOFTWARE COMES AS IS, WITHOUT ANY WARRANTY OR CONDITION, AND THE LICENSOR
+WILL NOT BE LIABLE FOR ANY DAMAGES ARISING OUT OF THESE TERMS OR THE USE OR
+NATURE OF THE SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# roost-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 [Roost](https://github.com/tdcq9594/qq-bot-roost) 的 QQ 能力做成 **MCP 工具**，
+让 Claude Desktop / Cursor / Cline / Continue / Windsurf 这些工作台能直接发 QQ 消息。
+
+方向跟 `ai-chat` 插件相反：
+
+| | 谁当大脑 | 干什么 |
+|---|---|---|
+| `ai-chat` 插件 | 工作台 | QQ 消息进来 → 工作台想 → 插件发出去 |
+| `roost-mcp` | 工作台 | 在工作台里说「帮我在群里发一句」→ 它调 QQ |
+
+两个可以同时用：`ai-chat` 负责「AI 住在群里」，`roost-mcp` 负责「你顺手让它发一句」。
+
+---
+
+## 前置
+
+Roost 要跑着，并且 ≥ 0.8.0（`POST /api/qq/call` 是这个版本加的）。
+
+---
+
+## 装
+
+### Claude Desktop
+
+`claude_desktop_config.json`：
+
+```jsonc
+{
+  "mcpServers": {
+    "qq": {
+      "command": "npx",
+      "args": ["-y", "roost-mcp"],
+      "env": {
+        "ROOST_URL": "http://127.0.0.1:8080",
+        "ROOST_KEY": "面板访问密钥"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Cline / 其他支持 MCP 的
+
+同样三件事：命令 `npx -y roost-mcp`、环境变量 `ROOST_URL` / `ROOST_KEY`。
+具体写在哪个配置文件里各家不同，看各自文档。
+
+### 本地调试
+
+```bash
+ROOST_URL=http://127.0.0.1:8080 ROOST_KEY=xxx node index.js
+# 然后在 stdin 里敲一行 JSON-RPC：
+{"jsonrpc":"2.0","id":1,"method":"tools/list"}
+```
+
+---
+
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `ROOST_URL` | `http://127.0.0.1:8080` | Roost 面板地址 |
+| `ROOST_KEY` | 空 | 面板访问密钥（`webui.accessKey`）。只监听本机时可以留空 |
+| `ROOST_BOT` | 空 | 多机器人时只操作这一个；留空 = 默认机器人 |
+
+---
+
+## 工具
+
+| 工具 | 干什么 |
+|---|---|
+| `qq_send` | 发文本 / Markdown / 图片到群或私聊 |
+| `qq_recall` | 撤回机器人自己发的消息 |
+| `qq_mute` | 群成员禁言 / 解除（需管理员） |
+| `qq_group_info` | 查群信息 |
+| `qq_capabilities` | 列出 Roost 封装了哪些官方接口（AI 不知道能调什么时先看这个） |
+| `qq_api` | 调其余任意官方接口，兜底 |
+
+`qq_api` 的参数约定：`__target` 是第一个位置参数，`__rest` 是后续位置参数，
+其余键合成一个对象追加在最后。危险操作（踢人、黑名单、审批策略）要 `confirm: true`。
+
+---
+
+## 设计说明
+
+**为什么不给 47 个接口各做一个工具**：AI 选不过来，也没人维护。
+六个工具 + 一个能力清单，剩下的靠 `qq_api` 兜底。官方加接口时，
+Roost 那边在 `endpoints.js` 加一行，这里零改动。
+
+**为什么日志走 stderr**：MCP 的 stdio 传输里 stdout 是协议通道，
+混一行日志客户端就解析失败。这是这类 server 最常见的坑。
+
+**为什么工具失败返回 `isError` 而不是抛异常**：让模型看到失败原因
+（比如「被动回复超限」），它才有机会换个做法；进程崩了就只能等用户重启。
+
+---
+
+## 测试
+
+```bash
+node test/mcp.test.mjs
+```
+
+起一个假 Roost，spawn 真的 MCP server，按协议发 JSON-RPC，验证：
+协议形状、stdout 里只有 JSON-RPC、工具失败走 `isError`、未知方法返回正确错误码。

package/index.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * roost-mcp —— 把 Roost 的 QQ 能力暴露成 MCP 工具。
+ *
+ * 方向跟 ai-chat 插件相反：
+ *   ai-chat     「工作台当大脑」——QQ 消息进来，工作台想，插件发出去
+ *   roost-mcp   「工作台当手脚」——在 Claude Desktop / Cursor 里说
+ *               「帮我在群里发一句」，它调这个 MCP server
+ *
+ * 走的是 Roost 内核的通用能力通道（`POST /api/qq/call`，v0.8.0 起）：
+ * 一个端点覆盖官方 47 个接口，白名单和风险分级在 Roost 那边，这里只负责转发。
+ *
+ * 零依赖：只用 node 内置的 fetch 和 stdio。
+ *
+ * 用法（Claude Desktop 的 claude_desktop_config.json）：
+ *   { "mcpServers": { "qq": {
+ *       "command": "npx", "args": ["-y", "roost-mcp"],
+ *       "env": { "ROOST_URL": "http://127.0.0.1:8080", "ROOST_KEY": "面板密钥" }
+ *   } } }
+ */
+
+import { createInterface } from 'node:readline';
+
+const BASE = String(process.env.ROOST_URL || 'http://127.0.0.1:8080').replace(/\/+$/, '');
+const KEY = String(process.env.ROOST_KEY || '');
+const BOT = String(process.env.ROOST_BOT || '');
+
+/** 日志必须走 stderr——stdout 是协议通道，混一个字节都会让客户端解析失败 */
+const log = (...a) => process.stderr.write(`[roost-mcp] ${a.join(' ')}\n`);
+
+/* ---------------- 调 Roost ---------------- */
+
+function qs() {
+  return KEY ? `?key=${encodeURIComponent(KEY)}` : '';
+}
+
+async function call(method, args = {}, confirm = false) {
+  const body = { method, args };
+  if (BOT) body.bot = BOT;
+  if (confirm) body.confirm = true;
+
+  const res = await fetch(`${BASE}/api/qq/call${qs()}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20000),
+  });
+
+  const text = await res.text();
+  let j = null;
+  try {
+    j = text ? JSON.parse(text) : null;
+  } catch {
+    throw new Error(`Roost 返回了非 JSON（HTTP ${res.status}）：${text.slice(0, 120)}`);
+  }
+  if (!res.ok || j?.ok === false) {
+    throw new Error(j?.error || `调用 ${method} 失败（HTTP ${res.status}）`);
+  }
+  return j?.result ?? j;
+}
+
+/* ---------------- 工具定义 ---------------- */
+
+const TOOLS = [
+  {
+    name: 'qq_send',
+    description:
+      '在 QQ 里发一条消息。可以发纯文本、Markdown，或者一张图片（给 URL）。'
+      + '群聊填 scene=group + 群的 openid；私聊填 scene=c2c + 用户 openid。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scene: { type: 'string', enum: ['group', 'c2c'], description: '群聊还是私聊' },
+        target: { type: 'string', description: '群 openid 或用户 openid' },
+        text: { type: 'string', description: '纯文本内容' },
+        markdown: { type: 'string', description: 'Markdown 内容，和 text 二选一' },
+        imageUrl: { type: 'string', description: '图片 URL，和 text/markdown 三选一' },
+      },
+      required: ['scene', 'target'],
+    },
+    async run(a) {
+      const method = a.scene === 'c2c' ? 'sendC2C' : 'sendGroup';
+
+      if (a.imageUrl) {
+        // uploadMedia(scene, target, opts) —— 三个位置参数
+        const up = await call('uploadMedia', {
+          __target: a.scene,
+          __rest: [a.target, { fileType: 1, url: a.imageUrl }],
+        });
+        if (!up?.file_info) throw new Error('图片上传没拿到 file_info');
+        return call(method, {
+          __target: a.target,
+          msgType: 7,
+          content: ' ',
+          media: { file_info: up.file_info },
+        });
+      }
+      if (a.markdown) {
+        return call(method, { __target: a.target, markdown: { content: String(a.markdown) } });
+      }
+      if (!a.text) throw new Error('text / markdown / imageUrl 至少给一个');
+      return call(method, { __target: a.target, content: String(a.text) });
+    },
+  },
+
+  {
+    name: 'qq_recall',
+    description: '撤回一条机器人自己发的消息。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scene: { type: 'string', enum: ['group', 'c2c'] },
+        target: { type: 'string', description: '群 openid 或用户 openid' },
+        messageId: { type: 'string', description: '要撤回的消息 id' },
+      },
+      required: ['scene', 'target', 'messageId'],
+    },
+    run: (a) =>
+      call(a.scene === 'c2c' ? 'retractC2CMessage' : 'retractGroupMessage', {
+        __target: a.target,
+        __rest: [a.messageId],
+      }),
+  },
+
+  {
+    name: 'qq_mute',
+    description: '群成员禁言 / 解除禁言。需要机器人是群管理员。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        groupId: { type: 'string', description: '群 openid' },
+        memberOpenid: { type: 'string', description: '成员的 openid' },
+        durationSec: { type: 'number', description: '禁言秒数，0 表示解除' },
+      },
+      required: ['groupId', 'memberOpenid', 'durationSec'],
+    },
+    run: (a) =>
+      call('muteMembers', {
+        __target: a.groupId,
+        __rest: [[{ memberOpenid: a.memberOpenid, durationSec: a.durationSec }]],
+      }),
+  },
+
+  {
+    name: 'qq_group_info',
+    description: '查群基本信息（群名、人数等）。',
+    inputSchema: {
+      type: 'object',
+      properties: { groupId: { type: 'string', description: '群 openid' } },
+      required: ['groupId'],
+    },
+    run: (a) => call('getGroupInfo', { __target: a.groupId }),
+  },
+
+  {
+    name: 'qq_capabilities',
+    description:
+      '列出 Roost 封装了哪些官方接口（方法名、风险等级、限制）。'
+      + '不知道有什么能调的时候先看这个。',
+    inputSchema: { type: 'object', properties: {} },
+    async run() {
+      const res = await fetch(`${BASE}/api/qq/capabilities${qs()}`, { signal: AbortSignal.timeout(10000) });
+      if (!res.ok) throw new Error(`取能力清单失败（HTTP ${res.status}）`);
+      const list = await res.json();
+      return { count: Array.isArray(list) ? list.length : 0, endpoints: list };
+    },
+  },
+
+  {
+    name: 'qq_api',
+    description:
+      '直接调 Roost 封装的其他官方接口。参数用 __target 传第一个位置参数，'
+      + '__rest 传后续位置参数，其余键会合成一个对象追加在最后。'
+      + '危险操作（踢人、黑名单、审批策略）需要 confirm=true。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        method: { type: 'string', description: '方法名，如 createPanel / getGroupMembers' },
+        args: { type: 'object', description: '参数对象' },
+        confirm: { type: 'boolean', description: '危险操作确认' },
+      },
+      required: ['method'],
+    },
+    run: (a) => call(a.method, a.args ?? {}, a.confirm === true),
+  },
+];
+
+/* ---------------- MCP 协议 ---------------- */
+
+const PROTOCOL = '2024-11-05';
+
+function reply(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+
+  // 通知类没有 id，不用回
+  if (id === undefined || id === null) {
+    if (method === 'notifications/initialized') log('客户端已初始化');
+    return;
+  }
+
+  try {
+    switch (method) {
+      case 'initialize':
+        return reply(id, {
+          protocolVersion: PROTOCOL,
+          capabilities: { tools: {} },
+          serverInfo: { name: 'roost-mcp', version: '0.1.0' },
+        });
+
+      case 'ping':
+        return reply(id, {});
+
+      case 'tools/list':
+        return reply(id, {
+          tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+        });
+
+      case 'tools/call': {
+        const name = params?.name;
+        const tool = TOOLS.find((t) => t.name === name);
+        if (!tool) return replyError(id, -32602, `没有这个工具：${name}`);
+        try {
+          const out = await tool.run(params?.arguments ?? {});
+          return reply(id, { content: [{ type: 'text', text: JSON.stringify(out ?? {}, null, 2) }] });
+        } catch (e) {
+          // 工具执行失败按协议用 isError 返回，让模型看到原因而不是崩掉
+          return reply(id, { content: [{ type: 'text', text: `出错了：${e.message}` }], isError: true });
+        }
+      }
+
+      default:
+        return replyError(id, -32601, `不认识的方法：${method}`);
+    }
+  } catch (e) {
+    log('处理失败：', e?.message ?? e);
+    return replyError(id, -32603, e?.message ?? '内部错误');
+  }
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on('line', (line) => {
+  const t = line.trim();
+  if (!t) return;
+  let msg;
+  try {
+    msg = JSON.parse(t);
+  } catch {
+    log('收到非 JSON 的一行，忽略');
+    return;
+  }
+  Promise.resolve(handle(msg)).catch((e) => log('未捕获：', e?.message ?? e));
+});
+
+rl.on('close', () => process.exit(0));
+
+log(`就绪：${BASE}${BOT ? `（只操作 ${BOT}）` : ''}`);

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "roost-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server：把 Roost 的 QQ 能力暴露给 Claude Desktop / Cursor / 任何支持 MCP 的工作台",
+  "type": "module",
+  "bin": {
+    "roost-mcp": "index.js"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/mcp.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "qq",
+    "roost"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tdcq9594/qq-bot-roost-plugins.git",
+    "directory": "packages/roost-mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}