@nuwax-ai/nuwa-browser-mcp 0.5.3 → 0.5.4

package/README.md

@@ -57,6 +57,17 @@ npx -y @nuwax-ai/nuwa-browser-mcp doctor
 
 典型循环：`nuwa_taskspace_use` → `nuwa_navigate` → `nuwa_snapshot` → `nuwa_click` / `nuwa_type` → `nuwa_snapshot`（验证）。
 
+## 服务器 / 无头部署（Linux）
+
+无显示器的 Linux 服务器可以整套跑（安装器自动用 xvfb 虚拟显示拉起应用）：
+
+```bash
+curl -fsSL https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-browser/install-from-s3.sh | bash -s -- --no-skill --no-sandbox
+npx -y @nuwax-ai/nuwa-browser-mcp doctor
+```
+
+要点：root / 容器必须 `--no-sandbox`（Chromium 硬性限制，root 无法开沙箱）；GUI 在 xvfb 虚拟显示内运行，需要人看时可用 VNC。注意 MCP server 与应用必须**同机**——它是本机 IPC 薄传输，不支持脱离桌面应用单独云托管。
+
 ## 排障
 
 ```bash

package/dist/cli.js

@@ -48,7 +48,11 @@ export function defaultCliPath() {
                 return c;
         }
     }
-    throw new Error("nuwa-browser CLI not found — install the app (install-from-s3.sh) or set NUWA_BROWSER_BIN");
+    throw new Error("nuwa-browser CLI not found — this MCP server drives the nuwa-browser desktop app, " +
+        "which must be installed (and running) on this machine.\n" +
+        "  install: curl -fsSL https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-browser/install-from-s3.sh | bash\n" +
+        "  verify:  npx -y @nuwax-ai/nuwa-browser-mcp doctor\n" +
+        "  (or set NUWA_BROWSER_BIN to an existing CLI path)");
 }
 const CMD_SPECIAL_RE = /[\s"^&|<>()]/;
 function quoteCmdArg(a) {

package/dist/doctor.js

@@ -33,6 +33,9 @@ export async function doctor() {
         console.log(`[fail] app IPC check: ${res.output.trim() || `(exit=${res.code})`}`);
         if (/cannot connect|socket|ECONNREFUSED|ENOENT/i.test(res.output)) {
             console.log("       fix: start the nuwa-browser app and retry");
+            if (process.platform === "linux") {
+                console.log("       server/headless: install with --no-sandbox; the installer launches the app under xvfb-run when no display is present");
+            }
         }
         return 1;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuwax-ai/nuwa-browser-mcp",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "MCP server exposing nuwa-browser — any MCP client can drive the agent browser (navigate, snapshot, click, type, collect).",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   },
   "main": "dist/index.js",
   "files": [
-    "dist"
+    "dist",
+    "preflight.mjs"
   ],
   "engines": {
     "node": ">=22"
@@ -46,6 +47,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
-    "test": "pnpm run build && node --test \"src/**/*.test.mjs\""
+    "test": "pnpm run build && node --test \"src/**/*.test.mjs\"",
+    "postinstall": "node preflight.mjs"
   }
 }

package/preflight.mjs

@@ -0,0 +1,43 @@
+/**
+ * preflight.mjs — best-effort install-time hint (npm postinstall).
+ *
+ * The MCP server is a thin transport over the nuwa-browser desktop app: it
+ * spawns the local `nuwa-browser` CLI, which talks to the running app's IPC
+ * socket. This script tells the operator at install time whether that
+ * prerequisite exists. It NEVER fails the install — worst case it prints the
+ * install one-liner. (Skipped silently under --ignore-scripts.)
+ */
+import { existsSync } from "node:fs";
+
+const INSTALL_CMD =
+  "curl -fsSL https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-browser/install-from-s3.sh | bash";
+
+let cliPath = null;
+try {
+  const { defaultCliPath } = await import("./dist/cli.js");
+  cliPath = defaultCliPath();
+} catch {
+  // dist not built yet (fresh checkout) — nothing to probe.
+}
+
+const isWin = process.platform === "win32";
+const appMarkers = isWin
+  ? [`${process.env.USERPROFILE || ""}\\AppData\\Local\\Programs\\nuwa-browser\\nuwa-browser.exe`]
+  : ["/Applications/nuwa-browser.app", "/opt/nuwa-browser"];
+const appInstalled = appMarkers.some((p) => p && existsSync(p));
+
+if (!cliPath) {
+  console.warn(
+    `[nuwa-mcp] nuwa-browser CLI not found on this machine.\n` +
+      `  This MCP server drives the nuwa-browser desktop app (same machine) — install it first:\n` +
+      `    ${INSTALL_CMD}\n` +
+      `  then verify with: npx -y @nuwax-ai/nuwa-browser-mcp doctor`,
+  );
+} else if (!appInstalled) {
+  console.warn(
+    `[nuwa-mcp] nuwa-browser CLI found (${cliPath}), but no desktop app install was detected.\n` +
+      `  If tools fail, re-run the installer: ${INSTALL_CMD}`,
+  );
+} else {
+  console.log(`[nuwa-mcp] nuwa-browser detected (CLI: ${cliPath}) — ready.`);
+}