@luckychen1993/pm-mcp 0.1.1 → 0.1.2

package/README.md

@@ -29,44 +29,58 @@ AI 编码项目的典型失控（本工具逐一给出机制）：
 | 法律知识产权 | `audit_license` 依赖许可证/copyleft 冲突 + 来源登记（provenance） |
 | 测试投机（删测试、skip 凑绿） | 禁用/蒸发/空测试检测 + 功能测试背书占比 + done 必附验证 |
 
-## 一键添加到 AI 编程助手
+## 一个命令自动添加到 AI 编程助手
 
-要求：Node.js ≥ 22.18。下面的配置固定到 npm 版本 `0.1.1`；首次启动由 `npx` 下载并在本机运行，pm-mcp 本身不需要 API Key，也不会调用远程模型。
+要求：Node.js ≥ 22.18。Windows、macOS 和 Linux 使用同一条命令：
 
-### Codex / ChatGPT 桌面版 / Codex IDE 扩展
+```bash
+npx -y @luckychen1993/pm-mcp@latest setup
+```
+
+安装器自动检测本机的 Codex、Claude Code、ZCode、Cursor 和 VS Code，并配置所有检测到的客户端。JSON 配置会先备份；已经存在的 Codex/Claude 配置默认保留，用 `setup --force` 才替换。先预览、不写配置：
+
+```bash
+npx -y @luckychen1993/pm-mcp@latest setup --dry-run
+```
+
+非标准安装路径无法自动发现时，可在同一命令末尾指定 `--client codex|claude|zcode|cursor|vscode`；`--client print` 输出通用 MCP JSON。首次启动由 `npx` 下载并在本机运行，pm-mcp 本身不需要 API Key，也不会调用远程模型。
+
+### 客户端官方命令（自动检测失败时备用）
+
+#### Codex / ChatGPT 桌面版 / Codex IDE 扩展
 
 Codex 的本地客户端共享同一份 MCP 配置。复制执行：
 
 ```bash
-codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.1
+codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.2
 ```
 
 重启客户端后可用 `codex mcp list` 检查。该命令遵循 [OpenAI 官方 MCP CLI 格式](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)。
 
-### Claude Code
+#### Claude Code
 
 ```bash
-claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.1
+claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.2
 ```
 
-### ZCode、Cursor、VS Code（Windows 一键脚本）
+#### ZCode、Cursor、VS Code（Windows 备用脚本）
 
 将 `<client>` 替换为 `zcode`、`cursor` 或 `vscode`，整行复制到 PowerShell：
 
 ```powershell
-$u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.1/install.ps1'; $f=Join-Path $env:TEMP 'install-pm-mcp.ps1'; Invoke-WebRequest $u -OutFile $f; & $f -Client <client>
+$u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.2/install.ps1'; $f=Join-Path $env:TEMP 'install-pm-mcp.ps1'; Invoke-WebRequest $u -OutFile $f; & $f -Client <client>
 ```
 
 脚本只写对应客户端的 MCP 配置；已有 JSON 配置会先生成带时间戳的备份。建议执行前先打开 [`install.ps1`](install.ps1) 审阅。ZCode 默认写入 `$ZCODE_HOME/cli/config.json` 或 `~/.zcode/cli/config.json`，Cursor 默认写入 `~/.cursor/mcp.json`；也可用 `-ConfigPath` 指定路径。
 
-### 其他支持 stdio MCP 的客户端
+#### 其他支持 stdio MCP 的客户端
 
 ```json
 {
   "mcpServers": {
     "pm-mcp": {
       "command": "npx",
-      "args": ["-y", "@luckychen1993/pm-mcp@0.1.1"],
+      "args": ["-y", "@luckychen1993/pm-mcp@0.1.2"],
       "env": {}
     }
   }

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+if (process.argv[2] === "setup") {
+    try {
+        const { runSetup } = await import("./setup.js");
+        process.exitCode = runSetup(process.argv.slice(3));
+    }
+    catch (error) {
+        console.error(`[pm-mcp setup] ERROR: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+}
+else {
+    await import("./index.js");
+}
+export {};

package/dist/index.js

@@ -22,7 +22,7 @@ for (let i = 0; i < argv.length; i++) {
         explicitRoot = argv[i + 1];
 }
 const root = resolveRoot(explicitRoot);
