@reconcrap/boss-recommend-mcp 2.1.1 → 2.1.2

package/README.md

@@ -7,6 +7,68 @@ Boss 推荐 / 搜索 / 聊天筛选 MCP（stdio）服务。
 - npm: `@reconcrap/boss-recommend-mcp`（https://www.npmjs.com/package/@reconcrap/boss-recommend-mcp）
 - GitHub: `reconcrap-cpu/boss-recommend-mcp`（https://github.com/reconcrap-cpu/boss-recommend-mcp）
 
+## AI harness install entrypoint
+
+如果用户只把这个 GitHub 链接交给 Codex、Claude Code、Cursor、OpenClaw、QClaw、Trae 等 AI harness，并要求“安装这个工具”，请优先执行本节，而不是直接在 macOS 上裸跑 `npm install -g`。
+
+AI harness 不能只完成 npm 安装就结束。安装流程还必须帮助用户完成必填 LLM 配置；如果用户没有提前提供，请向用户索取：
+
+- LLM base URL（默认可用 `https://api.openai.com/v1`）
+- LLM API key
+- LLM model（默认可用 `gpt-4.1-mini`）
+
+然后写入配置：
+
+```bash
+boss-recommend-mcp config set --base-url <baseUrl> --api-key <apiKey> --model <model> --thinking-level low
+boss-recommend-mcp doctor
+```
+
+如果用户用 macOS bootstrap，它会自动尝试交互式询问并写入这些字段。非交互式 AI harness 如果拿不到用户输入，应暂停并询问用户上述三项，不要把安装标记为完成。
+
+macOS 首次安装推荐使用仓库里的 nvm bootstrap。它会把 Node/npm/global packages 放到用户目录，避免首次安装或后续升级时出现：
+
+```text
+EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@reconcrap'
+```
+
+这是 npm global prefix 权限问题，不是 `boss-recommend-mcp` 包内部创建目录失败。
+
+macOS 一键安装：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash
+```
+
+如果要直接配置某个宿主：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash -s -- --agent openclaw
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash -s -- --agent qclaw
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash -s -- --agent trae-cn
+```
+
+安装后，未来升级只需要在同一个 nvm shell 里运行：
+
+```bash
+npm -g i @reconcrap/boss-recommend-mcp@latest
+boss-recommend-mcp where
+```
+
+如果升级前 `npm config get prefix` 返回 `/usr/local`，说明当前 shell 没有使用 nvm Node；请先重新加载 nvm，不要使用 `sudo npm install -g`。
+
+macOS bootstrap 会执行 `boss-recommend-mcp install --mcp-launch global-wrapper`。该模式会把 MCP 宿主配置为启动稳定 wrapper：`~/.boss-recommend-mcp/bin/boss-recommend-mcp-mcp-server`。这个 wrapper 每次启动时都会调用当前全局 `boss-recommend-mcp start`，因此后续 `npm -g i @reconcrap/boss-recommend-mcp@latest` 会更新 MCP 宿主实际运行的版本，不需要每次升级后重写 MCP 配置。
+
+如果 AI harness 已经从用户处拿到 LLM 信息，可以非交互式传给 bootstrap：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh \
+  | BOSS_RECOMMEND_BASE_URL="https://api.openai.com/v1" \
+    BOSS_RECOMMEND_API_KEY="<apiKey>" \
+    BOSS_RECOMMEND_MODEL="gpt-4.1-mini" \
+    bash -s -- --agent openclaw
+```
+
 2.0.0 是 CDP-only 重写版本：活跃浏览器路径只允许 Chrome DevTools Protocol 的 `DOM` / `Input` / `Page` / `Network` / `Accessibility` 等域，不使用 `Runtime.evaluate` 或页面 JS。包内保留 recommend、search/recruit、chat 三条域服务，并共享浏览器、生命周期、筛选、CV 获取、无限滚动、自愈与 CSV 报告层。
 
 安装 `boss-recommend-mcp` 后可以直接：
@@ -125,6 +187,13 @@ npm install -g @reconcrap/boss-recommend-mcp@latest
 boss-recommend-mcp start
 ```
 
