@reglow/reui-mcp 0.1.0

package/integrations.mjs

@@ -0,0 +1,273 @@
+/**
+ * AI 工具的集成规格（Trae / CodeBuddy / Qoder 等）
+ *
+ * 数据来自各工具官方文档（2026-09 核对），用于：
+ * - `reui-setup` 一键写入 MCP 配置 + 安装 Skills；
+ * - `reui-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 = "reui-mcp";
+
+/** npm 包名（npx 启动用） */
+export const MCP_PACKAGE = "@reglow/reui-mcp";
+
+/** 默认的 stdio 启动参数 */
+export const DEFAULT_ARGS = ["-y", MCP_PACKAGE];
+
+/** 本 MCP 服务器在配置中的描述 */
+const SERVER_DESCRIPTION =
+  "ReUI 组件库文档 / 示例 / 源码 / 函数查询（@reglow/reui-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 里的 reui-mcp 条目粘贴进去（IDE 不走项目文件）",
+        "CLI：项目级 `.mcp.json` 直接生效，可用 `/mcp` 查看连接状态",
+      ],
+      notes: [
+        "项目级优先读 `.mcp.json`，其次 `mcp.json`（已弃用）",
+        "支持 JSONC（注释 / 尾逗号）；同名服务器优先级 local > project > user",
+        '如需免确认，可在 settings.json 配 permissions.allow: ["mcp__reui-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 reui-mcp -s project -- npx -y @reglow/reui-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 中确认 reui-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 reui-mcp -- npx -y @reglow/reui-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.reui-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 {{ serverName?: string, 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;
+}
+
+/** `reui-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;
+}