@reglow/review-mcp 0.1.0

package/index.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * review-mcp —— ReView 组件库 MCP 服务器（stdio）
+ *
+ * 让 AI 助手在写 ReView（uni-app x / uts / uvue）代码时「有据可查」：组件文档、代码示例、
+ * 源码文件、函数实现、跨库检索与库级指南，全部来自本地 ReView 仓库
+ * （或运行目录下的 `uni_modules/reglow-review`，官方文档站点兜底）。
+ *
+ * 用法（客户端 mcpServers 配置中作为 command + args）：
+ *   npx -y @reglow/review-mcp                     # 自动识别本地仓库 / uni_modules，文档缺失时走官网兜底
+ *   npx -y @reglow/review-mcp --root D:/path/to/review   # 指定工作区（开发组件库时）
+ *   npx -y @reglow/review-mcp --check             # 自检：打印知识源与组件数量后退出
+ *   npx -y @reglow/review-mcp --setup             # 为 Trae/CodeBuddy/Qoder 一键写 MCP 配置 + 装 Skills
+ *   npx -y @reglow/review-mcp --install-skills    # 仅安装 Skills 知识包（等价于 review-skills）
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createKnowledgeResolver, createServer } from "./server.mjs";
+import { NPM_NOT_PUBLISHED_HINT } from "./knowledge.mjs";
+import { installSkills, mcpConfigSnippet, runSkillsCli } from "./skills.mjs";
+import { DEFAULT_SETUP_TOOLS } from "./integrations.mjs";
+import { renderToolList, runSetupCli } from "./setup.mjs";
+
+const PACKAGE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const OWN_PACKAGE = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf8"),
+);
+
+const USAGE = [
+  `review-mcp v${OWN_PACKAGE.version} —— ReView（uni-app x）组件库 MCP 服务器`,
+  "",
+  "用法：review-mcp [选项]",
+  "",
+  "选项：",
+  "      --root <dir>              ReView 仓库工作区路径（未指定时自动识别仓库 / 项目内的 uni_modules/reglow-review）",
+  "      --version <ver>           指定知识版本；因 @reglow/review 未发布 npm，只会给出提示",
+  "      --no-site                 禁用官方文档站点兜底（完全离线）",
+  "      --check                   自检：打印知识源、版本与组件数量后退出",
+  `      --setup [tools]           一键配置 AI 工具（MCP 配置 + Skills），默认 ${DEFAULT_SETUP_TOOLS.join(",")}`,
+  "                                例：--setup trae,codebuddy,qoder / --setup all；支持 --scope user --dry-run --force",
+  "      --install-skills          仅安装 Skills 知识包（可配合 --target / --all / --force）",
+  "      --list-tools              列出支持的工具、MCP 配置路径与 Skills 目录",
+  "      --print-config            打印 MCP 客户端配置片段后退出",
+  "  -v, --version                 打印本包版本号（不带值时）",
+  "  -h, --help                    显示帮助",
+  "",
+  `说明：${NPM_NOT_PUBLISHED_HINT}`,
+  "",
+  "MCP 客户端配置示例（Trae / Cursor / Claude Desktop 的 mcpServers）：",
+  JSON.stringify(mcpConfigSnippet(), null, 2),
+].join("\n");
+
+function parseArgs(argv) {
+  const options = {
+    root: undefined,
+    knowledgeVersion: undefined,
+    allowSite: true,
+  };
+  const passthrough = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--root") options.root = argv[++i];
+    else if (arg.startsWith("--root="))
+      options.root = arg.slice("--root=".length);
+    else if (arg === "--version" || arg === "--default-version") {
+      const value = argv[i + 1];
+      if (value && !value.startsWith("-")) {
+        options.knowledgeVersion = value;
+        i += 1;
+      } else {
+        options.ownVersion = true;
+      }
+    } else if (arg.startsWith("--version=")) {
+      options.knowledgeVersion = arg.slice("--version=".length);
+    } else if (arg.startsWith("--default-version=")) {
+      options.knowledgeVersion = arg.slice("--default-version=".length);
+    } else if (arg === "--no-site") options.allowSite = false;
+    else if (arg === "--check") options.check = true;
+    else if (arg === "--print-config") options.printConfig = true;
+    else if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "-v") options.ownVersion = true;
+    else passthrough.push(arg);
+  }
+  options.passthrough = passthrough;
+  return options;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  // 工具配置命令（`--setup [tools]` / `setup [tools]`）
+  if (argv.includes("--setup") || argv[0] === "setup") {
+    const index = argv.findIndex((arg) => arg === "--setup" || arg === "setup");
+    // 去掉 --setup 本体，其余参数（含位置形式的目标工具清单）原样交给 review-setup
+    process.exitCode = runSetupCli(argv.filter((_, i) => i !== index));
+    return;
+  }
+
+  if (argv.includes("--list-tools")) {
+    console.log(renderToolList({ cwd: process.cwd() }));
+    return;
+  }
+
+  // Skills 安装命令（支持 `--install-skills` 与 `install-skills` 两种写法）
+  if (argv.includes("--install-skills") || argv[0] === "install-skills") {
+    const rest = argv.filter(
+      (arg) => arg !== "--install-skills" && arg !== "install-skills",
+    );
+    process.exitCode = runSkillsCli(rest);
+    return;
+  }
+
+  const options = parseArgs(argv);
+  if (options.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (options.ownVersion) {
+    console.log(OWN_PACKAGE.version);
+    return;
+  }
+  if (options.printConfig) {
+    console.log(JSON.stringify(mcpConfigSnippet(), null, 2));
+    return;
+  }
+
+  const logger = (message) => console.error(message);
+  if (options.knowledgeVersion) {
+    logger(`[review-mcp] ⚠️ ${NPM_NOT_PUBLISHED_HINT}`);
+  }
+  const resolveKnowledge = createKnowledgeResolver({
+    root: options.root,
+    allowSite: options.allowSite,
+    logger,
+  });
+  const knowledge = await resolveKnowledge(options.knowledgeVersion);
+
+  if (options.check) {
+    const meta = knowledge.meta();
+    const components = knowledge.listComponents();
+    console.log(
+      JSON.stringify(
+        {
+          package: OWN_PACKAGE.name,
+          packageVersion: OWN_PACKAGE.version,
+          knowledgeSource: meta.source,
+          reviewVersion: meta.version,
+          versionDate: meta.versionDate,
+          versionSource: meta.versionSource,
+          root: meta.root,
+          warning: meta.warning,
+          componentCount: components.length,
+          documentedCount: knowledge.catalog.documentedCount,
+          categories: knowledge.catalog.categories.map((group) => ({
+            key: group.key,
+            label: group.label,
+            count: group.components.length,
+          })),
+          components: components.map((entry) => entry.name),
+          allowSiteFallback: options.allowSite,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (options.allowSite === false) {
+    logger("[review-mcp] 已禁用官方文档站点兜底（--no-site）");
+  }
+  const server = createServer({
+    resolveKnowledge,
+    defaultKnowledge: knowledge,
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger(
+    `[review-mcp] 已启动：knowledge=${knowledge.meta().source} version=${knowledge.meta().version} ` +
+    `components=${knowledge.listComponents().length}`,
+  );
+}
+
+main().catch((error) => {
+  console.error(`[review-mcp] 启动失败：${error?.stack ?? error}`);
+  process.exitCode = 1;
+});
+
+export { installSkills };

package/integrations.mjs

@@ -0,0 +1,270 @@
+/**
+ * AI 工具的集成规格（Trae / CodeBuddy / Qoder 等）
+ *
+ * 数据来自各工具官方文档（2026-09 核对），用于：
+ * - `review-setup` 一键写入 MCP 配置 + 安装 Skills；
+ * - `review-skills` 的 `--list` 展示；
+ * - 文档与错误提示中的「手动步骤」说明。
+ *
+ * 参考：
+ * - Trae：https://docs.trae.cn/ide/add-mcp-servers （项目级 `.trae/mcp.json`，需在设置中开启「启用项目级 MCP」）
+ * - CodeBuddy：https://www.codebuddy.ai/docs/cli/mcp （项目级 `.mcp.json`，支持 JSONC）
+ *              https://www.codebuddy.ai/docs/zh/cli/skills （`.codebuddy/skills/`）
+ * - Qoder：https://docs.qoder.com/zh/cli/mcp-reference （项目级 `.mcp.json` / `.qoder/settings.json`，需批准）
+ *          https://docs.qoder.com/cli/Skills （`.qoder/skills/`）
+ */
+
+/** MCP 服务器名（写入 mcpServers 的 key） */
+export const DEFAULT_SERVER_NAME = "review-mcp";
+
+/** npm 包名（npx 启动用） */
+export const MCP_PACKAGE = "@reglow/review-mcp";
+
+/** 默认的 stdio 启动参数 */
+export const DEFAULT_ARGS = ["-y", MCP_PACKAGE];
+
+/** 本 MCP 服务器在配置中的描述 */
+const SERVER_DESCRIPTION =
+  "ReView（uni-app x / uts / uvue）移动端组件库：文档 / 示例 / 源码 / 函数查询（@reglow/review-mcp）";
+
+/**
+ * 各工具集成规格
+ *
+ * - `skills.projectDir`：项目级 Skills 目录（相对项目根）
+ * - `skills.userDir`：用户级 Skills 目录（`~` 表示用户主目录）
+ * - `mcp.projectFile`：项目级 MCP 配置文件（相对项目根）
+ * - `mcp.userFile`：用户级 MCP 配置文件（可按平台覆盖）
+ * - `mcp.jsonc`：配置文件是否允许注释 / 尾逗号（合并时会先做 JSONC 解析）
+ * - `mcp.explicitType`：写入条目时是否带 `type: "stdio"`
+ * - `mcp.manualSteps`：一键写入后仍需人工完成的步骤
+ */
+export const TOOL_INTEGRATIONS = {
+  trae: {
+    label: "Trae",
+    docsUrl: "https://docs.trae.cn/ide/add-mcp-servers",
+    skills: { projectDir: ".trae/skills", userDir: "~/.trae/skills" },
+    mcp: {
+      projectFile: ".trae/mcp.json",
+      userFile: {
+        win32: "%APPDATA%/Trae/User/mcp.json",
+        darwin: "~/Library/Application Support/Trae/User/mcp.json",
+        linux: "~/.config/Trae/User/mcp.json",
+      },
+      explicitType: false,
+      manualSteps: [
+        "Trae 设置 → MCP：打开「启用项目级 MCP」开关（首次使用项目级配置必须开启）",
+        "若改用用户级配置：设置 → MCP → 添加 → 手动添加，或直接编辑上述用户级 mcp.json",
+      ],
+      notes: [
+        "stdio 配置中 command 不能包含空格",
+        "支持 ${workspaceFolder} 变量与 START_MCP_TIMEOUT_MS / RUN_MCP_TIMEOUT_MS 超时环境变量",
+      ],
+    },
+  },
+  codebuddy: {
+    label: "CodeBuddy",
+    docsUrl: "https://www.codebuddy.ai/docs/cli/mcp",
+    skills: { projectDir: ".codebuddy/skills", userDir: "~/.codebuddy/skills" },
+    mcp: {
+      projectFile: ".mcp.json",
+      userFile: "~/.codebuddy/.mcp.json",
+      jsonc: true,
+      explicitType: true,
+      manualSteps: [
+        "IDE：对话面板右上 CodeBuddy Settings → MCP → Add MCP，把 .mcp.json 里的 review-mcp 条目粘贴进去（IDE 不走项目文件）",
+        "CLI：项目级 `.mcp.json` 直接生效，可用 `/mcp` 查看连接状态",
+      ],
+      notes: [
+        "项目级优先读 `.mcp.json`，其次 `mcp.json`（已弃用）",
+        "支持 JSONC（注释 / 尾逗号）；同名服务器优先级 local > project > user",
+        '如需免确认，可在 settings.json 配 permissions.allow: ["mcp__review-mcp__*"]',
+      ],
+    },
+  },
+  qoder: {
+    label: "Qoder",
+    docsUrl: "https://docs.qoder.com/zh/cli/mcp-reference",
+    skills: { projectDir: ".qoder/skills", userDir: "~/.qoder/skills" },
+    mcp: {
+      projectFile: ".mcp.json",
+      alternativeProjectFile: ".qoder/settings.json",
+      userFile: "~/.qoder/settings.json",
+      explicitType: true,
+      manualSteps: [
+        "项目级 MCP 默认需要批准：首次调用时确认，或在 settings.json 中设置 mcp.enableAllProjectMcpServers: true",
+        "CLI 也可直接执行：qoder mcp add review-mcp -s project -- npx -y @reglow/review-mcp",
+        "修改后如 CLI 正在运行，执行 /mcp reload 重新发现",
+      ],
+      notes: [
+        "同名服务器覆盖顺序：用户级 → 项目级 settings.json → 项目级 .mcp.json → 本地级 → CLI 参数",
+        "可选用 trust / alwaysAllow / includeTools / excludeTools 控制权限",
+      ],
+    },
+  },
+  cursor: {
+    label: "Cursor",
+    docsUrl: "https://docs.cursor.com/context/model-context-protocol",
+    skills: { projectDir: ".cursor/skills", userDir: "~/.cursor/skills" },
+    mcp: {
+      projectFile: ".cursor/mcp.json",
+      userFile: "~/.cursor/mcp.json",
+      explicitType: false,
+      manualSteps: ["Cursor 设置 → MCP 中确认 review-mcp 已启用"],
+      notes: [],
+    },
+  },
+  claude: {
+    label: "Claude Code",
+    docsUrl: "https://docs.claude.com/en/docs/claude-code/mcp",
+    skills: { projectDir: ".claude/skills", userDir: "~/.claude/skills" },
+    mcp: {
+      projectFile: ".mcp.json",
+      userFile: {
+        win32: "%APPDATA%/Claude/claude_desktop_config.json",
+        darwin: "~/Library/Application Support/Claude/claude_desktop_config.json",
+        linux: "~/.config/Claude/claude_desktop_config.json",
+      },
+      explicitType: false,
+      manualSteps: ["也可执行：claude mcp add review-mcp -- npx -y @reglow/review-mcp"],
+      notes: [],
+    },
+  },
+  generic: {
+    label: "通用 .skills 目录",
+    docsUrl: "https://modelcontextprotocol.io/",
+    skills: { projectDir: ".skills", userDir: null },
+    mcp: {
+      projectFile: ".mcp.json",
+      userFile: null,
+      explicitType: true,
+      manualSteps: [
+        "按你所用的 MCP 客户端文档，把 .mcp.json 中的 mcpServers.review-mcp 条目加入其配置",
+      ],
+      notes: [],
+    },
+  },
+};
+
+/** 默认一键配置的目标（用户重点关注的三个工具） */
+export const DEFAULT_SETUP_TOOLS = ["trae", "codebuddy", "qoder"];
+
+/** 全部可配置工具（`--setup all`） */
+export const ALL_TOOLS = Object.keys(TOOL_INTEGRATIONS);
+
+/** 工具名归一化（大小写 / 别名） */
+export function normalizeTool(name) {
+  const key = String(name ?? "")
+    .trim()
+    .toLowerCase();
+  if (key === "trae" || key === "trae-ide" || key === "traecli") return "trae";
+  if (
+    key === "codebuddy" ||
+    key === "code-buddy" ||
+    key === "tencent-codebuddy"
+  )
+    return "codebuddy";
+  if (key === "qoder" || key === "qoder-cli") return "qoder";
+  if (key === "claude" || key === "claude-code" || key === "claude-desktop")
+    return "claude";
+  if (key === "cursor") return "cursor";
+  if (key === "generic" || key === "mcp" || key === "all-mcp") return "generic";
+  return key;
+}
+
+/** 解析工具清单字符串（`trae,codebuddy,qoder` / `all`） */
+export function parseTools(input) {
+  if (!input) return [...DEFAULT_SETUP_TOOLS];
+  const raw = String(input)
+    .split(/[,\s]+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (raw.length === 0) return [...DEFAULT_SETUP_TOOLS];
+  const expanded = raw.includes("all") ? ALL_TOOLS : raw;
+  const tools = [];
+  for (const item of expanded) {
+    const tool = normalizeTool(item);
+    if (!TOOL_INTEGRATIONS[tool]) {
+      throw new Error(`未知工具「${item}」，可选：${ALL_TOOLS.join(" / ")}`);
+    }
+    if (!tools.includes(tool)) tools.push(tool);
+  }
+  return tools;
+}
+
+/** 展开 `~` 与 `%VAR%` / `$VAR`，得到绝对路径（统一使用 `/` 分隔，Windows 下 Node 同样接受） */
+export function expandPath(
+  target,
+  { cwd = process.cwd(), env = process.env, platform = process.platform } = {},
+) {
+  let value = String(target ?? "");
+  value = value.replace(/%([^%]+)%/g, (_m, name) => env[name] ?? `%${name}%`);
+  if (value.startsWith("~/") || value === "~") {
+    const home = env.USERPROFILE || env.HOME || cwd;
+    value = value.replace(/^~/, home);
+  }
+  if (!value) return null;
+  const combined = /^([a-zA-Z]:[\\/]|[\\/]{1,2})/.test(value)
+    ? value
+    : `${cwd}/${value}`;
+  return combined
+    .replace(/\\/g, "/")
+    .replace(/\/{2,}/g, "/")
+    .replace(/^([a-zA-Z]):\//, "$1:/");
+}
+
+/** 取某工具在指定 scope 下的配置文件绝对路径 */
+export function resolveConfigPath(tool, scope = "project", options = {}) {
+  const spec = TOOL_INTEGRATIONS[tool];
+  if (!spec) throw new Error(`未知工具「${tool}」`);
+  const cwd = options.cwd ?? process.cwd();
+  const platform = options.platform ?? process.platform;
+  if (scope === "user") {
+    const userFile = spec.mcp.userFile;
+    if (!userFile) return null;
+    const raw = typeof userFile === "string" ? userFile : userFile[platform];
+    if (!raw) return null;
+    return expandPath(raw, { ...options, cwd });
+  }
+  return expandPath(spec.mcp.projectFile, { ...options, cwd });
+}
+
+/** 取某工具在指定 scope 下的 Skills 目录绝对路径 */
+export function resolveSkillsDir(tool, scope = "project", options = {}) {
+  const spec = TOOL_INTEGRATIONS[tool];
+  if (!spec) throw new Error(`未知工具「${tool}」`);
+  const cwd = options.cwd ?? process.cwd();
+  const dir = scope === "user" ? spec.skills.userDir : spec.skills.projectDir;
+  if (!dir) return null;
+  return expandPath(dir, { ...options, cwd });
+}
+
+/**
+ * 构造写入 mcpServers 的服务器条目
+ *
+ * @param {string} tool 工具名
+ * @param {{ args?: string[], env?: Record<string, string> }} [options]
+ */
+export function buildMcpEntry(tool, options = {}) {
+  const spec = TOOL_INTEGRATIONS[tool];
+  if (!spec) throw new Error(`未知工具「${tool}」`);
+  const entry = {
+    command: "npx",
+    args: [...(options.args ?? DEFAULT_ARGS)],
+  };
+  if (spec.mcp.explicitType) {
+    entry.type = "stdio";
+    entry.description = SERVER_DESCRIPTION;
+  }
+  if (options.env && Object.keys(options.env).length > 0)
+    entry.env = { ...options.env };
+  return entry;
+}
+
+/** `review-skills --list` 用的目标表（兼容旧行为：预设名 → 目录） */
+export function skillTargetsFromIntegrations() {
+  const targets = {};
+  for (const [tool, spec] of Object.entries(TOOL_INTEGRATIONS)) {
+    targets[tool] = { dir: spec.skills.projectDir, label: spec.label };
+  }
+  return targets;
+}