@ada-mcp/mcp-server 0.1.14 → 0.1.15

package/README.md

@@ -1,139 +1,139 @@
-# @ada-mcp/mcp-server
-
-ADA MCP server package that supports:
-
-- Local stdio mode (default) for MCP hosts
-- Remote HTTP mode (`server`) with API key authentication
-- MCP **Streamable HTTP** on `POST|GET|DELETE /mcp` (same port as legacy REST), with optional SSE per MCP spec (`@modelcontextprotocol/sdk` transport)
-
-## 标准安装（Cursor / MCP）
-
-请使用 **`@ada-mcp/launcher@0.1.11`** 拉起本包（见 [launcher README](../ada-mcp-launcher/README.md)）：
-
-```json
-{
-  "mcpServers": {
-    "ada-mcp": {
-      "command": "pnpm",
-      "args": ["dlx", "@ada-mcp/launcher@0.1.11"]
-    }
-  }
-}
-```
-
-本包版本：**`@ada-mcp/mcp-server@0.1.14`**（由 launcher 默认拉取；依赖锁定 `playwright@1.59.1`）。
-
-直接调试本包（无 launcher 拉包前测速）：
-
-```bash
-pnpm dlx @ada-mcp/mcp-server@0.1.14
-# npx 等价：
-npx -y @ada-mcp/mcp-server@0.1.14
-```
-
-## 启动时自动安装依赖（默认仅 Playwright）
-
-进程启动前会按配置自动执行 `install-deps`（日志在 stderr）：
-
-| 配置 | 含义 |
-|------|------|
-| （未配置） | 仅安装 **Playwright + 浏览器** |
-| `playwright` | 仅 Playwright（显式写法，与默认相同） |
-| `selenium` | **仅** Selenium 原生驱动（GeckoDriver/ChromeDriver） |
-| `appium` | **仅** Appium 包 + 移动端驱动 |
-| `playwright,selenium` | 组合（逗号连接多类） |
-| `all` | 上述全部 |
-| `none` / `skip` | 不自动安装 |
-
-**环境变量**
-
-- `ADA_MCP_INSTALL_DEPS`：范围，如 `playwright`、`playwright,selenium`、`all`、`none`
-- `ADA_MCP_SKIP_INSTALL_DEPS=1`：跳过自动安装
-- `ADA_MCP_INSTALL_DEPS_FORCE=1`：强制重装
-- `ADA_MCP_GECKODRIVER_VERSION` / `ADA_MCP_CHROMEDRIVER_VERSION`：Selenium 驱动版本
-- `ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS`：浏览器下载超时（默认 15 分钟）
-- `ADA_INSTALL_STRATEGY_TIMEOUT_MS`：npm 装包超时（默认 2 分钟）
-
-## 代理与镜像（`0.1.10+` 推荐）
-
-| 阶段 | 自动探测最快镜像 |
-|------|------------------|
-| `pnpm dlx @ada-mcp/launcher` | **是** — 拉包前测速（推荐） |
-| `pnpm dlx @ada-mcp/mcp-server` | tarball 仍走本机源；**同次安装的依赖**由 `preinstall` 测速（仅写入官方 Playwright CDN，`0.1.9+`） |
-| 启动后 `install-deps` | 是 — 内置国内镜像测速（**无需配置**） |
-
-默认 npm 探测候选（按优先级，延迟相同取靠前）：阿里云 npmmirror → 腾讯云 → 华为云 → npm 官方。
-
-| 变量 | 说明 |
-|------|------|
-| `npm_config_registry` | 可选；仅加速 **dlx** 拉包（推荐 `https://registry.npmmirror.com`） |
-| `ADA_REGISTRY_CANDIDATES` | 可选；在默认五镜像**之外**追加候选 |
-| `ADA_NPM_PROXY_REGISTRY` / `ADA_PNPM_PROXY_REGISTRY` | 可选；覆盖探测主候选（默认 npmmirror） |
-| `PLAYWRIGHT_DOWNLOAD_HOST` | 可选；Playwright 浏览器 CDN |
-
-详见 [ADA-MCP-接入手册 §3.9.2](../../docs/ADA-MCP-接入手册.md#392-代理与镜像配置)。
-
-**CLI 参数**（写在 MCP `args` 末尾）
-
-- `--install-deps=playwright,selenium`
-- `--skip-install-deps`
-- `--install-deps-force`
-- `--geckodriver-version=latest` `--chromedriver-version=match-chrome`
-
-在标准 `args` 后追加，例如安装全部依赖：
-
-```json
-"args": ["dlx", "@ada-mcp/launcher@0.1.11", "--install-deps=all"]
-```
-
-## Cursor MCP 配置
-
-**pnpm（推荐）**：`pnpm` + `dlx @ada-mcp/launcher@0.1.11`
-
-**npx 等价**（`launcher@0.1.7+`）：`npx` + `-y @ada-mcp/launcher@0.1.11`（内层同样 `npx -y` mcp-server，测速逻辑与 pnpm 一致）
-
-```json
-{
-  "mcpServers": {
-    "ada-mcp": {
-      "command": "npx",
-      "args": ["-y", "@ada-mcp/launcher@0.1.11"]
-    }
-  }
-}
-```
-
-Windows 若找不到 `pnpm`，可将 `command` 改为 `pnpm.cmd` 绝对路径；无 pnpm 时只能直接 `npx -y @ada-mcp/mcp-server@0.1.14`（无 launcher 拉包测速）。
-
-## Remote mode
-
-Set API key in environment variable first:
-
-```bash
-export ADA_MCP_REMOTE_API_KEY=your_token
-```
-
-Windows PowerShell:
-
-```powershell
-$env:ADA_MCP_REMOTE_API_KEY="your_token"
-```
-
-Then run:
-
-```bash
-pnpm dlx @ada-mcp/mcp-server server --host=127.0.0.1 --port=8787 --allow-risky=true --risky-mode=whitelist --risky-commands=custom
-```
-
-### Streamable HTTP (`/mcp`)
-
-- Endpoint: `http://<host>:<port>/mcp` — same API key headers as below (`x-api-key` or `Authorization: Bearer`).
-- First request: `POST /mcp` with JSON-RPC `initialize` (no `Mcp-Session-Id`); server returns a session id in `Mcp-Session-Id` response header.
-- Follow-up: `POST /mcp` with body + `Mcp-Session-Id`; for server-initiated streaming, open `GET /mcp` with `Accept: text/event-stream` and the same session header.
-- Session teardown: `DELETE /mcp` with `Mcp-Session-Id`.
-
-When listening on all interfaces (e.g. `--host=0.0.0.0`), set allowed Host headers to satisfy DNS rebinding checks:
-
-```bash
-pnpm dlx @ada-mcp/mcp-server server --host=0.0.0.0 --port=8787 --api-key=your_token --allowed-hosts=localhost,127.0.0.1
-```
+# @ada-mcp/mcp-server
+
+ADA MCP server package that supports:
+
+- Local stdio mode (default) for MCP hosts
+- Remote HTTP mode (`server`) with API key authentication
+- MCP **Streamable HTTP** on `POST|GET|DELETE /mcp` (same port as legacy REST), with optional SSE per MCP spec (`@modelcontextprotocol/sdk` transport)
+
+## 标准安装（Cursor / MCP）
+
+请使用 **`@ada-mcp/launcher@0.1.12`** 拉起本包（见 [launcher README](../ada-mcp-launcher/README.md)）：
+
+```json
+{
+  "mcpServers": {
+    "ada-mcp": {
+      "command": "pnpm",
+      "args": ["dlx", "@ada-mcp/launcher@0.1.12"]
+    }
+  }
+}
+```
+
+本包版本：**`@ada-mcp/mcp-server@0.1.15`**（由 launcher 默认拉取；依赖锁定 `playwright@1.59.1`）。
+
+直接调试本包（无 launcher 拉包前测速）：
+
+```bash
+pnpm dlx @ada-mcp/mcp-server@0.1.15
+# npx 等价：
+npx -y @ada-mcp/mcp-server@0.1.15
+```
+
+## 启动时自动安装依赖（默认仅 Playwright）
+
+进程启动前会按配置自动执行 `install-deps`（日志在 stderr）：
+
+| 配置 | 含义 |
+|------|------|
+| （未配置） | 仅安装 **Playwright + 浏览器** |
+| `playwright` | 仅 Playwright（显式写法，与默认相同） |
+| `selenium` | **仅** Selenium 原生驱动（GeckoDriver/ChromeDriver） |
+| `appium` | **仅** Appium 包 + 移动端驱动 |
+| `playwright,selenium` | 组合（逗号连接多类） |
+| `all` | 上述全部 |
+| `none` / `skip` | 不自动安装 |
+
+**环境变量**
+
+- `ADA_MCP_INSTALL_DEPS`：范围，如 `playwright`、`playwright,selenium`、`all`、`none`
+- `ADA_MCP_SKIP_INSTALL_DEPS=1`：跳过自动安装
+- `ADA_MCP_INSTALL_DEPS_FORCE=1`：强制重装
+- `ADA_MCP_GECKODRIVER_VERSION` / `ADA_MCP_CHROMEDRIVER_VERSION`：Selenium 驱动版本
+- `ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS`：浏览器下载超时（默认 15 分钟）
+- `ADA_INSTALL_STRATEGY_TIMEOUT_MS`：npm 装包超时（默认 2 分钟）
+
+## 代理与镜像（`0.1.10+` 推荐）
+
+| 阶段 | 自动探测最快镜像 |
+|------|------------------|
+| `pnpm dlx @ada-mcp/launcher` | **是** — 拉包前测速（推荐） |
+| `pnpm dlx @ada-mcp/mcp-server` | tarball 仍走本机源；**同次安装的依赖**由 `preinstall` 测速（仅写入官方 Playwright CDN，`0.1.9+`） |
+| 启动后 `install-deps` | 是 — 内置国内镜像测速（**无需配置**） |
+
+默认 npm 探测候选（按优先级，延迟相同取靠前）：阿里云 npmmirror → 腾讯云 → 华为云 → npm 官方。
+
+| 变量 | 说明 |
+|------|------|
+| `npm_config_registry` | 可选；仅加速 **dlx** 拉包（推荐 `https://registry.npmmirror.com`） |
+| `ADA_REGISTRY_CANDIDATES` | 可选；在默认五镜像**之外**追加候选 |
+| `ADA_NPM_PROXY_REGISTRY` / `ADA_PNPM_PROXY_REGISTRY` | 可选；覆盖探测主候选（默认 npmmirror） |
+| `PLAYWRIGHT_DOWNLOAD_HOST` | 可选；Playwright 浏览器 CDN |
+
+详见 [ADA-MCP-接入手册 §3.9.2](../../docs/ADA-MCP-接入手册.md#392-代理与镜像配置)。
+
+**CLI 参数**（写在 MCP `args` 末尾）
+
+- `--install-deps=playwright,selenium`
+- `--skip-install-deps`
+- `--install-deps-force`
+- `--geckodriver-version=latest` `--chromedriver-version=match-chrome`
+
+在标准 `args` 后追加，例如安装全部依赖：
+
+```json
+"args": ["dlx", "@ada-mcp/launcher@0.1.12", "--install-deps=all"]
+```
+
+## Cursor MCP 配置
+
+**pnpm（推荐）**：`pnpm` + `dlx @ada-mcp/launcher@0.1.12`
+
+**npx 等价**（`launcher@0.1.7+`）：`npx` + `-y @ada-mcp/launcher@0.1.12`（内层同样 `npx -y` mcp-server，测速逻辑与 pnpm 一致）
+
+```json
+{
+  "mcpServers": {
+    "ada-mcp": {
+      "command": "npx",
+      "args": ["-y", "@ada-mcp/launcher@0.1.12"]
+    }
+  }
+}
+```
+
+Windows 若找不到 `pnpm`，可将 `command` 改为 `pnpm.cmd` 绝对路径；无 pnpm 时只能直接 `npx -y @ada-mcp/mcp-server@0.1.15`（无 launcher 拉包测速）。
+
+## Remote mode
+
+Set API key in environment variable first:
+
+```bash
+export ADA_MCP_REMOTE_API_KEY=your_token
+```
+
+Windows PowerShell:
+
+```powershell
+$env:ADA_MCP_REMOTE_API_KEY="your_token"
+```
+
+Then run:
+
+```bash
+pnpm dlx @ada-mcp/mcp-server server --host=127.0.0.1 --port=8787 --allow-risky=true --risky-mode=whitelist --risky-commands=custom
+```
+
+### Streamable HTTP (`/mcp`)
+
+- Endpoint: `http://<host>:<port>/mcp` — same API key headers as below (`x-api-key` or `Authorization: Bearer`).
+- First request: `POST /mcp` with JSON-RPC `initialize` (no `Mcp-Session-Id`); server returns a session id in `Mcp-Session-Id` response header.
+- Follow-up: `POST /mcp` with body + `Mcp-Session-Id`; for server-initiated streaming, open `GET /mcp` with `Accept: text/event-stream` and the same session header.
+- Session teardown: `DELETE /mcp` with `Mcp-Session-Id`.
+
+When listening on all interfaces (e.g. `--host=0.0.0.0`), set allowed Host headers to satisfy DNS rebinding checks:
+
+```bash
+pnpm dlx @ada-mcp/mcp-server server --host=0.0.0.0 --port=8787 --api-key=your_token --allowed-hosts=localhost,127.0.0.1
+```

package/dist/cli.cjs

@@ -2887,7 +2887,7 @@ var init_config = __esm({
         ],
         nativeDriversDir: "dirver",
         geckodriverVersion: "latest",
-        chromedriverVersion: "latest"
+        chromedriverVersion: "match-chrome"
       },
       appium: {
         serverUrl: "http://127.0.0.1:4723",
@@ -3277,30 +3277,171 @@ async function resolveChromedriverCfTVersion(requested) {
   }
   return hit.version;
 }
-async function detectInstalledChromeMajorVersion() {
-  if (process.platform !== "win32") {
+function parseBrowserVersionString(raw) {
+  const match = raw.match(/(\d+\.\d+(?:\.\d+)*(?:\.\d+)?)/);
+  if (!match) {
     return void 0;
   }
-  const candidates = [
-    import_node_path4.default.join(process.env["ProgramFiles"] ?? "C:\\Program Files", "Google", "Chrome", "Application", "chrome.exe"),
-    import_node_path4.default.join(
-      process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)",
-      "Google",
-      "Chrome",
-      "Application",
-      "chrome.exe"
-    )
-  ];
-  for (const chromePath of candidates) {
-    if (!await fileExists(chromePath)) {
+  const version = match[1];
+  return { version, major: version.split(".")[0] };
+}
+async function runCommandCapture(command, args) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.spawn)(command, args, {
+      stdio: ["ignore", "pipe", "ignore"],
+      shell: process.platform === "win32"
+    });
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("exit", (code) => resolve(code === 0 ? out.trim() : void 0));
+    child.on("error", () => resolve(void 0));
+  });
+}
+async function detectChromeFromExecutable(exePath) {
+  if (!await fileExists(exePath)) {
+    return void 0;
+  }
+  if (process.platform === "win32") {
+    const version = await readWindowsFileVersion(exePath);
+    if (!version) {
+      return void 0;
+    }
+    const parsed2 = parseBrowserVersionString(version);
+    if (!parsed2) {
+      return void 0;
+    }
+    return { path: exePath, version: parsed2.version, major: parsed2.major };
+  }
+  const out = await runCommandCapture(exePath, ["--version"]);
+  if (!out) {
+    return void 0;
+  }
+  const parsed = parseBrowserVersionString(out);
+  if (!parsed) {
+    return void 0;
+  }
+  return { path: exePath, version: parsed.version, major: parsed.major };
+}
+async function detectFirefoxFromExecutable(exePath) {
+  if (!await fileExists(exePath)) {
+    return void 0;
+  }
+  if (process.platform === "win32") {
+    const version = await readWindowsFileVersion(exePath);
+    if (!version) {
+      return void 0;
+    }
+    const parsed2 = parseBrowserVersionString(version);
+    if (!parsed2) {
+      return void 0;
+    }
+    return { path: exePath, version: parsed2.version, major: parsed2.major };
+  }
+  const out = await runCommandCapture(exePath, ["--version"]);
+  if (!out) {
+    return void 0;
+  }
+  const parsed = parseBrowserVersionString(out);
+  if (!parsed) {
+    return void 0;
+  }
+  return { path: exePath, version: parsed.version, major: parsed.major };
+}
+async function detectLocalBrowsers() {
+  const result = {};
+  if (process.platform === "win32") {
+    const chromeCandidates = [
+      import_node_path4.default.join(process.env["ProgramFiles"] ?? "C:\\Program Files", "Google", "Chrome", "Application", "chrome.exe"),
+      import_node_path4.default.join(
+        process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)",
+        "Google",
+        "Chrome",
+        "Application",
+        "chrome.exe"
+      ),
+      import_node_path4.default.join(process.env["ProgramFiles"] ?? "C:\\Program Files", "Chromium", "Application", "chrome.exe")
+    ];
+    for (const p of chromeCandidates) {
+      const hit = await detectChromeFromExecutable(p);
+      if (hit) {
+        result.chrome = hit;
+        break;
+      }
+    }
+    const firefoxCandidates = [
+      import_node_path4.default.join(process.env["ProgramFiles"] ?? "C:\\Program Files", "Mozilla Firefox", "firefox.exe"),
+      import_node_path4.default.join(
+        process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)",
+        "Mozilla Firefox",
+        "firefox.exe"
+      )
+    ];
+    for (const p of firefoxCandidates) {
+      const hit = await detectFirefoxFromExecutable(p);
+      if (hit) {
+        result.firefox = hit;
+        break;
+      }
+    }
+    return result;
+  }
+  if (process.platform === "darwin") {
+    const chromePaths = [
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium"
+    ];
+    for (const p of chromePaths) {
+      const hit = await detectChromeFromExecutable(p);
+      if (hit) {
+        result.chrome = hit;
+        break;
+      }
+    }
+    const firefoxPath = "/Applications/Firefox.app/Contents/MacOS/firefox";
+    const ff = await detectFirefoxFromExecutable(firefoxPath);
+    if (ff) {
+      result.firefox = ff;
+    }
+    return result;
+  }
+  const chromeCommands = ["google-chrome-stable", "google-chrome", "chromium-browser", "chromium"];
+  for (const cmd of chromeCommands) {
+    if (!await commandOnPath(cmd)) {
       continue;
     }
-    const version = await readWindowsFileVersion(chromePath);
-    if (version) {
-      return version.split(".")[0];
+    const out = await runCommandCapture(cmd, ["--version"]);
+    const parsed = out ? parseBrowserVersionString(out) : void 0;
+    if (parsed) {
+      result.chrome = { path: cmd, version: parsed.version, major: parsed.major };
+      break;
     }
   }
-  return void 0;
+  if (await commandOnPath("firefox")) {
+    const out = await runCommandCapture("firefox", ["--version"]);
+    const parsed = out ? parseBrowserVersionString(out) : void 0;
+    if (parsed) {
+      result.firefox = { path: "firefox", version: parsed.version, major: parsed.major };
+    }
+  }
+  return result;
+}
+function logSeleniumDriverGuidance(onLogLine) {
+  onLogLine?.(
+    "[selenium] \u5B89\u88C5\u524D\u4F1A\u68C0\u6D4B\u672C\u673A Chrome/Chromium \u4E0E Firefox \u7248\u672C\uFF1B\u9A71\u52A8\u653E\u5165\u9879\u76EE\u76EE\u5F55\u540E\u53EF\u81EA\u884C\u66FF\u6362\u8986\u76D6\u3002"
+  );
+  onLogLine?.("[selenium] \u5404\u6D4F\u89C8\u5668\u9A71\u52A8\u624B\u52A8\u4E0B\u8F7D\u53C2\u8003\uFF1A");
+  for (const ref of SELENIUM_DRIVER_MANUAL_DOWNLOAD_REFERENCES) {
+    onLogLine?.(`[selenium]   ${ref.browser} (${ref.platforms}) \u2014 ${ref.vendor}: ${ref.url}`);
+  }
+  onLogLine?.(
+    "[selenium] \u81EA\u52A8\u4E0B\u8F7D\u5931\u8D25\u65F6\u5C06\u8DF3\u8FC7\u5BF9\u5E94\u9A71\u52A8\u5E76\u7EE7\u7EED\uFF0C\u8BF7\u6309\u4E0A\u8868\u81EA\u884C\u4E0B\u8F7D\u540E\u653E\u5165\u9A71\u52A8\u76EE\u5F55\u6216\u914D\u7F6E PATH/ADA_GECKODRIVER_PATH/ADA_CHROMEDRIVER_PATH\u3002"
+  );
+}
+async function detectInstalledChromeMajorVersion() {
+  const browsers = await detectLocalBrowsers();
+  return browsers.chrome?.major;
 }
 async function readWindowsFileVersion(exePath) {
   return new Promise((resolve) => {
@@ -3343,7 +3484,7 @@ async function downloadGeckodriver(driversDir, versionInput, onLogLine) {
   await import_promises4.default.mkdir(driversDir, { recursive: true });
   const zipPath = import_node_path4.default.join(driversDir, `_download_geckodriver_${version}.zip`);
   const extractDir = import_node_path4.default.join(driversDir, `_extract_geckodriver_${version}`);
-  onLogLine?.(`[selenium] \u4E0B\u8F7D geckodriver ${tag} \uFFFD\uFFFD?${driversDir}`);
+  onLogLine?.(`[selenium] \u4E0B\u8F7D geckodriver ${tag} \u2192 ${driversDir}`);
   onLogLine?.(`[selenium] URL: ${url}`);
   await downloadToFile(url, zipPath);
   await import_promises4.default.rm(extractDir, { recursive: true, force: true });
@@ -3356,7 +3497,7 @@ async function downloadGeckodriver(driversDir, versionInput, onLogLine) {
   await copyExecutable(found, dest);
   await import_promises4.default.rm(zipPath, { force: true });
   await import_promises4.default.rm(extractDir, { recursive: true, force: true });
-  onLogLine?.(`[selenium] geckodriver \u5DF2\u5199\uFFFD\uFFFD? ${dest}`);
+  onLogLine?.(`[selenium] geckodriver \u5DF2\u5199\u5165: ${dest}`);
   return { path: dest, version: tag };
 }
 async function downloadChromedriver(driversDir, versionInput, onLogLine) {
@@ -3376,7 +3517,7 @@ async function downloadChromedriver(driversDir, versionInput, onLogLine) {
   await import_promises4.default.mkdir(driversDir, { recursive: true });
   const zipPath = import_node_path4.default.join(driversDir, `_download_chromedriver_${major}.zip`);
   const extractDir = import_node_path4.default.join(driversDir, `_extract_chromedriver_${major}`);
-  onLogLine?.(`[selenium] \u4E0B\u8F7D chromedriver ${fullVersion} (\u4E3B\u7248\uFFFD\uFFFD?${major}) \uFFFD\uFFFD?${driversDir}`);
+  onLogLine?.(`[selenium] \u4E0B\u8F7D chromedriver ${fullVersion} (\u4E3B\u7248\u672C ${major}) \u2192 ${driversDir}`);
   onLogLine?.(`[selenium] URL: ${url}`);
   await downloadToFile(url, zipPath);
   await import_promises4.default.rm(extractDir, { recursive: true, force: true });
@@ -3393,7 +3534,7 @@ async function downloadChromedriver(driversDir, versionInput, onLogLine) {
   }
   await import_promises4.default.rm(zipPath, { force: true });
   await import_promises4.default.rm(extractDir, { recursive: true, force: true });
-  onLogLine?.(`[selenium] chromedriver \u5DF2\u5199\uFFFD\uFFFD? ${destVersioned}`);
+  onLogLine?.(`[selenium] chromedriver \u5DF2\u5199\u5165: ${destVersioned}`);
   return { path: destVersioned, version: fullVersion, major };
 }
 async function saveNativeDriverManifest(manifest, workspaceRoot) {
@@ -3403,38 +3544,91 @@ async function saveNativeDriverManifest(manifest, workspaceRoot) {
   const file = import_node_path4.default.join(dir, "native-drivers.json");
   await import_promises4.default.writeFile(file, JSON.stringify(manifest, null, 2), "utf8");
 }
+function resolveDefaultChromedriverVersion(requested, browsers) {
+  if (requested && requested !== "latest") {
+    return requested;
+  }
+  if (browsers.chrome?.major) {
+    return "match-chrome";
+  }
+  return requested ?? "latest";
+}
+function formatDownloadError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 async function ensureNativeWebDrivers(options = {}) {
   const root = options.workspaceRoot ?? await resolveWorkspaceRoot3();
   const driversDir = options.driversDir ?? await resolveNativeDriversDir(root);
   await import_promises4.default.mkdir(driversDir, { recursive: true });
   const log2 = options.onLogLine;
+  logSeleniumDriverGuidance(log2);
   log2?.(`[selenium] \u539F\u751F\u9A71\u52A8\u76EE\u5F55: ${driversDir}`);
+  const browsers = await detectLocalBrowsers();
+  if (browsers.chrome) {
+    log2?.(
+      `[selenium] \u68C0\u6D4B\u5230\u672C\u673A Chrome/Chromium: ${browsers.chrome.version} (\u4E3B\u7248\u672C ${browsers.chrome.major}) \u2014 ${browsers.chrome.path}`
+    );
+  } else {
+    log2?.("[selenium] \u672A\u68C0\u6D4B\u5230\u672C\u673A Chrome/Chromium\uFF08chromedriver \u5C06\u4F7F\u7528 latest \u6216\u663E\u5F0F\u6307\u5B9A\u7248\u672C\uFF09");
+  }
+  if (browsers.firefox) {
+    log2?.(
+      `[selenium] \u68C0\u6D4B\u5230\u672C\u673A Firefox: ${browsers.firefox.version} (\u4E3B\u7248\u672C ${browsers.firefox.major}) \u2014 ${browsers.firefox.path}`
+    );
+  } else {
+    log2?.("[selenium] \u672A\u68C0\u6D4B\u5230\u672C\u673A Firefox\uFF08geckodriver \u5C06\u4F7F\u7528 latest \u6216\u663E\u5F0F\u6307\u5B9A\u7248\u672C\uFF09");
+  }
   const localChromeVersions = await listLocalChromedriverVersions(driversDir);
   if (localChromeVersions.length > 0) {
-    log2?.(`[selenium] \u76EE\u5F55\u5185\u5DF2\uFFFD\uFFFD?chromedriver \u7248\u672C: ${localChromeVersions.join(", ")}`);
+    log2?.(`[selenium] \u76EE\u5F55\u5185\u5DF2\u6709 chromedriver \u7248\u672C: ${localChromeVersions.join(", ")}`);
+  }
+  const chromedriverRequest = resolveDefaultChromedriverVersion(options.chromedriverVersion, browsers);
+  if (chromedriverRequest === "match-chrome" && browsers.chrome) {
+    log2?.(
+      `[selenium] chromedriver \u5C06\u5C1D\u8BD5\u5339\u914D\u672C\u673A Chrome \u4E3B\u7248\u672C ${browsers.chrome.major}\uFF08chrome-for-testing \u76EE\u5F55\uFF09`
+    );
   }
   const localGecko = await findGeckodriverInDir(driversDir, options.geckodriverVersion);
   const hasLocalGecko = Boolean(localGecko && await fileExists(localGecko));
   let geckoVersion = options.geckodriverVersion;
   if (options.geckodriverVersion !== "skip" && (options.force || !hasLocalGecko)) {
-    const downloaded = await downloadGeckodriver(driversDir, options.geckodriverVersion ?? "latest", log2);
-    geckoVersion = downloaded.version;
+    try {
+      const downloaded = await downloadGeckodriver(driversDir, options.geckodriverVersion ?? "latest", log2);
+      geckoVersion = downloaded.version;
+    } catch (error) {
+      log2?.(`[selenium][warn] geckodriver \u81EA\u52A8\u4E0B\u8F7D\u5931\u8D25\uFF0C\u5DF2\u8DF3\u8FC7: ${formatDownloadError(error)}`);
+      log2?.(
+        "[selenium][warn] \u8BF7\u5C06 geckodriver \u653E\u5165\u4E0A\u8FF0\u76EE\u5F55\u6216\u914D\u7F6E PATH / ADA_GECKODRIVER_PATH\uFF1B\u53EF\u53C2\u8003 Mozilla \u53D1\u5E03\u9875\u624B\u52A8\u4E0B\u8F7D\u3002"
+      );
+    }
   } else if (hasLocalGecko) {
     log2?.(`[selenium] \u590D\u7528\u5DF2\u6709 geckodriver: ${localGecko}`);
   }
-  const localChrome = await findChromedriverInDir(driversDir, options.chromedriverVersion);
+  const localChrome = await findChromedriverInDir(driversDir, chromedriverRequest);
   const hasLocalChrome = Boolean(localChrome && await fileExists(localChrome.path));
-  if (options.chromedriverVersion !== "skip" && (options.force || !hasLocalChrome)) {
-    await downloadChromedriver(driversDir, options.chromedriverVersion ?? "latest", log2);
+  if (chromedriverRequest !== "skip" && (options.force || !hasLocalChrome)) {
+    try {
+      await downloadChromedriver(driversDir, chromedriverRequest ?? "latest", log2);
+    } catch (error) {
+      log2?.(`[selenium][warn] chromedriver \u81EA\u52A8\u4E0B\u8F7D\u5931\u8D25\uFF0C\u5DF2\u8DF3\u8FC7: ${formatDownloadError(error)}`);
+      if (browsers.chrome) {
+        log2?.(
+          `[selenium][warn] \u672C\u673A Chrome \u4E3B\u7248\u672C\u4E3A ${browsers.chrome.major}\uFF0C\u8BF7\u4E0B\u8F7D\u5339\u914D\u7248\u672C\u7684 chromedriver \u653E\u5165\u76EE\u5F55\u6216\u914D\u7F6E ADA_CHROMEDRIVER_PATH\u3002`
+        );
+      }
+      log2?.(
+        "[selenium][warn] \u53EF\u53C2\u8003 chrome-for-testing / chromedriver.storage \u624B\u52A8\u4E0B\u8F7D\uFF1B\u5DF2\u653E\u5165 dirver/ \u7684\u9A71\u52A8\u4F1A\u5728\u4E0B\u6B21\u542F\u52A8\u65F6\u81EA\u52A8\u590D\u7528\u3002"
+      );
+    }
   } else if (hasLocalChrome) {
-    log2?.(`[selenium] \u590D\u7528\u5DF2\u6709 chromedriver: ${localChrome.path} (\u4E3B\u7248\uFFFD\uFFFD?${localChrome.version})`);
+    log2?.(`[selenium] \u590D\u7528\u5DF2\u6709 chromedriver: ${localChrome.path} (\u4E3B\u7248\u672C ${localChrome.version})`);
   }
   const resolved = await resolveNativeDrivers({
     driversDir,
     workspaceRoot: root,
     selection: {
       geckodriverVersion: geckoVersion,
-      chromedriverVersion: options.chromedriverVersion ?? localChrome?.version
+      chromedriverVersion: chromedriverRequest ?? localChrome?.version
     }
   });
   await saveNativeDriverManifest(
@@ -3449,14 +3643,21 @@ async function ensureNativeWebDrivers(options = {}) {
   if (resolved.geckodriverPath) {
     process.env.ADA_GECKODRIVER_PATH = resolved.geckodriverPath;
     log2?.(`[selenium] \u4F7F\u7528 geckodriver: ${resolved.geckodriverPath}`);
+  } else if (options.geckodriverVersion !== "skip") {
+    log2?.("[selenium][warn] \u672A\u627E\u5230\u53EF\u7528 geckodriver\uFF08\u81EA\u52A8\u4E0B\u8F7D\u5DF2\u8DF3\u8FC7\u6216\u5931\u8D25\uFF0C\u8BF7\u624B\u52A8\u5B89\u88C5\uFF09");
   }
   if (resolved.chromedriverPath) {
     process.env.ADA_CHROMEDRIVER_PATH = resolved.chromedriverPath;
     log2?.(`[selenium] \u4F7F\u7528 chromedriver: ${resolved.chromedriverPath}`);
+  } else if (chromedriverRequest !== "skip") {
+    log2?.("[selenium][warn] \u672A\u627E\u5230\u53EF\u7528 chromedriver\uFF08\u81EA\u52A8\u4E0B\u8F7D\u5DF2\u8DF3\u8FC7\u6216\u5931\u8D25\uFF0C\u8BF7\u624B\u52A8\u5B89\u88C5\uFF09");
+  }
+  if (!resolved.geckodriverOk && !resolved.chromedriverOk) {
+    log2?.("[selenium][warn] \u5F53\u524D\u65E0\u53EF\u7528\u539F\u751F WebDriver\uFF1BSelenium \u4EFB\u52A1\u53EF\u80FD\u5931\u8D25\uFF0C\u8BF7\u6309\u4E0A\u6587\u53C2\u8003\u5730\u5740\u81EA\u884C\u4E0B\u8F7D\u3002");
   }
   return resolved;
 }
-var import_node_child_process, import_promises4, import_node_path4, DEFAULT_NATIVE_DRIVERS_DIR, CHROME_FOR_TESTING_JSON;
+var import_node_child_process, import_promises4, import_node_path4, DEFAULT_NATIVE_DRIVERS_DIR, CHROME_FOR_TESTING_JSON, SELENIUM_DRIVER_MANUAL_DOWNLOAD_REFERENCES;
 var init_src2 = __esm({
   "../../packages/native-drivers/src/index.ts"() {
     "use strict";
@@ -3465,6 +3666,44 @@ var init_src2 = __esm({
     import_node_path4 = __toESM(require("node:path"), 1);
     DEFAULT_NATIVE_DRIVERS_DIR = "dirver";
     CHROME_FOR_TESTING_JSON = "https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json";
+    SELENIUM_DRIVER_MANUAL_DOWNLOAD_REFERENCES = [
+      {
+        browser: "Chrome/Chromium",
+        platforms: "Windows/Linux/macOS",
+        vendor: "\u8C37\u6B4C",
+        url: "https://chromedriver.storage.googleapis.com/index.html"
+      },
+      {
+        browser: "Firefox",
+        platforms: "Windows/Linux/macOS",
+        vendor: "Mozilla",
+        url: "https://github.com/mozilla/geckodriver/releases"
+      },
+      {
+        browser: "Edge",
+        platforms: "win10",
+        vendor: "\u5FAE\u8F6F",
+        url: "https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/"
+      },
+      {
+        browser: "Internet Explorer",
+        platforms: "Windows",
+        vendor: "Selenium \u9879\u76EE\u7EC4",
+        url: "https://selenium-release.storage.googleapis.com/index.html"
+      },
+      {
+        browser: "Safari",
+        platforms: "macOS El Capitan \u53CA\u66F4\u9AD8\u7248\u672C",
+        vendor: "\u82F9\u679C",
+        url: "\uFF08\u7CFB\u7EDF\u5185\u7F6E\uFF0C\u65E0\u9700\u5355\u72EC\u4E0B\u8F7D\uFF09"
+      },
+      {
+        browser: "Opera",
+        platforms: "Windows/macOS/Linux",
+        vendor: "Opera",
+        url: "https://github.com/operasoftware/operachromiumdriver/releases"
+      }
+    ];
   }
 });
 
@@ -3543,7 +3782,7 @@ function runCommand2(command, args, options) {
     });
   });
 }
-function runCommandCapture(command, args) {
+function runCommandCapture2(command, args) {
   return new Promise((resolve) => {
     const child = (0, import_node_child_process2.spawn)(command, args, {
       stdio: ["ignore", "pipe", "pipe"],
@@ -3665,7 +3904,7 @@ async function ensureNodeEnvironmentForInstall(onLogLine) {
   const requiredNpmMajor = 10;
   const runtimeNode = process.versions.node;
   const runtimeMajor = majorOf(runtimeNode);
-  const nodeVersion = await runCommandCapture("node", ["-v"]);
+  const nodeVersion = await runCommandCapture2("node", ["-v"]);
   if (nodeVersion.code === 0) {
     const nodeMajor = majorOf(nodeVersion.stdout);
     onLogLine?.(`[deps] Node \u7248\u672C\u68C0\u6D4B\uFF1A\u7CFB\u7EDF=${nodeVersion.stdout}\uFF0C\u5185\u7F6E=${runtimeNode}`);
@@ -3684,7 +3923,7 @@ async function ensureNodeEnvironmentForInstall(onLogLine) {
       `[deps][warn] \u672A\u4ECE PATH \u68C0\u6D4B\u5230 node\uFF0C\u5F53\u524D\u8FD0\u884C\u65F6 Node.js=${runtimeNode}\uFF08\u53EF\u6267\u884C\u7A0B\u5E8F\u5185\u7F6E\uFF09\uFF0C\u7EE7\u7EED\u5C1D\u8BD5\u5B89\u88C5\u3002`
     );
   }
-  const npmVersion = await runCommandCapture("npm", ["-v"]);
+  const npmVersion = await runCommandCapture2("npm", ["-v"]);
   if (npmVersion.code !== 0) {
     const message = "\u672A\u68C0\u6D4B\u5230\u53EF\u7528\u7684 npm\uFF08PATH \u4E2D\u4E0D\u53EF\u7528\uFF09\u3002\u8BF7\u5B89\u88C5 Node.js 22+\uFF08\u542B npm\uFF09\u5E76\u91CD\u542F\u7EC8\u7AEF\u540E\u91CD\u8BD5\u3002";
     onLogLine?.(`[deps] ${message}`);
@@ -3737,7 +3976,7 @@ async function resolveCompatibleDriverSpecs(driver) {
   const preferred = driver === "uiautomator2" ? process.env.ADA_APPIUM_DRIVER_SPEC_UIAUTOMATOR2 ?? `${pkg}@2` : process.env.ADA_APPIUM_DRIVER_SPEC_XCUITEST ?? `${pkg}@7`;
   const fallbackRange = driver === "uiautomator2" ? process.env.ADA_APPIUM_DRIVER_RANGE_UIAUTOMATOR2 ?? "<3" : process.env.ADA_APPIUM_DRIVER_RANGE_XCUITEST ?? "<8";
   const specs = [preferred];
-  const view = await runCommandCapture("npm", ["view", `${pkg}@${fallbackRange}`, "version"]);
+  const view = await runCommandCapture2("npm", ["view", `${pkg}@${fallbackRange}`, "version"]);
   if (view.code === 0 && view.stdout) {
     const version = view.stdout.trim().split(/\r?\n/).pop()?.trim();
     if (version) {
@@ -4159,7 +4398,7 @@ async function verifyAppiumCommand() {
   }
 }
 async function getInstalledAppiumDrivers() {
-  const check = await runCommandCapture("npm", ["exec", "appium", "driver", "list", "--installed", "--json"]);
+  const check = await runCommandCapture2("npm", ["exec", "appium", "driver", "list", "--installed", "--json"]);
   if (check.code === 0 && check.stdout) {
     try {
       const parsed = JSON.parse(check.stdout);
@@ -4168,7 +4407,7 @@ async function getInstalledAppiumDrivers() {
     } catch {
     }
   }
-  const fallback = await runCommandCapture("npm", ["exec", "appium", "driver", "list", "--installed"]);
+  const fallback = await runCommandCapture2("npm", ["exec", "appium", "driver", "list", "--installed"]);
   if (fallback.code !== 0) {
     return [];
   }
@@ -4238,6 +4477,7 @@ async function ensureSeleniumNativeDrivers(config, options, onLogLine) {
   }
   const geckoVer = options?.geckodriverVersion ?? config.dependencies.geckodriverVersion ?? "latest";
   const chromeVer = options?.chromedriverVersion ?? config.dependencies.chromedriverVersion ?? "latest";
+  onLogLine?.("[selenium] \u5C06\u68C0\u6D4B\u672C\u673A Chrome/Firefox \u7248\u672C\u5E76\u5C1D\u8BD5\u5339\u914D\u9A71\u52A8\uFF1B\u4E0B\u8F7D\u5931\u8D25\u65F6\u8DF3\u8FC7\u5E76\u63D0\u793A\u624B\u52A8\u4E0B\u8F7D\uFF08\u89C1\u5B89\u88C5\u65E5\u5FD7\u53C2\u8003\u5730\u5740\uFF09\u3002");
   try {
     const catalog = await listChromedriverCfTVersions();
     onLogLine?.(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ada-mcp/mcp-server",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "ADA MCP server for web/mobile automation (stdio + remote HTTP)",
   "private": false,
   "type": "commonjs",