+macOS 首次安装如果没有确认 npm prefix 在用户目录，优先使用本文开头的 `scripts/install-macos.sh`。完成 bootstrap 后，后续升级仍然使用同一个 npm 命令：
+
+```bash
+npm -g i @reconcrap/boss-recommend-mcp@latest
+boss-recommend-mcp where
+```
+
 无需安装（npx 直接运行）：
 
 ```bash
@@ -150,7 +219,8 @@ node src/cli.js start
 如果检测到 legacy Boss server entries，installer 会：
 
 - 保留非 Boss MCP server。
-- 写入统一 server：`boss-recommend -> npx -y @reconcrap/boss-recommend-mcp@<installed-version> start`
+- 默认写入统一 server：`boss-recommend -> npx -y @reconcrap/boss-recommend-mcp@<installed-version> start`
+- 如果传入 `--mcp-launch global-wrapper`，写入升级稳定入口：`boss-recommend -> ~/.boss-recommend-mcp/bin/boss-recommend-mcp-mcp-server`。该 wrapper 会加载 `~/.nvm/nvm.sh` 并执行当前全局 `boss-recommend-mcp start`，适合 macOS 上通过 `npm -g i @reconcrap/boss-recommend-mcp@latest` 持续升级。
 - 从同一个 `mcp.json` 删除旧 `boss-recruit-mcp`、standalone `boss-chat`、旧本地 Boss repo 路径，避免 agent 继续调用 legacy 包。
 - 在原文件旁生成 `mcp.json.boss-mcp-migration-*.bak`。
 - 同步外部 skills 目录里的 `boss-recommend-pipeline`、`boss-recruit-pipeline`、`boss-chat`。
@@ -166,6 +236,14 @@ boss-recommend-mcp doctor --agent openclaw
 boss-recommend-mcp doctor --agent qclaw
 ```
 