-const server = new McpServer({ name: "pm-mcp", version: "0.1.1" });
+const server = new McpServer({ name: "pm-mcp", version: "0.1.2" });
 registerAllTools(server, root);
 /* -------------------------------- Resources ------------------------------- */
 function safeText(fn) {

package/dist/setup.js

@@ -0,0 +1,257 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.2";
+export const SERVER_NAME = "pm-mcp";
+const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode"];
+export function parseSetupArgs(argv) {
+    const options = { client: "auto", force: false, dryRun: false, help: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--client") {
+            const value = argv[index + 1];
+            if (!value || !["auto", "all", "codex", "claude", "zcode", "cursor", "vscode", "print"].includes(value)) {
+                throw new Error("--client must be auto, all, codex, claude, zcode, cursor, vscode, or print");
+            }
+            options.client = value;
+            index += 1;
+        }
+        else if (arg === "--force") {
+            options.force = true;
+        }
+        else if (arg === "--dry-run") {
+            options.dryRun = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            options.help = true;
+        }
+        else {
+            throw new Error(`unknown setup argument: ${arg}`);
+        }
+    }
+    return options;
+}
+export function commandExists(command, env = process.env, platform = process.platform) {
+    const searchPath = env.PATH ?? env.Path ?? "";
+    const suffixes = platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+    return searchPath.split(path.delimiter).filter(Boolean).some((directory) => suffixes.some((suffix) => {
+        try {
+            return fs.statSync(path.join(directory, command + suffix)).isFile();
+        }
+        catch {
+            return false;
+        }
+    }));
+}
+export function detectClients(context) {
+    const found = [];
+    const { env, home, exists } = context;
+    if (context.commandExists("codex") || Boolean(env.CODEX_HOME) || exists(path.join(home, ".codex")))
+        found.push("codex");
+    if (context.commandExists("claude"))
+        found.push("claude");
+    if (context.commandExists("zcode") || Boolean(env.ZCODE_HOME) || exists(path.join(home, ".zcode")))
+        found.push("zcode");
+    if (context.commandExists("cursor") || exists(path.join(home, ".cursor")))
+        found.push("cursor");
+    if (context.commandExists("code"))
+        found.push("vscode");
+    return found;
+}
+function asObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be a JSON object`);
+    return value;
+}
+export function mergeJsonServer(document, shape) {
+    const root = asObject(document, "configuration root");
+    let servers;
+    if (shape === "zcode") {
+        const mcp = root.mcp === undefined ? (root.mcp = {}) : root.mcp;
+        const mcpObject = asObject(mcp, "mcp");
+        const currentServers = mcpObject.servers === undefined ? (mcpObject.servers = {}) : mcpObject.servers;
+        servers = asObject(currentServers, "mcp.servers");
+    }
+    else {
+        const currentServers = root.mcpServers === undefined ? (root.mcpServers = {}) : root.mcpServers;
+        servers = asObject(currentServers, "mcpServers");
+    }
+    servers[SERVER_NAME] = { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} };
+    return root;
+}
+function backupName(file) {
+    const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "");
+    return `${file}.backup-${stamp}-${process.pid}`;
+}
+export function writeJsonClientConfig(file, shape, dryRun = false) {
+    const absolute = path.resolve(file);
+    const exists = fs.existsSync(absolute);
+    let document = {};
+    if (exists) {
+        const stat = fs.lstatSync(absolute);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`refusing non-regular config file: ${absolute}`);
+        try {
+            document = JSON.parse(fs.readFileSync(absolute, "utf8"));
+        }
+        catch (error) {
+            throw new Error(`invalid JSON in ${absolute}; no changes made: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const merged = mergeJsonServer(document, shape);
+    if (dryRun)
+        return null;
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    const backup = exists ? backupName(absolute) : null;
+    if (backup)
+        fs.copyFileSync(absolute, backup, fs.constants.COPYFILE_EXCL);
+    const temporary = `${absolute}.tmp-${process.pid}`;
+    try {
+        fs.writeFileSync(temporary, JSON.stringify(merged, null, 2) + "\n", { encoding: "utf8", flag: "wx" });
+        fs.renameSync(temporary, absolute);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* nothing to clean */ }
+        throw error;
+    }
+    return backup;
+}
+function codexConfigPath(env, home) {
+    return path.join(env.CODEX_HOME || path.join(home, ".codex"), "config.toml");
+}
+function zcodeConfigPath(env, home) {
+    return path.join(env.ZCODE_HOME || path.join(home, ".zcode"), "cli", "config.json");
+}
+function hasCodexServer(text) {
+    return /^\s*\[mcp_servers\.(?:pm-mcp|"pm-mcp")\]\s*$/m.test(text);
+}
+function appendCodexConfig(file, dryRun, log) {
+    const absolute = path.resolve(file);
+    const existing = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : "";
+    if (hasCodexServer(existing)) {
+        log(`[skip] Codex already has ${SERVER_NAME}; use --force with the Codex CLI to replace it.`);
+        return;
+    }
+    log(`[${dryRun ? "plan" : "write"}] Codex: ${absolute}`);
+    if (dryRun)
+        return;
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    if (fs.existsSync(absolute))
+        fs.copyFileSync(absolute, backupName(absolute), fs.constants.COPYFILE_EXCL);
+    const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+    const block = `${separator}\n[mcp_servers.${SERVER_NAME}]\ncommand = "npx"\nargs = ["-y", "${PACKAGE_SPEC}"]\n`;
+    fs.appendFileSync(absolute, block, "utf8");
+}
+function run(command, args, visible) {
+    const result = spawnSync(command, args, {
+        shell: false,
+        windowsHide: true,
+        stdio: visible ? "inherit" : "ignore",
+    });
+    if (result.error)
+        return -1;
+    return result.status ?? -1;
+}
+function configureCliClient(client, options, available, log) {
+    if (!available)
+        return false;
+    const getArgs = ["mcp", "get", SERVER_NAME];
+    const exists = run(client, getArgs, false) === 0;
+    if (exists && !options.force) {
+        log(`[skip] ${client} already has ${SERVER_NAME}; run setup --force to replace it.`);
+        return true;
+    }
+    const addArgs = client === "codex"
+        ? ["mcp", "add", SERVER_NAME, "--", "npx", "-y", PACKAGE_SPEC]
+        : ["mcp", "add", SERVER_NAME, "--scope", "user", "--", "npx", "-y", PACKAGE_SPEC];
+    log(`[${options.dryRun ? "plan" : "run"}] ${client} ${addArgs.join(" ")}`);
+    if (options.dryRun)
+        return true;
+    if (exists && run(client, ["mcp", "remove", SERVER_NAME], true) !== 0)
+        throw new Error(`${client} could not remove the existing server`);
+    if (run(client, addArgs, true) !== 0)
+        throw new Error(`${client} could not add ${SERVER_NAME}`);
+    return true;
+}
+function configureClient(client, options, context, log) {
+    if (client === "codex") {
+        if (configureCliClient("codex", options, context.commandExists("codex"), log))
+            return;
+        appendCodexConfig(codexConfigPath(context.env, context.home), options.dryRun, log);
+        return;
+    }
+    if (client === "claude") {
+        if (!configureCliClient("claude", options, context.commandExists("claude"), log))
+            throw new Error("claude was not found in PATH");
+        return;
+    }
+    if (client === "zcode" || client === "cursor") {
+        const file = client === "zcode" ? zcodeConfigPath(context.env, context.home) : path.join(context.home, ".cursor", "mcp.json");
+        log(`[${options.dryRun ? "plan" : "write"}] ${client}: ${file}`);
+        const backup = writeJsonClientConfig(file, client === "zcode" ? "zcode" : "standard", options.dryRun);
+        if (backup)
+            log(`[backup] ${backup}`);
+        return;
+    }
+    if (!context.commandExists("code"))
+        throw new Error("code was not found in PATH");
+    const definition = JSON.stringify({ name: SERVER_NAME, command: "npx", args: ["-y", PACKAGE_SPEC] });
+    log(`[${options.dryRun ? "plan" : "run"}] code --add-mcp ${definition}`);
+    if (!options.dryRun && run("code", ["--add-mcp", definition], true) !== 0)
+        throw new Error("VS Code could not add pm-mcp");
+}
+function printHelp(log) {
+    log("pm-mcp setup — configure local AI coding clients");
+    log("");
+    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|print] [--force] [--dry-run]`);
+    log("Default auto mode configures every detected supported client.");
+}
+export function runSetup(argv, overrides = {}) {
+    const options = parseSetupArgs(argv);
+    const log = overrides.log ?? console.log;
+    if (options.help) {
+        printHelp(log);
+        return 0;
+    }
+    if (options.client === "print") {
+        log(JSON.stringify({ mcpServers: { [SERVER_NAME]: { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} } } }, null, 2));
+        return 0;
+    }
+    const env = overrides.env ?? process.env;
+    const home = overrides.home ?? os.homedir();
+    const context = {
+        env,
+        home,
+        commandExists: overrides.commandExists ?? ((command) => commandExists(command, env)),
+        exists: overrides.exists ?? fs.existsSync,
+    };
+    const selected = options.client === "all"
+        ? CLIENTS
+        : options.client === "auto"
+            ? detectClients(context)
+            : [options.client];
+    if (selected.length === 0) {
+        log("No supported client was detected. Use --client <name>, or --client print for generic JSON.");
+        return 1;
+    }
+    log(`pm-mcp setup ${PACKAGE_SPEC}`);
+    log(`clients: ${selected.join(", ")}`);
+    let failures = 0;
+    for (const client of selected) {
+        try {
+            configureClient(client, options, context, log);
+        }
+        catch (error) {
+            failures += 1;
+            console.error(`[failed] ${client}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (failures > 0)
+        return 1;
+    log("Done. Restart the configured client and ask it to call pm-mcp get_status.");
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",
@@ -26,7 +26,7 @@
     "dist/"
   ],
   "bin": {
-    "pm-mcp": "dist/index.js"
+    "pm-mcp": "dist/cli.js"
   },
   "main": "dist/index.js",
   "engines": {