@zythegit/jenkins-config-mcp 1.6.1 → 1.6.2

package/README.md

@@ -24,6 +24,50 @@ MCP Server 本体是 Python 实现，但发布物是 PyInstaller 打出的单文
 
 支持的平台：Windows x64、macOS x64 / arm64、Linux x64 / arm64。
 
+## 其他客户端
+
+上面那段 `mcpServers` 适用于 Claude Desktop / Claude Code / Cursor 等大多数客户端。以下三家键名或格式不同，照抄会配了不生效：
+
+**Codex CLI** — `~/.codex/config.toml`（或受信任项目的 `.codex/config.toml`），TOML 格式，表名带下划线：
+
+```toml
+[mcp_servers.jenkins-build]
+command = "npx"
+args = ["-y", "@zythegit/jenkins-config-mcp"]
+env = { JENKINS_MCP_ALLOW_WRITE = "1" }
+```
+
+也可以 `codex mcp add jenkins-build --env JENKINS_MCP_ALLOW_WRITE=1 -- npx -y @zythegit/jenkins-config-mcp`，TUI 里用 `/mcp` 看连接状态。
+
+**OpenCode** — `~/.config/opencode/opencode.json`（或项目根的 `opencode.json`）的 `mcp` 键下，`command` 是数组，环境变量键名是 `environment` 而非 `env`：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "jenkins-build": {
+      "type": "local",
+      "command": ["npx", "-y", "@zythegit/jenkins-config-mcp"],
+      "environment": { "JENKINS_MCP_ALLOW_WRITE": "1" },
+      "enabled": true
+    }
+  }
+}
+```
+
+**Pi** — 内核不带 MCP，得先装适配器扩展并重启 Pi：
+
+```bash
+pi install npm:pi-mcp-adapter
+```
+
+之后写项目根的 `.mcp.json` 或全局 `~/.pi/agent/mcp.json`，格式与上面那段 `mcpServers` 完全一致，直接复制。装好后用 `/mcp` 面板看连接状态。
+
+VS Code (Copilot) 的 `.vscode/mcp.json` 顶层键是 `servers` 而不是 `mcpServers`。逐客户端的完整说明见仓库内 `docs/mcp/README.md` §3.4。
+
+改完配置都要重启客户端，MCP 配置不热加载。
+
+
 ## 解析优先级
 
 1. `JENKINS_MCP_BINARY` — 直接指定二进制路径

package/bin/jenkins-config-mcp.js

@@ -32,6 +32,12 @@ const MODULE_ARGS = ['-m', 'jenkins_config.mcp.server'];
 const DEFAULT_PACKAGE =
   'jenkins-config[mcp] @ git+https://github.com/zyTheGit/jenkins-config.git';
 
+// cmd.exe 需要转义的元字符。三处转义共用一份，避免改一处漏两处
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+
+// 主动关停时记录信号：既用于去重（避免重复杀树），也用于区分关停与真失败
+let shutdownSignal = null;
+
 // 平台 → Release 资产名，与 .github/workflows/build.yml 的产物命名保持一致
 const ASSETS = {
   'win32-x64': 'jenkins-config-mcp-win-x64.exe',
@@ -50,6 +56,21 @@ function log(message) {
   process.stderr.write(`[jenkins-config-mcp] ${message}\n`);
 }
 
+/**
+ * 判断路径是否指向一个存在的普通文件。
+ *
+ * @param {string} candidate 待检查路径
+ * @returns {boolean} 是文件则 true
+ */
+function isExistingFile(candidate) {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    // 不存在或不可读
+    return false;
+  }
+}
+
 /**
  * 在 PATH 中查找可执行文件（Windows 下按 PATHEXT 补全后缀）。
  *
@@ -60,26 +81,130 @@ function log(message) {
  */
 function which(name) {
   if (name.includes(path.sep) || name.includes('/')) {
-    return fs.existsSync(name) ? name : null;
+    return isExistingFile(name) ? name : null;
+  }
+  let exts = [''];
+  if (process.platform === 'win32') {
+    exts = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
+    // 名字已自带 PATHEXT 后缀时（jenkins-config-mcp.cmd）要先按原名找，
+    // 否则只会去试 xxx.cmd.EXE 这类不存在的组合，明明在 PATH 上却找不到
+    if (exts.some((ext) => name.toLowerCase().endsWith(ext.toLowerCase()))) {
+      exts = [''].concat(exts);
+    }
   }
-  const exts =
-    process.platform === 'win32'
-      ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
-      : [''];
   for (const dir of (process.env.PATH || '').split(path.delimiter)) {
     if (!dir) continue;
     for (const ext of exts) {
       const candidate = path.join(dir, name + ext);
-      try {
-        if (fs.statSync(candidate).isFile()) return candidate;
-      } catch {
-        // 不存在或不可读，继续尝试下一个候选
-      }
+      if (isExistingFile(candidate)) return candidate;
     }
   }
   return null;
 }
 
+/**
+ * 判断命令是否是 Windows 批处理脚本（.cmd / .bat）。
+ *
+ * Node 18.20 / 20.12 起（CVE-2024-27980 加固）不再允许在 shell: false 下
+ * 直接 spawn 批处理文件，会同步抛出 EINVAL。而 pip / npm 在 Windows 上
+ * 生成的 console script shim 经常就是 .cmd，兜底分支正好会命中它。
+ *
+ * @param {string} command 待执行的命令路径
+ * @returns {boolean} 是批处理脚本则 true
+ */
+function isBatchScript(command) {
+  return process.platform === 'win32' && /\.(cmd|bat)$/i.test(command);
+}
+
+/**
+ * 转义交给 cmd.exe 的命令路径。
+ *
+ * 走 cmd.exe 是被迫的（批处理只能由它解释），因此必须自己把元字符挡掉，
+ * 不能让路径里的 `&` `^` 之类被当成命令分隔符。
+ *
+ * @param {string} value 命令路径
+ * @returns {string} 转义后的命令
+ */
+function escapeCmdCommand(value) {
+  return String(value).replace(CMD_META, '^$1');
+}
+
+/**
+ * 转义交给 cmd.exe 的单个参数。
+ *
+ * 先按 Windows 的 argv 规则处理反斜杠与引号，再包引号，最后转义 cmd 元字符；
+ * 元字符转义做两遍 —— 批处理里的 `%*` 会被 cmd 二次解析，只转一遍在 shim
+ * 展开参数时又会被吃掉一层。
+ *
+ * @param {string} value 参数原文
+ * @returns {string} 转义后的参数
+ */
+function escapeCmdArgument(value) {
+  let arg = String(value);
+  arg = arg.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+  arg = arg.replace(/(?=(\\+?)?)\1$/, '$1$1');
+  arg = `"${arg}"`;
+  return arg.replace(CMD_META, '^$1').replace(CMD_META, '^$1');
+}
+
+/**
+ * 把批处理命令包装成一次 cmd.exe 调用。
+ *
+ * 不用 spawn 的 shell: true —— Node 24 起那条路径会打印 DEP0190 弃用警告，
+ * 且由 Node 拼接命令行时不会转义参数。这里自己拼好并置
+ * windowsVerbatimArguments，告诉 Node 命令行已经转义完毕。
+ *
+ * @param {string} command 批处理脚本路径
+ * @param {string[]} args 传给脚本的参数
+ * @returns {{command: string, args: string[]}} cmd.exe 调用形式
+ */
+function wrapForCmd(command, args) {
+  const line = [escapeCmdCommand(command)].concat(args.map(escapeCmdArgument)).join(' ');
+  return { command: process.env.COMSPEC || 'cmd.exe', args: ['/d', '/s', '/c', `"${line}"`] };
+}
+
+/**
+ * 终止子进程（经 cmd.exe 转发时连同整棵进程树）。
+ *
+ * 走 cmd.exe 时 child 只是 cmd.exe 本身，真正的 MCP Server 是它的子进程。
+ * Windows 没有进程组信号，单杀 cmd.exe 会留下孤儿进程继续持有继承来的
+ * stdin/stdout，客户端会一直等一个没人回应的管道，只能用 taskkill /T 杀树。
+ *
+ * 只执行一次：taskkill 路径不会置位 child.killed，重复信号会拿着可能已被
+ * 复用的 PID 再杀一遍。
+ *
+ * @param {import('node:child_process').ChildProcess} child 子进程
+ * @param {string} sig 收到的信号名
+ * @param {boolean} viaCmd 是否经 cmd.exe 转发
+ */
+function terminate(child, sig, viaCmd) {
+  if (shutdownSignal) return;
+  shutdownSignal = sig;
+
+  if (viaCmd && child.pid) {
+    try {
+      const killer = spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], {
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      // taskkill 不在 PATH 上（精简镜像）时退回单进程 kill，至少别静默什么都不做
+      killer.on('error', () => child.kill(sig));
+      // taskkill 起来了却没干成（拒绝访问、被安全软件拦截）同样要退回，
+      // 否则进程树存活而这里既无日志也无动作 —— child.kill 对已退出进程是空操作
+      killer.on('exit', (code) => {
+        if (code !== 0 && !child.killed) {
+          log(`taskkill 失败（退出码 ${code}），退回单进程 kill`);
+          child.kill(sig);
+        }
+      });
+      return;
+    } catch {
+      // spawn 同步抛错，同样退回单进程 kill
+    }
+  }
+  child.kill(sig);
+}
+
 /**
  * 当前平台对应的 Release 资产名。
  *
@@ -282,33 +407,65 @@ async function main() {
   }
 
   const args = resolved.args.concat(process.argv.slice(2));
+  // 只有批处理 shim 才绕 cmd.exe —— 二进制与 python.exe 继续直接 spawn，
+  // 不让用户参数经过命令行解析器
+  const viaCmd = isBatchScript(resolved.command);
+  const launch = viaCmd ? wrapForCmd(resolved.command, args) : { command: resolved.command, args };
 
   if (process.env.JENKINS_MCP_LAUNCHER_DRYRUN) {
     process.stdout.write(
-      JSON.stringify({ source: resolved.source, command: resolved.command, args }) + '\n'
+      JSON.stringify({
+        source: resolved.source,
+        command: resolved.command,
+        args,
+        via_cmd: viaCmd,
+      }) + '\n'
     );
     return;
   }
 
-  const child = spawn(resolved.command, args, {
+  // 经 cmd.exe 转发后，脚本不存在只会让 cmd 自己报错并返回 1，spawn 的
+  // 'error' 事件不再触发，所以这里先自己判一次，保证仍有一行归因日志。
+  // 用 which() 判定而不是直接 existsSync：命令可能是裸名（如
+  // JENKINS_MCP_BINARY=foo.cmd），那种情况 cmd.exe 会按 PATH 找，不能按 CWD 否掉
+  if (viaCmd && !which(resolved.command)) {
+    log(`启动失败 (${resolved.command}): 文件不存在`);
+    process.exit(1);
+  }
+
+  const child = spawn(launch.command, launch.args, {
     stdio: 'inherit',
     shell: false,
     windowsHide: true,
+    windowsVerbatimArguments: viaCmd,
   });
 
   child.on('error', (err) => {
-    log(`启动失败 (${resolved.command}): ${err.message}`);
+    // 转发时 spawn 的对象是 cmd.exe，两个路径都打出来才能区分是 COMSPEC 还是 shim 的问题
+    log(`启动失败 (${launch.command}${viaCmd ? ` → ${resolved.command}` : ''}): ${err.message}`);
     process.exit(1);
   });
 
   for (const sig of ['SIGINT', 'SIGTERM']) {
     process.on(sig, () => {
-      if (!child.killed) child.kill(sig);
+      if (!child.killed) terminate(child, sig, viaCmd);
     });
   }
 
   child.on('exit', (code, signal) => {
+    // 主动关停：taskkill /F 会让 cmd.exe 带非零码退出，不能报成失败。
+    // 重新抛信号前先摘掉自己的 listener，否则被自己接住，进程反而退不掉
+    if (shutdownSignal) {
+      process.removeAllListeners(shutdownSignal);
+      if (process.platform === 'win32') {
+        // Windows 没有真正的信号投递，process.kill 自己等于 TerminateProcess
+        process.exit(0);
+      }
+      process.kill(process.pid, shutdownSignal);
+      return;
+    }
     if (signal) {
+      process.removeAllListeners(signal);
       process.kill(process.pid, signal);
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zythegit/jenkins-config-mcp",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "npx launcher for the jenkins-config MCP Server (Python)",
   "bin": {
     "jenkins-config-mcp": "bin/jenkins-config-mcp.js"