+macOS 上如果希望 MCP 宿主总是使用全局 npm 最新安装版本：
+
+```bash
+boss-recommend-mcp install --mcp-launch global-wrapper --agent openclaw
+boss-recommend-mcp install --mcp-launch global-wrapper --agent qclaw
+boss-recommend-mcp install --mcp-launch global-wrapper --agent trae-cn
+```
+
 自定义路径：
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recommend-mcp",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",
@@ -79,10 +79,11 @@
     "live:chat-image-screening": "node scripts/live-chat-image-screening-smoke.js"
   },
   "files": [
-    "bin",
-    "config/screening-config.example.json",
-    "skills",
-    "scripts/postinstall.cjs",
+    "bin",
+    "config/screening-config.example.json",
+    "skills",
+    "scripts/install-macos.sh",
+    "scripts/postinstall.cjs",
     "src/core",
     "src/domains",
     "src/chat-mcp.js",

package/scripts/install-macos.sh

@@ -0,0 +1,280 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE_NAME="@reconcrap/boss-recommend-mcp"
+DEFAULT_NODE_VERSION="${BOSS_RECOMMEND_NODE_VERSION:-22}"
+DEFAULT_NVM_VERSION="${BOSS_RECOMMEND_NVM_VERSION:-v0.40.4}"
+
+NODE_VERSION="$DEFAULT_NODE_VERSION"
+NVM_VERSION="$DEFAULT_NVM_VERSION"
+AGENT="${BOSS_RECOMMEND_AGENT:-}"
+DRY_RUN=0
+SKIP_DOCTOR=0
+SKIP_LLM_CONFIG=0
+BASE_URL="${BOSS_RECOMMEND_BASE_URL:-https://api.openai.com/v1}"
+API_KEY="${BOSS_RECOMMEND_API_KEY:-}"
+MODEL="${BOSS_RECOMMEND_MODEL:-gpt-4.1-mini}"
+THINKING_LEVEL="${BOSS_RECOMMEND_THINKING_LEVEL:-low}"
+GREETING_MESSAGE="${BOSS_RECOMMEND_GREETING_MESSAGE:-Hi同学，能麻烦发下简历吗？}"
+
+usage() {
+  cat <<'EOF'
+Install boss-recommend-mcp on macOS with nvm-backed npm globals.
+
+Usage:
+  install-macos.sh [--agent <agent|all>] [--node-version <version>] [--nvm-version <tag>] [--dry-run] [--skip-doctor] [--skip-llm-config]
+
+Examples:
+  curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash
+  curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash -s -- --agent openclaw
+
+Supported agents: cursor, trae, trae-cn, claude, openclaw, qclaw, all
+
+LLM config can be supplied non-interactively with:
+  BOSS_RECOMMEND_BASE_URL, BOSS_RECOMMEND_API_KEY, BOSS_RECOMMEND_MODEL,
+  BOSS_RECOMMEND_THINKING_LEVEL, BOSS_RECOMMEND_GREETING_MESSAGE
+EOF
+}
+
+log() {
+  printf '%s\n' "[boss-recommend-mcp] $*"
+}
+
+die() {
+  printf '%s\n' "[boss-recommend-mcp] ERROR: $*" >&2
+  exit 1
+}
+
+run() {
+  log "+ $*"
+  if [ "$DRY_RUN" -eq 0 ]; then
+    "$@"
+  fi
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --agent)
+      [ "$#" -ge 2 ] || die "--agent requires a value"
+      AGENT="$2"
+      shift 2
+      ;;
+    --node-version)
+      [ "$#" -ge 2 ] || die "--node-version requires a value"
+      NODE_VERSION="$2"
+      shift 2
+      ;;
+    --nvm-version)
+      [ "$#" -ge 2 ] || die "--nvm-version requires a value"
+      NVM_VERSION="$2"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --skip-doctor)
+      SKIP_DOCTOR=1
+      shift
+      ;;
+    --skip-llm-config)
+      SKIP_LLM_CONFIG=1
+      shift
+      ;;
+    --base-url)
+      [ "$#" -ge 2 ] || die "--base-url requires a value"
+      BASE_URL="$2"
+      shift 2
+      ;;
+    --api-key)
+      [ "$#" -ge 2 ] || die "--api-key requires a value"
+      API_KEY="$2"
+      shift 2
+      ;;
+    --model)
+      [ "$#" -ge 2 ] || die "--model requires a value"
+      MODEL="$2"
+      shift 2
+      ;;
+    --thinking-level)
+      [ "$#" -ge 2 ] || die "--thinking-level requires a value"
+      THINKING_LEVEL="$2"
+      shift 2
+      ;;
+    --greeting-message)
+      [ "$#" -ge 2 ] || die "--greeting-message requires a value"
+      GREETING_MESSAGE="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      die "Unknown option: $1"
+      ;;
+  esac
+done
+
+prompt_text() {
+  local label="$1"
+  local default_value="$2"
+  local secret="${3:-0}"
+  local value
+  if [ ! -r /dev/tty ]; then
+    return 1
+  fi
+  if [ "$secret" -eq 1 ]; then
+    printf '%s' "${label}: " > /dev/tty
+    IFS= read -r -s value < /dev/tty || return 1
+    printf '\n' > /dev/tty
+  elif [ -n "$default_value" ]; then
+    printf '%s' "${label} [${default_value}]: " > /dev/tty
+    IFS= read -r value < /dev/tty || return 1
+    if [ -z "$value" ]; then
+      value="$default_value"
+    fi
+  else
+    printf '%s' "${label}: " > /dev/tty
+    IFS= read -r value < /dev/tty || return 1
+  fi
+  printf '%s' "$value"
+}
+
+if [ "$(uname -s)" != "Darwin" ]; then
+  if [ "$DRY_RUN" -eq 1 ]; then
+    log "dry-run on non-macOS host; skipping platform enforcement"
+  else
+    die "This bootstrap script is for macOS. Use npm install -g ${PACKAGE_NAME}@latest on other platforms."
+  fi
+fi
+
+export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+
+load_nvm() {
+  if [ -s "$NVM_DIR/nvm.sh" ]; then
+    # shellcheck disable=SC1090
+    . "$NVM_DIR/nvm.sh"
+  elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+    export NVM_DIR="$HOME/.nvm"
+    # shellcheck disable=SC1091
+    . "$HOME/.nvm/nvm.sh"
+  fi
+}
+
+install_nvm() {
+  if command -v nvm >/dev/null 2>&1; then
+    return
+  fi
+  log "nvm was not found; installing ${NVM_VERSION} into ${NVM_DIR}"
+  if [ "$DRY_RUN" -eq 1 ]; then
+    log "+ curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh | bash"
+    return
+  fi
+  curl -fsSL "https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh" | bash
+  load_nvm
+  command -v nvm >/dev/null 2>&1 || die "nvm installed but is not available in this shell. Open a new terminal and rerun this script."
+}
+
+load_nvm
+install_nvm
+
+run nvm install "$NODE_VERSION"
+run nvm alias default "$NODE_VERSION"
+run nvm use "$NODE_VERSION"
+
+if [ "$DRY_RUN" -eq 0 ]; then
+  NODE_PATH="$(command -v node || true)"
+  NPM_PATH="$(command -v npm || true)"
+  NPM_PREFIX="$(npm config get prefix || true)"
+  log "node: ${NODE_PATH}"
+  log "npm: ${NPM_PATH}"
+  log "npm prefix: ${NPM_PREFIX}"
+
+  case "$NPM_PREFIX" in
+    /usr/local|/usr/local/*)
+      die "npm is still using /usr/local. Reload nvm and rerun this script; do not use sudo npm install -g."
+      ;;
+  esac
+  case "$NPM_PREFIX" in
+    "$NVM_DIR"/*)
+      ;;
+    *)
+      die "npm prefix is not under ${NVM_DIR}. Current prefix: ${NPM_PREFIX}"
+      ;;
+  esac
+else
+  log "+ verify: npm config get prefix must be under ${NVM_DIR}, not /usr/local"
+fi
+
+run npm -g i "${PACKAGE_NAME}@latest"
+run boss-recommend-mcp where
+
+INSTALL_ARGS=(install --mcp-launch global-wrapper)
+DOCTOR_ARGS=(doctor)
+if [ -n "$AGENT" ]; then
+  INSTALL_ARGS+=(--agent "$AGENT")
+  DOCTOR_ARGS+=(--agent "$AGENT")
+fi
+
+run boss-recommend-mcp "${INSTALL_ARGS[@]}"
+
+if [ "$SKIP_LLM_CONFIG" -eq 0 ]; then
+  log "LLM screening config is required before running candidate screening."
+  if [ "$DRY_RUN" -eq 0 ]; then
+    if [ -r /dev/tty ]; then
+      BASE_URL="$(prompt_text "LLM base URL" "$BASE_URL")"
+      MODEL="$(prompt_text "LLM model" "$MODEL")"
+      THINKING_LEVEL="$(prompt_text "LLM thinking level" "$THINKING_LEVEL")"
+      GREETING_MESSAGE="$(prompt_text "Greeting message for candidates" "$GREETING_MESSAGE")"
+      if [ -z "$API_KEY" ]; then
+        API_KEY="$(prompt_text "LLM API key (input hidden)" "" 1)"
+      fi
+    fi
+    if [ -z "$BASE_URL" ] || [ -z "$API_KEY" ] || [ -z "$MODEL" ]; then
+      cat >&2 <<EOF
+[boss-recommend-mcp] LLM config is still required.
+[boss-recommend-mcp] Ask the user for:
+  1. LLM base URL
+  2. LLM API key
+  3. LLM model name
+[boss-recommend-mcp] Then run:
+  boss-recommend-mcp config set --base-url <baseUrl> --api-key <apiKey> --model <model> --thinking-level ${THINKING_LEVEL}
+EOF
+      exit 2
+    fi
+  fi
+
+  CONFIG_ARGS=(config set --base-url "$BASE_URL" --api-key "$API_KEY" --model "$MODEL")
+  if [ -n "$THINKING_LEVEL" ]; then
+    CONFIG_ARGS+=(--thinking-level "$THINKING_LEVEL")
+  fi
+  if [ -n "$GREETING_MESSAGE" ]; then
+    CONFIG_ARGS+=(--greeting-message "$GREETING_MESSAGE")
+  fi
+
+  if [ "$DRY_RUN" -eq 1 ]; then
+    log "+ boss-recommend-mcp config set --base-url ${BASE_URL:-<baseUrl>} --api-key <hidden> --model ${MODEL:-<model>} --thinking-level ${THINKING_LEVEL:-<level>}"
+  else
+    log "+ boss-recommend-mcp config set --base-url ${BASE_URL} --api-key <hidden> --model ${MODEL}"
+    boss-recommend-mcp "${CONFIG_ARGS[@]}"
+  fi
+else
+  log "Skipping LLM config because --skip-llm-config was provided."
+fi
+
+if [ "$SKIP_DOCTOR" -eq 0 ]; then
+  log "+ boss-recommend-mcp ${DOCTOR_ARGS[*]}"
+  if [ "$DRY_RUN" -eq 0 ]; then
+    if ! boss-recommend-mcp "${DOCTOR_ARGS[@]}"; then
+      log "doctor reported follow-up work. The npm package install still completed."
+    fi
+  fi
+fi
+
+cat <<EOF
+[boss-recommend-mcp] install complete.
+[boss-recommend-mcp] Future upgrades:
+  npm -g i ${PACKAGE_NAME}@latest
+  boss-recommend-mcp where
+EOF

package/src/cli.js

@@ -50,10 +50,12 @@ const chromeOnboardingUrlPattern = /^chrome:\/\/(welcome|intro|newtab|signin|his
 const bossLoginUrlPattern = /(?:zhipin\.com\/web\/user(?:\/|\?|$)|passport\.zhipin\.com)/i;
 const bossLoginTitlePattern = /登录|signin|扫码登录|BOSS直聘登录/i;
 const supportedMcpClients = ["generic", "cursor", "trae", "claudecode", "openclaw", "qclaw"];
-const defaultMcpServerName = "boss-recommend";
-const defaultMcpCommand = "npx";
-const recommendMcpPackageName = "@reconcrap/boss-recommend-mcp";
-const recommendMcpBinaryName = "boss-recommend-mcp";
+const defaultMcpServerName = "boss-recommend";
+const defaultMcpCommand = "npx";
+const recommendMcpPackageName = "@reconcrap/boss-recommend-mcp";
+const recommendMcpBinaryName = "boss-recommend-mcp";
+const globalMcpWrapperFileName = "boss-recommend-mcp-mcp-server";
+const supportedMcpLaunchModes = ["npx", "global-wrapper"];
 const autoSyncSkipCommands = new Set(["install", "install-skill", "where", "help", "--help", "-h", "list-jobs", "jobs", "recommend-jobs"]);
 const externalMcpTargetsEnv = "BOSS_RECOMMEND_MCP_CONFIG_TARGETS";
 const externalSkillDirsEnv = "BOSS_RECOMMEND_EXTERNAL_SKILL_DIRS";
@@ -124,15 +126,22 @@ function getCodexHome() {
     : path.join(os.homedir(), ".codex");
 }
 
-function getStateHome() {
-  return process.env.BOSS_RECOMMEND_HOME
-    ? path.resolve(process.env.BOSS_RECOMMEND_HOME)
-    : path.join(os.homedir(), ".boss-recommend-mcp");
-}
-
-function ensureDir(targetPath) {
-  fs.mkdirSync(targetPath, { recursive: true });
-}
+function getStateHome() {
+  return process.env.BOSS_RECOMMEND_HOME
+    ? path.resolve(process.env.BOSS_RECOMMEND_HOME)
+    : path.join(os.homedir(), ".boss-recommend-mcp");
+}
+
+function getGlobalMcpWrapperPath(options = {}) {
+  if (typeof options["mcp-wrapper-path"] === "string" && options["mcp-wrapper-path"].trim()) {
+    return path.resolve(options["mcp-wrapper-path"].trim());
+  }
+  return path.join(getStateHome(), "bin", globalMcpWrapperFileName);
+}
+
+function ensureDir(targetPath) {
+  fs.mkdirSync(targetPath, { recursive: true });
+}
 
 function pathExists(targetPath) {
   try {
@@ -738,13 +747,55 @@ function parseMcpClientTargets(rawValue) {
   return unique;
 }
 
-function isPlainObject(value) {
-  return value && typeof value === "object" && !Array.isArray(value);
-}
-
-function shouldDefaultRecommendDetachedMcpEnv(options = {}) {
-  const client = normalizeMcpClientName(options.client);
-  const agent = normalizeAgentName(options.agent);
+function isPlainObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeMcpLaunchMode(options = {}) {
+  const raw = String(options["mcp-launch"] || options.mcpLaunch || "").trim().toLowerCase().replace(/_/g, "-");
+  if (!raw) return "npx";
+  if (raw === "default") return "npx";
+  if (raw === "global" || raw === "wrapper") return "global-wrapper";
+  if (supportedMcpLaunchModes.includes(raw)) return raw;
+  throw new Error(`Unsupported --mcp-launch value: ${raw}. Supported: ${supportedMcpLaunchModes.join(", ")}`);
+}
+
+function buildGlobalMcpWrapperScript() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+export NVM_DIR="\${NVM_DIR:-$HOME/.nvm}"
+if [ -s "$NVM_DIR/nvm.sh" ]; then
+  . "$NVM_DIR/nvm.sh"
+elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+  export NVM_DIR="$HOME/.nvm"
+  . "$NVM_DIR/nvm.sh"
+fi
+
+if ! command -v ${recommendMcpBinaryName} >/dev/null 2>&1; then
+  echo "${recommendMcpBinaryName} not found on PATH. Install or reload nvm, then run: npm -g i ${recommendMcpPackageName}@latest" >&2
+  exit 127
+fi
+
+exec ${recommendMcpBinaryName} start "$@"
+`;
+}
+
+function ensureGlobalMcpWrapper(options = {}) {
+  const wrapperPath = getGlobalMcpWrapperPath(options);
+  ensureDir(path.dirname(wrapperPath));
+  fs.writeFileSync(wrapperPath, buildGlobalMcpWrapperScript(), "utf8");
+  try {
+    fs.chmodSync(wrapperPath, 0o755);
+  } catch {
+    // Some filesystems ignore POSIX executable bits; the path is still valid for POSIX hosts.
+  }
+  return wrapperPath;
+}
+
+function shouldDefaultRecommendDetachedMcpEnv(options = {}) {
+  const client = normalizeMcpClientName(options.client);
+  const agent = normalizeAgentName(options.agent);
   return client === "openclaw"
     || client === "qclaw"
     || agent === "openclaw"
@@ -764,10 +815,28 @@ function getAgentConfigOutputDir(options = {}) {
   return path.join(getStateHome(), "agent-mcp-configs");
 }
 
-function buildMcpLaunchConfig(options = {}) {
-  const command = typeof options.command === "string" && options.command.trim()
-    ? options.command.trim()
-    : defaultMcpCommand;
+function buildMcpLaunchConfig(options = {}) {
+  const mcpLaunchMode = normalizeMcpLaunchMode(options);
+  if (mcpLaunchMode === "global-wrapper") {
+    const args = parseJsonOption(options["args-json"], "args-json");
+    const env = parseJsonOption(options["env-json"], "env-json");
+    const launchConfig = {
+      command: ensureGlobalMcpWrapper(options),
+      args: Array.isArray(args) ? args : []
+    };
+    const mergedEnv = {
+      ...getDefaultMcpEnv(options),
+      ...(isPlainObject(env) ? env : {})
+    };
+    if (Object.keys(mergedEnv).length > 0) {
+      launchConfig.env = mergedEnv;
+    }
+    return launchConfig;
+  }
+
+  const command = typeof options.command === "string" && options.command.trim()
+    ? options.command.trim()
+    : defaultMcpCommand;
   const args = parseJsonOption(options["args-json"], "args-json");
   const env = parseJsonOption(options["env-json"], "env-json");
   const launchArgs = Array.isArray(args) && args.length > 0
@@ -2633,11 +2702,12 @@ function printHelp() {
   console.log("  boss-recommend-mcp init-config  Create screening-config.json if missing (prefer workspace config/, fallback ~/.boss-recommend-mcp)");
   console.log("  boss-recommend-mcp config set   Write baseUrl/apiKey/model (prefer workspace config/, fallback ~/.boss-recommend-mcp)");
   console.log("  boss-recommend-mcp set-port     Persist preferred Chrome debug port to screening-config.json");
-  console.log("  boss-recommend-mcp mcp-config   Generate MCP config JSON for Cursor/Trae(含 trae-cn)/Claude Code/OpenClaw/QClaw");
-  console.log("  boss-recommend-mcp doctor       Check config/runtime/calibration prerequisites (supports --agent trae-cn/qclaw/cursor/...)");
-  console.log("  boss-recommend-mcp calibrate    Disabled until CDP-only featured calibration is live-verified");
-  console.log("  boss-recommend-mcp launch-chrome Launch or reuse Chrome debug instance and open Boss recommend page");
-  console.log("  boss-recommend-mcp where        Print installed package, skill, and config paths");
+  console.log("  boss-recommend-mcp mcp-config   Generate MCP config JSON for Cursor/Trae(含 trae-cn)/Claude Code/OpenClaw/QClaw");
+  console.log("  boss-recommend-mcp doctor       Check config/runtime/calibration prerequisites (supports --agent trae-cn/qclaw/cursor/...)");
+  console.log("  boss-recommend-mcp calibrate    Disabled until CDP-only featured calibration is live-verified");
+  console.log("  boss-recommend-mcp launch-chrome Launch or reuse Chrome debug instance and open Boss recommend page");
+  console.log("  boss-recommend-mcp where        Print installed package, skill, and config paths");
+  console.log("  boss-recommend-mcp install --mcp-launch global-wrapper  Use ~/.boss-recommend-mcp/bin wrapper so npm global upgrades affect MCP hosts");
   console.log("");
   console.log("Run command:");
   console.log("  boss-recommend-mcp prepare-run --instruction \"...\" --overrides-file overrides.json --confirmation-file confirmation.json");
@@ -2665,14 +2735,15 @@ function printMcpConfig(options = {}) {
   }
 }
 
-async function installAll(options = {}) {
-  const runtimeDirsResult = await ensureRuntimeDirectories(options);
-  const skillResults = installSkill();
-  const configResult = await ensureUserConfig(options);
-  const mcpTemplateResult = writeMcpConfigFiles({ client: "all" });
-  const externalMcpResult = installExternalMcpConfigs(options);
-  const externalSkillResult = mirrorSkillToExternalDirs(options);
-  console.log(
+async function installAll(options = {}) {
+  const runtimeDirsResult = await ensureRuntimeDirectories(options);
+  const skillResults = installSkill();
+  const configResult = await ensureUserConfig(options);
+  const mcpLaunchMode = normalizeMcpLaunchMode(options);
+  const mcpTemplateResult = writeMcpConfigFiles({ ...options, agent: undefined, client: "all" });
+  const externalMcpResult = installExternalMcpConfigs(options);
+  const externalSkillResult = mirrorSkillToExternalDirs(options);
+  console.log(
     `Runtime directories prepared: created=${runtimeDirsResult.created.length}, existing=${runtimeDirsResult.existed.length}, failed=${runtimeDirsResult.failed.length}`
   );
   console.log(`- recommend runtime: ${runtimeDirsResult.stateHome}`);
@@ -2700,10 +2771,13 @@ async function installAll(options = {}) {
     console.warn(`screening-config.json skip default patch: ${configResult.patch_error}`);
   }
   console.log(`请在该目录修改 baseUrl/apiKey/model 并替换占位词后再运行：${path.dirname(configResult.path)}`);
-  console.log(`MCP config templates exported to: ${mcpTemplateResult.outputDir}`);
-  for (const item of mcpTemplateResult.files) {
-    console.log(`- ${item.client}: ${item.file}`);
-  }
+  console.log(`MCP config templates exported to: ${mcpTemplateResult.outputDir}`);
+  for (const item of mcpTemplateResult.files) {
+    console.log(`- ${item.client}: ${item.file}`);
+  }
+  if (mcpLaunchMode === "global-wrapper") {
+    console.log(`Upgrade-stable MCP wrapper: ${getGlobalMcpWrapperPath(options)}`);
+  }
   if (externalMcpResult.targets.length > 0) {
     console.log(`Auto-configured external MCP files: ${externalMcpResult.applied.length}`);
     for (const item of externalMcpResult.applied) {
@@ -3189,11 +3263,13 @@ export async function runCli(argv = process.argv) {
 }
 
 export const __testables = {
-  buildRecommendJobListCliInput,
-  buildBossChatCliInput,
-  buildDefaultMcpArgs,
-  buildMcpLaunchConfig,
-  collectRuntimeDirectories,
+  buildRecommendJobListCliInput,
+  buildBossChatCliInput,
+  buildDefaultMcpArgs,
+  buildMcpLaunchConfig,
+  ensureGlobalMcpWrapper,
+  getGlobalMcpWrapperPath,
+  collectRuntimeDirectories,
   ensureBossChatRuntimeReady: ensureBossChatRuntimeReadyLocal,
   ensureRuntimeDirectories,
   getBossChatCliRunTarget,