@mindstone/mcp-server-browser-automation 0.2.2 → 0.2.4

package/README.md

@@ -9,7 +9,7 @@ Browser control you can watch: open pages, sign in, click around, fill forms, ta
 
 ## Status
 
-- **Version:** [0.2.2](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-browser-automation)
+- **Version:** [0.2.4](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-browser-automation)
 - **Auth:** None ([`server.json`](./server.json))
 - **Tools:** [21](./src/tools/) (navigation, observation, interaction, sessions, files)
 - **Surface:** browser-automation
@@ -44,7 +44,7 @@ Response (trimmed):
 
 - Node.js 20+
 - npm
-- The `agent-browser` CLI on `PATH`, or `npx` available so the server can install it automatically.
+- Nothing else to install for the CLI: the server ships `agent-browser` as a dependency.
 
 <!-- BEGIN INSTALL_LINKS: do not edit by hand; regenerated by scripts/gen-install-links.mjs -->
 ## One-click install
@@ -94,20 +94,16 @@ npm install -g @mindstone/mcp-server-browser-automation
 mcp-server-browser-automation
 ```
 
-This server requires the `agent-browser` CLI binary to control the browser.
+This server uses the `agent-browser` CLI to control the browser.
 
 ### Binary Resolution
 
-1. **PATH lookup** (preferred): If `agent-browser` is on your PATH, it is used directly.
-2. **npx fallback**: If the binary is not found, the server automatically falls back to `npx -y agent-browser@0.33.2`.
+1. **PATH lookup** (preferred): If an `agent-browser` executable is on your PATH, it is used directly.
+2. **Bundled copy**: Otherwise the server runs the `agent-browser` package it ships as a dependency (pinned to 0.33.2), with the same Node that runs the server. No shell and no `npx` are involved, so this works the same on Windows, macOS and Linux.
 
 ### Installing agent-browser
 
-```bash
-npm install -g agent-browser
-```
-
-Or let the npx fallback handle it automatically (slower on first use due to download).
+Nothing to do: installing this server installs `agent-browser` with it. A separate executable on PATH takes precedence. On Windows, npm's `.cmd` shims cannot be used, so the bundled copy runs instead.
 
 ## Configuration
 
@@ -117,6 +113,7 @@ No API keys or credentials are required. The server communicates with the browse
 |---|---|---|
 | `AGENT_BROWSER_SESSION_NAME` | No | Session name for browser persistence (default: `mcp`) |
 | `AGENT_BROWSER_SHOW_WINDOW` | No | Set to `false` to run without a visible browser window. Default is visible (`true`). |
+| `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` | No | Periodic session autosave interval in milliseconds (needs `agent-browser` 0.31.2 or later). Default `0` (off), because each periodic save briefly opens a tab that brings a visible browser window in front of other apps. The session is still saved when the browser closes (`browser_close`). Any value you set is passed through as-is; an empty or non-numeric value gets the CLI's 30-second default. The `agent-browser` daemon reads it when it starts, so an already-running daemon keeps its previous setting until it exits (for example after `browser_close`). |
 | `MCP_WORKSPACE_PATH` | No | Workspace directory that `browser_pdf` writes into and `browser_upload` reads from. Defaults to the system temp directory. See [Security notes](#security-notes). |
 
 ### MCP Host Configuration

package/dist/browser-client.d.ts

@@ -21,13 +21,9 @@ export interface ExecOptions {
  * on the CLI — passing one would be a CLI error — so headless is the absence
  * of `--headed`.
  *
- * Falls back to `npx -y agent-browser@<NPX_FALLBACK_VERSION>` if the binary is
- * not on PATH. Uses execFile (no shell) to prevent command injection.
+ * Runs an `agent-browser` executable from PATH when there is one; otherwise
+ * runs the connector's own agent-browser dependency with this Node. Both use
+ * execFile with no shell, so no argument is ever interpreted by a shell.
  */
 export declare function execAgentBrowser(args: string[], options?: ExecOptions): Promise<ExecResult>;
-/**
- * Reset the resolved binary cache.
- * Primarily used for testing to reset state between test runs.
- */
-export declare function resetBinaryCache(): void;
 //# sourceMappingURL=browser-client.d.ts.map

package/dist/browser-client.js

@@ -1,16 +1,23 @@
 import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { promisify } from 'node:util';
 import { ConnectorError, DEFAULT_TIMEOUT_MS, SESSION_NAME } from './types.js';
 import { wrapUntrusted } from './untrusted-content.js';
 const execFileAsync = promisify(execFile);
-let resolvedBinary = null;
-function resolveAgentBrowser() {
-    if (resolvedBinary)
-        return resolvedBinary;
-    // Default to the binary name — execFile will search PATH.
-    // If not found (ENOENT), the caller falls back to npx.
-    resolvedBinary = 'agent-browser';
-    return resolvedBinary;
+const MAX_BUFFER = 10 * 1024 * 1024; // 10MB for large snapshots
+let bundledEntry = null;
+/**
+ * Path to the JS entry of the agent-browser package this connector depends
+ * on. Run with `process.execPath` rather than through an npm `.cmd` shim or
+ * npx: on Windows, execFile cannot start a shim without a shell, and npx
+ * reaches the CLI through cmd.exe, which cuts arguments at the first newline.
+ * Throws MODULE_NOT_FOUND when the dependency is missing.
+ */
+function resolveBundledEntry() {
+    if (!bundledEntry) {
+        bundledEntry = createRequire(import.meta.url).resolve('agent-browser/bin/agent-browser.js');
+    }
+    return bundledEntry;
 }
 function buildEnv() {
     const env = { ...process.env };
@@ -18,6 +25,16 @@ function buildEnv() {
     if (!env.AGENT_BROWSER_SESSION_NAME) {
         env.AGENT_BROWSER_SESSION_NAME = SESSION_NAME;
     }
+    // A session name turns on the CLI's periodic autosave (every 30s by
+    // default, agent-browser >= 0.31.2). Each save opens a temporary tab, which
+    // brings a visible browser window in front of the user's other apps.
+    // Save-on-close still persists the session, so periodic saves stay off
+    // unless the host sets an interval. A host value, including an empty
+    // string, passes through untouched; the CLI treats empty or non-numeric
+    // values as its 30s default. The daemon reads this only when it starts.
+    if (env.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS === undefined) {
+        env.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS = '0';
+    }
     return env;
 }
 /**
@@ -44,18 +61,6 @@ function resolveHeaded(optionHeaded, env) {
         return false;
     return true;
 }
-/**
- * Pinned version of agent-browser used by the npx fallback.
- *
- * Why pinned: keeps fallback behavior reproducible. Bump when verified against
- * a newer release. Do not use `latest` — npx caches by spec, and an unpinned
- * spec produces flaky behavior across machines.
- *
- * 0.33.2 verified 2026-08-05 against the connector's full command surface
- * (open, snapshot -i, screenshot, pdf, get url/title/text, tab, click/fill/
- * type/press/scroll/select/hover, eval, back/forward, wait, close).
- */
-const NPX_FALLBACK_VERSION = '0.33.2';
 /**
  * Build the ConnectorError message for a failed CLI invocation.
  *
@@ -89,8 +94,9 @@ function cliFailureMessage(command, stderr, stdout) {
  * on the CLI — passing one would be a CLI error — so headless is the absence
  * of `--headed`.
  *
- * Falls back to `npx -y agent-browser@<NPX_FALLBACK_VERSION>` if the binary is
- * not on PATH. Uses execFile (no shell) to prevent command injection.
+ * Runs an `agent-browser` executable from PATH when there is one; otherwise
+ * runs the connector's own agent-browser dependency with this Node. Both use
+ * execFile with no shell, so no argument is ever interpreted by a shell.
  */
 export async function execAgentBrowser(args, options) {
     const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -101,59 +107,46 @@ export async function execAgentBrowser(args, options) {
     if (resolveHeaded(options?.headed, env) && args.length > 0) {
         args = [args[0], '--headed', ...args.slice(1)];
     }
-    const binary = resolveAgentBrowser();
-    try {
+    const run = async (file, fileArgs) => {
         // execFile is safe against command injection (no shell interpretation)
-        const result = await execFileAsync(binary, args, {
+        const result = await execFileAsync(file, fileArgs, {
             env,
             timeout: timeoutMs,
-            maxBuffer: 10 * 1024 * 1024, // 10MB for large snapshots
+            maxBuffer: MAX_BUFFER,
+            // GUI hosts should not open a console window for each CLI call on Windows.
+            windowsHide: true,
         });
         return { stdout: result.stdout, stderr: result.stderr ?? '' };
+    };
+    try {
+        return await run('agent-browser', args);
     }
     catch (error) {
-        const err = error;
-        // Binary not found on PATH — try npx fallback (pulls a pinned version
-        // from the npm cache / registry).
-        if (err.code === 'ENOENT') {
-            try {
-                const npxResult = await execFileAsync('npx', ['-y', `agent-browser@${NPX_FALLBACK_VERSION}`, ...args], {
-                    env,
-                    timeout: timeoutMs + 15_000, // extra time for npx install
-                    maxBuffer: 10 * 1024 * 1024,
-                });
-                return { stdout: npxResult.stdout, stderr: npxResult.stderr ?? '' };
-            }
-            catch (npxError) {
-                const npxErr = npxError;
-                // Distinguish: npx itself missing (true binary-not-found) vs
-                // agent-browser ran but returned non-zero (CLI error surfaced via npx).
-                if (npxErr.code === 'ENOENT') {
-                    throw new ConnectorError(`agent-browser binary not found on PATH and npx is also unavailable: ${npxErr.message ?? String(npxErr)}`, 'BINARY_NOT_FOUND', 'Install agent-browser: npm install -g agent-browser\n' +
-                        'Or ensure npx is available on PATH.');
-                }
-                // npx ran but the underlying CLI exited non-zero — propagate as CLI_ERROR
-                // with the (enveloped) stderr for diagnosis.
-                throw new ConnectorError(cliFailureMessage(args[0], npxErr.stderr, npxErr.stdout), 'CLI_ERROR', 'The agent-browser CLI command failed (via npx fallback). ' +
-                    'Check the error details above. ' +
-                    'For best performance, install agent-browser globally: npm install -g agent-browser');
-            }
+        if (error.code !== 'ENOENT') {
+            throw classifyFailure(error, args[0], timeoutMs);
         }
-        // Timeout — name only the subcommand: the full argument vector may carry
-        // sensitive values (URLs with userinfo, selectors, filenames, typed
-        // values, evaluation scripts) and must not be echoed to the model.
-        if (err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' || err.killed) {
-            throw new ConnectorError(`Command timed out after ${timeoutMs}ms: agent-browser ${args[0]}`, 'TIMEOUT', 'The browser operation took too long. Try a simpler action or increase the timeout.');
-        }
-        // Other errors — include the (enveloped) stderr for diagnostics
-        throw new ConnectorError(cliFailureMessage(args[0], err.stderr, err.stdout), 'CLI_ERROR', 'The agent-browser CLI command failed. Check that agent-browser is installed and the browser session is active.');
+    }
+    // Not on PATH: run the bundled copy.
+    try {
+        return await run(process.execPath, [resolveBundledEntry(), ...args]);
+    }
+    catch (error) {
+        throw classifyFailure(error, args[0], timeoutMs);
     }
 }
-/**
- * Reset the resolved binary cache.
- * Primarily used for testing to reset state between test runs.
- */
-export function resetBinaryCache() {
-    resolvedBinary = null;
+function classifyFailure(error, command, timeoutMs) {
+    const err = error;
+    // Timeout — name only the subcommand: the full argument vector may carry
+    // sensitive values (URLs with userinfo, selectors, filenames, typed
+    // values, evaluation scripts) and must not be echoed to the model.
+    if (err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' || err.killed) {
+        return new ConnectorError(`Command timed out after ${timeoutMs}ms: agent-browser ${command}`, 'TIMEOUT', 'The browser operation took too long. Try a simpler action or increase the timeout.');
+    }
+    // Neither a PATH executable nor the bundled dependency could be started.
+    if (err.code === 'MODULE_NOT_FOUND' || err.code === 'ENOENT') {
+        return new ConnectorError('agent-browser is not on PATH and the copy bundled with this connector could not be found', 'BINARY_NOT_FOUND', "This connector's installation is incomplete. Reinstall the connector.");
+    }
+    // Other errors — include the (enveloped) stderr for diagnostics
+    return new ConnectorError(cliFailureMessage(command, err.stderr, err.stdout), 'CLI_ERROR', 'The agent-browser CLI command failed. Check that agent-browser is installed and the browser session is active.');
 }
 //# sourceMappingURL=browser-client.js.map

package/dist/index.d.ts

@@ -7,10 +7,12 @@
  * Sessions persist automatically between invocations.
  *
  * Requirements:
- * - agent-browser CLI binary on PATH, or npx available for fallback
+ * - agent-browser executable on PATH, or the bundled dependency run with this Node
  *
  * Environment variables:
  * - AGENT_BROWSER_SESSION_NAME: Session name for persistence (default: "mcp")
+ * - AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: Periodic session autosave interval in ms (default: "0", off;
+ *   the session is still saved on close). Read when the agent-browser daemon starts.
  * - MCP_DISABLE_GRACEFUL_FS=1: Disable the graceful-fs EMFILE mitigation patch
  */
 import './installGracefulFs.js';

package/dist/index.js

@@ -7,10 +7,12 @@
  * Sessions persist automatically between invocations.
  *
  * Requirements:
- * - agent-browser CLI binary on PATH, or npx available for fallback
+ * - agent-browser executable on PATH, or the bundled dependency run with this Node
  *
  * Environment variables:
  * - AGENT_BROWSER_SESSION_NAME: Session name for persistence (default: "mcp")
+ * - AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: Periodic session autosave interval in ms (default: "0", off;
+ *   the session is still saved on close). Read when the agent-browser daemon starts.
  * - MCP_DISABLE_GRACEFUL_FS=1: Disable the graceful-fs EMFILE mitigation patch
  */
 // MUST be the very first import — installs the graceful-fs EMFILE mitigation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstone/mcp-server-browser-automation",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "mcpName": "io.github.mindstone/mcp-server-browser-automation",
   "description": "Browser automation MCP server — visible-by-default browser control via accessibility snapshots, navigation, form filling, screenshots, and tab management. Set AGENT_BROWSER_SHOW_WINDOW=false to run quietly.",
   "license": "FSL-1.1-MIT",
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "agent-browser": "0.33.2",
     "graceful-fs": "^4.2.11",
     "zod": "^3.23.0"
   },