@mindstone/mcp-server-browser-automation 0.1.7

package/LICENSE

@@ -0,0 +1,97 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Mindstone Learning Limited
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+**Licensor**: Mindstone Learning Limited
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+**Software**: Browser Automation MCP Server
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A "Competing
+Use" means making the Software available to third parties as a commercial
+hosted service that directly competes with any product or service provided by
+the Licensor.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, OF
+ANY CHARACTER INCLUDING DAMAGES FOR LOSS OF GOODWILL, LOST PROFITS, LOST SALES
+OR BUSINESS, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, LOST CONTENT,
+DATA OR DATA USE, BREACH OF DUTY OF GOOD FAITH, OR ANY AND ALL OTHER DAMAGES
+OR LOSSES OF ANY KIND OR NATURE WHATSOEVER (WHETHER DIRECT, INDIRECT, SPECIAL,
+COLLATERAL, INCIDENTAL, CONSEQUENTIAL OR OTHERWISE) ARISING OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THIS LICENSE, EVEN IF SUCH PARTY SHALL HAVE
+BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+### Trademark
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Change Date
+
+Four years from the date the Software is made available under these Terms and
+Conditions: **2030-04-08**
+
+## Change License
+
+MIT License
+
+## License Details
+
+| Parameter | Value |
+|---|---|
+| Licensor | Mindstone Learning Limited |
+| Software | Browser Automation MCP Server |
+| Use Limitation | Competing Use |
+| Change Date | 2030-04-08 |
+| Change License | MIT |

package/README.md

@@ -0,0 +1,134 @@
+# Browser Automation MCP Server
+
+Headless browser control via accessibility snapshots — navigate pages, fill forms, click elements, take screenshots, and manage tabs using the [agent-browser](https://www.npmjs.com/package/agent-browser) CLI.
+
+## Installation
+
+```bash
+npx -y @mindstone/mcp-server-browser-automation
+```
+
+Or install globally:
+
+```bash
+npm install -g @mindstone/mcp-server-browser-automation
+mcp-server-browser-automation
+```
+
+## Requirements
+
+This server requires the `agent-browser` CLI binary 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.17`.
+
+### Installing agent-browser
+
+```bash
+npm install -g agent-browser
+```
+
+Or let the npx fallback handle it automatically (slower on first use due to download).
+
+## Configuration
+
+No API keys or credentials are required. The server communicates with the browser via the agent-browser CLI.
+
+| Variable | Required | Description |
+|---|---|---|
+| `AGENT_BROWSER_SESSION_NAME` | No | Session name for browser persistence (default: `mcp`) |
+| `BROWSER_AUTOMATION_ALLOW_EVAL` | No | Set to `1` to register the `browser_evaluate` tool. Off by default. See [Security considerations](#security-considerations). |
+
+### MCP Host Configuration
+
+```json
+{
+  "mcpServers": {
+    "browser-automation": {
+      "command": "npx",
+      "args": ["-y", "@mindstone/mcp-server-browser-automation"]
+    }
+  }
+}
+```
+
+## Available Tools (17 by default; +1 when `BROWSER_AUTOMATION_ALLOW_EVAL=1`)
+
+### Navigation
+- **browser_navigate** — Navigate to a URL
+- **browser_back** — Navigate back in browser history
+- **browser_forward** — Navigate forward in browser history
+- **browser_wait** — Wait for an element to appear or a specified time
+
+### Observation
+- **browser_snapshot** — Get the page accessibility tree with interactive element references
+- **browser_screenshot** — Take a screenshot of the current page
+- **browser_get_page_info** — Get the current page URL and title
+
+### Interaction
+- **browser_click** — Click an element using @ref or CSS selector
+- **browser_fill** — Clear a field and fill it with text
+- **browser_type** — Type text character by character (real keystrokes)
+- **browser_press_key** — Press a keyboard key
+- **browser_scroll** — Scroll the page in a direction
+- **browser_select** — Select an option from a dropdown
+- **browser_hover** — Hover over an element
+- **browser_evaluate** — Execute JavaScript in the page context (gated; see [Security considerations](#security-considerations))
+
+### Session Management
+- **browser_tabs** — List open tabs or switch to a tab
+- **browser_close** — Close the browser session
+- **browser_authenticate** — Open a visible browser for manual login
+
+## Workflow
+
+The typical workflow uses accessibility snapshots for reliable element targeting:
+
+1. `browser_navigate` → open a page
+2. `browser_snapshot` → see interactive elements with @ref IDs
+3. `browser_click` / `browser_fill` → interact using @ref references
+4. `browser_screenshot` → visual verification
+
+## Security considerations
+
+Browser automation has a large attack surface: the agent-browser CLI controls a real headless browser that loads URLs you pass it, runs page-side JavaScript, and persists cookies and session state across runs. Read this section before deploying.
+
+### `browser_evaluate` is gated behind `BROWSER_AUTOMATION_ALLOW_EVAL`
+
+`browser_evaluate` lets the model execute arbitrary JavaScript inside the page context — the security equivalent of giving the model a shell on whatever site it has just navigated to. To prevent prompt-injected content from doing this silently, the tool is **only registered when the host explicitly opts in**:
+
+```bash
+BROWSER_AUTOMATION_ALLOW_EVAL=1 mcp-server-browser-automation
+```
+
+Without this env var, `browser_evaluate` is **not** in the tools list at all — the LLM cannot even see it. When enabled, the tool is annotated `destructiveHint: true` so MCP hosts can (and should) require explicit user confirmation before each invocation.
+
+### URL scheme deny-list
+
+`browser_navigate` and `browser_authenticate` accept only `http:` and `https:` URLs (plus the special `about:blank`). Other URL schemes are refused before the underlying `agent-browser` CLI is invoked:
+
+- `file:` — would let pages read local filesystem paths
+- `chrome:` and `chrome-extension:` — internal browser pages and installed extensions
+- `javascript:` — equivalent to `eval()` against the current document
+- `data:` — inlined attacker-controlled HTML/JS payloads
+- `view-source:` — defeats the same-origin policy on rendered content
+- `about:` — privileged internal pages (`about:config`, `about:cache`, `about:debugging`, …); only `about:blank` is permitted
+
+### Cookie and session persistence
+
+The connector tells `agent-browser` to use a **named, persistent session** via `AGENT_BROWSER_SESSION_NAME` (default value: `mcp`). All cookies, `localStorage` data, and any logins performed via `browser_authenticate` are stored on disk under that session name and reused across runs. Anyone who can read the session storage — the local user, other tools running as the same user, or backups — can also use those logged-in sessions.
+
+To override the session name (for example, to keep separate profiles per project) set `AGENT_BROWSER_SESSION_NAME` explicitly in the host's MCP server config. To wipe state, close the browser via `browser_close` and remove the session directory managed by `agent-browser`.
+
+### Recommended deployment posture
+
+- **Run the connector against a separate browser profile** — a dedicated `AGENT_BROWSER_SESSION_NAME` per MCP host. Do not reuse your daily browser profile: the connector reads and overwrites cookies in whichever profile it is pointed at, and a malicious page can ride the existing session of any site you are logged into.
+- **Leave `browser_evaluate` disabled** unless the host implements user confirmation for every call. The default (off) is the safe choice.
+- **Require host confirmation** for `browser_authenticate` and any flow that may navigate to authenticated sites — otherwise prompt injection in fetched content can drive the browser at sites the user is logged into.
+- **Treat returned page content as untrusted** — accessibility snapshots, screenshots, and JavaScript-evaluation outputs come from arbitrary websites and may contain prompt-injection attempts.
+
+## License
+
+FSL-1.1-MIT

package/dist/browser-client.d.ts

@@ -0,0 +1,33 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+}
+export interface ExecOptions {
+    timeoutMs?: number;
+    headed?: boolean;
+}
+/**
+ * Execute an agent-browser CLI command.
+ *
+ * Argument shape: `agent-browser <command> [args] [options]`. The CLI parses
+ * the FIRST positional as the command, so flags like `--headed` MUST come
+ * AFTER the command — putting them first makes the CLI report
+ * "Unknown command: --headed" and exit 1.
+ *
+ * Visibility default is HEADED — users see the browser window so they can
+ * watch what the agent is doing (the trust-by-transparency choice). Hosts
+ * that want quiet operation set `AGENT_BROWSER_SHOW_WINDOW=false`. Callers
+ * can override per-call with `options.headed`. There is no `--headless` flag
+ * 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.
+ */
+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

@@ -0,0 +1,138 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { ConnectorError, DEFAULT_TIMEOUT_MS, SESSION_NAME } from './types.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;
+}
+function buildEnv() {
+    const env = { ...process.env };
+    // Always use session persistence
+    if (!env.AGENT_BROWSER_SESSION_NAME) {
+        env.AGENT_BROWSER_SESSION_NAME = SESSION_NAME;
+    }
+    return env;
+}
+/**
+ * Resolve whether the browser window should be visible for this invocation.
+ *
+ * Resolution order (highest precedence first):
+ *   1. Explicit `options.headed` from the caller (true → headed, false → headless).
+ *      Used by `browser_authenticate` and any future caller that wants to
+ *      override the user's preference for a specific operation.
+ *   2. The `AGENT_BROWSER_SHOW_WINDOW` env var, set by the host application
+ *      from the user's connector setupField:
+ *        - 'false' / '0' → headless (work out of sight)
+ *        - 'true' / '1' / unset → headed (visible window)
+ *
+ * The visible default is deliberate: showing the browser builds user trust by
+ * letting them watch what the agent is doing. Hosts (or power users) who
+ * prefer the quieter behaviour can opt out by setting the env var to 'false'.
+ */
+function resolveHeaded(optionHeaded, env) {
+    if (optionHeaded !== undefined)
+        return optionHeaded;
+    const raw = env.AGENT_BROWSER_SHOW_WINDOW?.trim().toLowerCase();
+    if (raw === 'false' || raw === '0')
+        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.
+ */
+const NPX_FALLBACK_VERSION = '0.26.0';
+/**
+ * Execute an agent-browser CLI command.
+ *
+ * Argument shape: `agent-browser <command> [args] [options]`. The CLI parses
+ * the FIRST positional as the command, so flags like `--headed` MUST come
+ * AFTER the command — putting them first makes the CLI report
+ * "Unknown command: --headed" and exit 1.
+ *
+ * Visibility default is HEADED — users see the browser window so they can
+ * watch what the agent is doing (the trust-by-transparency choice). Hosts
+ * that want quiet operation set `AGENT_BROWSER_SHOW_WINDOW=false`. Callers
+ * can override per-call with `options.headed`. There is no `--headless` flag
+ * 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.
+ */
+export async function execAgentBrowser(args, options) {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const env = buildEnv();
+    // Inject --headed AFTER the command (positional index 1). The CLI parses
+    // the first positional as the command name, so flags must follow it.
+    // Headless is the absence of --headed; the CLI has no --headless flag.
+    if (resolveHeaded(options?.headed, env) && args.length > 0) {
+        args = [args[0], '--headed', ...args.slice(1)];
+    }
+    const binary = resolveAgentBrowser();
+    try {
+        // execFile is safe against command injection (no shell interpretation)
+        const result = await execFileAsync(binary, args, {
+            env,
+            timeout: timeoutMs,
+            maxBuffer: 10 * 1024 * 1024, // 10MB for large snapshots
+        });
+        return { stdout: result.stdout, stderr: result.stderr ?? '' };
+    }
+    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 actual stderr for diagnosis.
+                const npxStderr = npxErr.stderr?.trim() ?? '';
+                const npxStdout = npxErr.stdout?.trim() ?? '';
+                throw new ConnectorError(npxStderr || npxStdout || npxErr.message || String(npxError), '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');
+            }
+        }
+        // Timeout
+        if (err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' || err.killed) {
+            throw new ConnectorError(`Command timed out after ${timeoutMs}ms: agent-browser ${args.join(' ')}`, 'TIMEOUT', 'The browser operation took too long. Try a simpler action or increase the timeout.');
+        }
+        // Other errors — include stderr for diagnostics
+        const stderr = err.stderr?.trim() ?? '';
+        const stdout = err.stdout?.trim() ?? '';
+        throw new ConnectorError(stderr || stdout || err.message || String(error), 'CLI_ERROR', 'The agent-browser CLI command failed. Check that agent-browser is installed and the browser session is active.');
+    }
+}
+/**
+ * Reset the resolved binary cache.
+ * Primarily used for testing to reset state between test runs.
+ */
+export function resetBinaryCache() {
+    resolvedBinary = null;
+}
+//# sourceMappingURL=browser-client.js.map

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Browser Automation MCP Server
+ *
+ * Provides headless browser automation via the agent-browser CLI.
+ * Uses accessibility snapshots (@ref pointers) instead of fragile CSS selectors.
+ * Sessions persist automatically between invocations.
+ *
+ * Requirements:
+ * - agent-browser CLI binary on PATH, or npx available for fallback
+ *
+ * Environment variables:
+ * - AGENT_BROWSER_SESSION_NAME: Session name for persistence (default: "mcp")
+ * - MCP_DISABLE_GRACEFUL_FS=1: Disable the graceful-fs EMFILE mitigation patch
+ */
+import './installGracefulFs.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Browser Automation MCP Server
+ *
+ * Provides headless browser automation via the agent-browser CLI.
+ * Uses accessibility snapshots (@ref pointers) instead of fragile CSS selectors.
+ * Sessions persist automatically between invocations.
+ *
+ * Requirements:
+ * - agent-browser CLI binary on PATH, or npx available for fallback
+ *
+ * Environment variables:
+ * - AGENT_BROWSER_SESSION_NAME: Session name for persistence (default: "mcp")
+ * - MCP_DISABLE_GRACEFUL_FS=1: Disable the graceful-fs EMFILE mitigation patch
+ */
+// MUST be the very first import — installs the graceful-fs EMFILE mitigation
+// before any other module touches node:fs.
+import './installGracefulFs.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Browser Automation MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/installGracefulFs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Boot-time graceful-fs install (leaf module).
+ *
+ * The browser-automation MCP server runs as a Node child process spawned by
+ * its host (e.g. via `npx`). It has its own `fs` surface and needs its own
+ * `graceful-fs.gracefulify(fs)` call to mitigate EMFILE / ENFILE bursts —
+ * notably on Windows where the default file descriptor / handle ceiling is
+ * tight and long-running browser-automation sessions can exhaust it.
+ *
+ * Imported as the very first statement of `index.ts` so the patch is
+ * installed before any other module touches `node:fs`.
+ *
+ * Kill switch: set `MCP_DISABLE_GRACEFUL_FS=1` to disable the patch.
+ *
+ * Failure handling: stash on `globalThis.__MCP_BOOTSTRAP_ERROR__` so future
+ * observability hooks can surface it. With `MCP_DEBUG_BOOTSTRAP=1` the
+ * failure also logs to stderr.
+ */
+export {};
+//# sourceMappingURL=installGracefulFs.d.ts.map

package/dist/installGracefulFs.js

@@ -0,0 +1,45 @@
+/**
+ * Boot-time graceful-fs install (leaf module).
+ *
+ * The browser-automation MCP server runs as a Node child process spawned by
+ * its host (e.g. via `npx`). It has its own `fs` surface and needs its own
+ * `graceful-fs.gracefulify(fs)` call to mitigate EMFILE / ENFILE bursts —
+ * notably on Windows where the default file descriptor / handle ceiling is
+ * tight and long-running browser-automation sessions can exhaust it.
+ *
+ * Imported as the very first statement of `index.ts` so the patch is
+ * installed before any other module touches `node:fs`.
+ *
+ * Kill switch: set `MCP_DISABLE_GRACEFUL_FS=1` to disable the patch.
+ *
+ * Failure handling: stash on `globalThis.__MCP_BOOTSTRAP_ERROR__` so future
+ * observability hooks can surface it. With `MCP_DEBUG_BOOTSTRAP=1` the
+ * failure also logs to stderr.
+ */
+import { createRequire } from 'node:module';
+if (process.env.MCP_DISABLE_GRACEFUL_FS !== '1') {
+    try {
+        // CommonJS interop — graceful-fs is a CJS package.
+        const requireFn = createRequire(import.meta.url);
+        const gracefulFs = requireFn('graceful-fs');
+        const fs = requireFn('node:fs');
+        gracefulFs.gracefulify(fs); // idempotent
+    }
+    catch (e) {
+        const g = globalThis;
+        g.__MCP_BOOTSTRAP_ERROR__ = {
+            kind: 'graceful_fs_leaf_install_failed',
+            error: {
+                name: e?.name,
+                message: e?.message,
+                stack: e?.stack,
+            },
+            at: Date.now(),
+        };
+        if (process.env.MCP_DEBUG_BOOTSTRAP === '1') {
+            // eslint-disable-next-line no-console
+            console.warn('[installGracefulFs] failed:', e);
+        }
+    }
+}
+//# sourceMappingURL=installGracefulFs.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,15 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SERVER_NAME, SERVER_VERSION } from './types.js';
+import { registerNavigationTools, registerInteractionTools, registerObservationTools, registerSessionTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    registerNavigationTools(server);
+    registerInteractionTools(server);
+    registerObservationTools(server);
+    registerSessionTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,5 @@
+export { registerNavigationTools } from './navigation.js';
+export { registerInteractionTools } from './interaction.js';
+export { registerObservationTools } from './observation.js';
+export { registerSessionTools } from './session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,5 @@
+export { registerNavigationTools } from './navigation.js';
+export { registerInteractionTools } from './interaction.js';
+export { registerObservationTools } from './observation.js';
+export { registerSessionTools } from './session.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/interaction.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerInteractionTools(server: McpServer): void;
+//# sourceMappingURL=interaction.d.ts.map

package/dist/tools/interaction.js

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+import { execAgentBrowser } from '../browser-client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerInteractionTools(server) {
+    server.registerTool('browser_click', {
+        description: `Click an element. Use @ref from browser_snapshot (preferred) or a CSS selector.
+
+WORKFLOW: browser_snapshot → find @ref → browser_click @ref`,
+        inputSchema: {
+            ref: z.string().describe('Element ref from snapshot (e.g., "@e2") or CSS selector'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        await execAgentBrowser(['click', args.ref]);
+        return JSON.stringify({ ok: true, message: `Clicked: ${args.ref}` });
+    }));
+    server.registerTool('browser_fill', {
+        description: `Clear a field and fill it with text. Use @ref from browser_snapshot.
+
+WORKFLOW: browser_snapshot → find input @ref → browser_fill`,
+        inputSchema: {
+            ref: z.string().describe('Element ref (e.g., "@e3") or CSS selector'),
+            value: z.string().describe('Text to fill'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        await execAgentBrowser(['fill', args.ref, args.value]);
+        return JSON.stringify({ ok: true, message: `Filled ${args.ref} with ${args.value.length} characters` });
+    }));
+    server.registerTool('browser_type', {
+        description: 'Type text character by character (simulates real keystrokes). Useful for search boxes and autocompletes that respond to individual key events.',
+        inputSchema: {
+            ref: z.string().describe('Element ref or CSS selector'),
+            text: z.string().describe('Text to type'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        await execAgentBrowser(['type', args.ref, args.text]);
+        return JSON.stringify({ ok: true, message: `Typed ${args.text.length} characters into ${args.ref}` });
+    }));
+    server.registerTool('browser_press_key', {
+        description: 'Press a keyboard key. Common keys: Enter, Tab, Escape, Backspace, ArrowDown, ArrowUp.',
+        inputSchema: {
+            key: z.string().describe('Key to press (e.g., "Enter", "Tab", "Escape")'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        await execAgentBrowser(['press', args.key]);
+        return JSON.stringify({ ok: true, message: `Pressed key: ${args.key}` });
+    }));
+    server.registerTool('browser_scroll', {
+        description: 'Scroll the page in a direction.',
+        inputSchema: {
+            direction: z.enum(['up', 'down', 'left', 'right']).describe('Scroll direction'),
+            amount: z.number().optional().default(500).describe('Pixels to scroll (default: 500)'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        const px = args.amount ?? 500;
+        await execAgentBrowser(['scroll', args.direction, String(px)]);
+        return JSON.stringify({ ok: true, message: `Scrolled ${args.direction} ${px}px` });
+    }));
+    server.registerTool('browser_select', {
+        description: 'Select an option from a dropdown.',
+        inputSchema: {
+            ref: z.string().describe('Element ref or CSS selector for the <select>'),
+            value: z.string().describe('Option value or visible text to select'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        await execAgentBrowser(['select', args.ref, args.value]);
+        return JSON.stringify({ ok: true, message: `Selected "${args.value}" in ${args.ref}` });
+    }));
+    server.registerTool('browser_hover', {
+        description: 'Hover over an element (triggers hover menus/tooltips).',
+        inputSchema: {
+            ref: z.string().describe('Element ref or CSS selector'),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        await execAgentBrowser(['hover', args.ref]);
+        return JSON.stringify({ ok: true, message: `Hovering over ${args.ref}` });
+    }));
+    // M3.12 — `browser_evaluate` lets the model run arbitrary JavaScript inside
+    // the page context, which is the security equivalent of giving it a shell
+    // on whatever site it has just navigated to. To prevent prompt-injected
+    // content from doing this silently, the tool is registered ONLY when the
+    // host explicitly opts in via `BROWSER_AUTOMATION_ALLOW_EVAL=1`. Without
+    // that env var the tool is not in the tools list at all (the LLM cannot
+    // even see it). When enabled it carries `destructiveHint: true` so MCP
+    // hosts can require explicit user confirmation before each invocation.
+    if (process.env.BROWSER_AUTOMATION_ALLOW_EVAL === '1') {
+        server.registerTool('browser_evaluate', // eslint-disable-line @typescript-eslint/quotes
+        {
+            description: 'Execute JavaScript in the page context and return the result. ' +
+                'DESTRUCTIVE: this is equivalent to running arbitrary code with the privileges of the current page; ' +
+                'hosts SHOULD require user confirmation before each call. ' +
+                'Only registered when BROWSER_AUTOMATION_ALLOW_EVAL=1 is set.',
+            inputSchema: {
+                script: z.string().describe('JavaScript code to execute'),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        }, withErrorHandling(async (args) => {
+            const result = await execAgentBrowser(['eval', args.script]);
+            return JSON.stringify({ ok: true, result: result.stdout.trim() });
+        }));
+    }
+}
+//# sourceMappingURL=interaction.js.map

package/dist/tools/navigation.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerNavigationTools(server: McpServer): void;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/tools/navigation.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { execAgentBrowser } from '../browser-client.js';
+import { validateUrlScheme, withErrorHandling } from '../utils.js';
+// URL scheme deny-list (validated by `validateUrlScheme` in utils.ts):
+// only http: and https: are permitted; about:blank is special-cased.
+// Refused: file:, chrome:, chrome-extension:, javascript:, data:,
+// view-source:, and about: URLs other than about:blank.
+export function registerNavigationTools(server) {
+    server.registerTool('browser_navigate', {
+        description: `Navigate to a URL. Opens the browser if not already running.
+
+Only http: and https: URLs are accepted (plus the special about:blank). Other URL schemes (file:, chrome:, chrome-extension:, javascript:, data:, view-source:, about:*) are refused.
+
+IMPORTANT: After navigating, call browser_snapshot to see the page content before interacting.`,
+        inputSchema: {
+            url: z.string().describe('URL to navigate to (http://, https://, or about:blank)'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        validateUrlScheme(args.url);
+        await execAgentBrowser(['open', args.url]);
+        const titleResult = await execAgentBrowser(['get', 'title']).catch(() => ({ stdout: '', stderr: '' }));
+        return JSON.stringify({
+            ok: true,
+            message: `Navigated to ${args.url}`,
+            title: titleResult.stdout.trim(),
+            hint: 'Call browser_snapshot to see page elements before interacting.',
+        });
+    }));
+    server.registerTool('browser_back', {
+        description: 'Navigate back in browser history.',
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async () => {
+        await execAgentBrowser(['back']);
+        return JSON.stringify({ ok: true, message: 'Navigated back' });
+    }));
+    server.registerTool('browser_forward', {
+        description: 'Navigate forward in browser history.',
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async () => {
+        await execAgentBrowser(['forward']);
+        return JSON.stringify({ ok: true, message: 'Navigated forward' });
+    }));
+    server.registerTool('browser_wait', {
+        description: 'Wait for an element to appear or for a specified time.',
+        inputSchema: {
+            selector: z.string().describe('CSS selector to wait for, or milliseconds (e.g., "2000")'),
+            timeout: z.number().optional().default(10000).describe('Max wait time in ms (default: 10000)'),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        const timeoutMs = args.timeout ?? 10_000;
+        await execAgentBrowser(['wait', args.selector], { timeoutMs: timeoutMs + 2000 });
+        return JSON.stringify({ ok: true, message: `Wait completed for: ${args.selector}` });
+    }));
+}
+//# sourceMappingURL=navigation.js.map

package/dist/tools/observation.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerObservationTools(server: McpServer): void;
+//# sourceMappingURL=observation.d.ts.map

package/dist/tools/observation.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { execAgentBrowser } from '../browser-client.js';
+import { withErrorHandling, withErrorHandlingRaw } from '../utils.js';
+import { SNAPSHOT_TIMEOUT_MS, SCREENSHOT_TIMEOUT_MS } from '../types.js';
+export function registerObservationTools(server) {
+    server.registerTool('browser_snapshot', {
+        description: `Get the page accessibility tree with interactive element references.
+
+THIS IS YOUR PRIMARY DISCOVERY TOOL. Always call this before clicking, filling, or interacting with the page.
+
+Returns element refs like @e1, @e2 that you use with browser_click, browser_fill, etc.
+Use the -i flag (default) to see only interactive elements, keeping output focused.`,
+        inputSchema: {
+            full: z.boolean().optional().default(false).describe('If true, show all elements (not just interactive). Default: false.'),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        const cliArgs = args.full ? ['snapshot'] : ['snapshot', '-i'];
+        const result = await execAgentBrowser(cliArgs, { timeoutMs: SNAPSHOT_TIMEOUT_MS });
+        return JSON.stringify({ ok: true, snapshot: result.stdout });
+    }));
+    server.registerTool('browser_screenshot', {
+        description: 'Take a screenshot of the current page. Returns an image.',
+        inputSchema: {
+            full_page: z.boolean().optional().default(false).describe('Capture full scrollable page'),
+            annotate: z.boolean().optional().default(false).describe('Add numbered element labels to the screenshot'),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, withErrorHandlingRaw(async (args) => {
+        const cliArgs = ['screenshot'];
+        if (args.full_page)
+            cliArgs.push('--full');
+        if (args.annotate)
+            cliArgs.push('--annotate');
+        cliArgs.push('-'); // output to stdout
+        const result = await execAgentBrowser(cliArgs, { timeoutMs: SCREENSHOT_TIMEOUT_MS });
+        const data = result.stdout.trim();
+        // agent-browser outputs base64 PNG when piped to stdout
+        if (data.length > 100) {
+            return {
+                content: [{
+                        type: 'image',
+                        data,
+                        mimeType: 'image/png',
+                    }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ ok: true, message: 'Screenshot taken', note: data }) }],
+        };
+    }));
+    server.registerTool('browser_get_page_info', {
+        description: 'Get the current page URL and title.',
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async () => {
+        const urlResult = await execAgentBrowser(['get', 'url']);
+        const titleResult = await execAgentBrowser(['get', 'title']);
+        return JSON.stringify({
+            ok: true,
+            url: urlResult.stdout.trim(),
+            title: titleResult.stdout.trim(),
+        });
+    }));
+}
+//# sourceMappingURL=observation.js.map

package/dist/tools/session.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSessionTools(server: McpServer): void;
+//# sourceMappingURL=session.d.ts.map

package/dist/tools/session.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { execAgentBrowser } from '../browser-client.js';
+import { validateUrlScheme, withErrorHandling } from '../utils.js';
+// URL scheme deny-list applied to browser_authenticate (validated by
+// `validateUrlScheme` in utils.ts): only http: and https: URLs are
+// permitted; about:blank is special-cased. Refused: file:, chrome:,
+// chrome-extension:, javascript:, data:, view-source:, and about: URLs
+// other than about:blank.
+export function registerSessionTools(server) {
+    server.registerTool('browser_tabs', {
+        description: 'List open tabs or switch to a tab by number.',
+        inputSchema: {
+            action: z.enum(['list', 'new', 'close']).optional().describe('Tab action. Omit to list tabs.'),
+            tab_number: z.number().optional().describe('Tab number to switch to (from tab list)'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        if (args.tab_number !== undefined) {
+            await execAgentBrowser(['tab', String(args.tab_number)]);
+            return JSON.stringify({ ok: true, message: `Switched to tab ${args.tab_number}` });
+        }
+        const cliAction = args.action ?? 'list';
+        const result = await execAgentBrowser(['tab', cliAction]);
+        return JSON.stringify({ ok: true, tabs: result.stdout.trim() });
+    }));
+    server.registerTool('browser_close', {
+        description: 'Close the browser session. Sessions are saved automatically.',
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, withErrorHandling(async () => {
+        await execAgentBrowser(['close']);
+        return JSON.stringify({ ok: true, message: 'Browser session closed. Sessions are saved automatically.' });
+    }));
+    server.registerTool('browser_authenticate', {
+        description: `Open a visible browser window so the user can log in manually. The session is saved automatically.
+
+WHEN TO USE: "I need to access LinkedIn", "Log me into WhatsApp", etc.
+Tell the user to close the browser when done logging in, or call browser_close.`,
+        inputSchema: {
+            url: z.string().describe('Website URL to open for login (http://, https://, or about:blank)'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        validateUrlScheme(args.url);
+        await execAgentBrowser(['open', args.url], { headed: true });
+        return JSON.stringify({
+            ok: true,
+            url: args.url,
+            message: `Browser opened to ${args.url} in visible mode. The user should log in manually. Their session will be saved automatically when the browser is closed.`,
+            next_step: 'Tell the user to log in and close the browser when done, or call browser_close.',
+        });
+    }));
+}
+//# sourceMappingURL=session.js.map

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+export declare const SERVER_NAME = "browser-automation-mcp-server";
+/** Server version reported on MCP `initialize`. Read from package.json so
+ *  it cannot drift from the published npm version. */
+export declare const SERVER_VERSION: string;
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const SNAPSHOT_TIMEOUT_MS = 15000;
+export declare const SCREENSHOT_TIMEOUT_MS = 15000;
+export declare const SESSION_NAME = "mcp";
+export declare class ConnectorError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,22 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const SERVER_NAME = 'browser-automation-mcp-server';
+/** Server version reported on MCP `initialize`. Read from package.json so
+ *  it cannot drift from the published npm version. */
+export const SERVER_VERSION = pkg.version;
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const SNAPSHOT_TIMEOUT_MS = 15_000;
+export const SCREENSHOT_TIMEOUT_MS = 15_000;
+export const SESSION_NAME = 'mcp';
+export class ConnectorError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'ConnectorError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,25 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Validate the URL scheme of a user-supplied URL before forwarding it to the
+ * agent-browser CLI. Throws a `ConnectorError` with a human-readable message
+ * (and a stable code suitable for tool error responses) when the scheme is
+ * not on the allow-list.
+ */
+export declare function validateUrlScheme(url: string): void;
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On ConnectorError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+/**
+ * Wraps a tool handler that returns a CallToolResult directly (e.g. for image responses).
+ */
+export declare function withErrorHandlingRaw<T>(fn: (args: T, extra: unknown) => Promise<CallToolResult>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,129 @@
+import { ConnectorError } from './types.js';
+/**
+ * URL scheme deny-list for browser_navigate / browser_authenticate.
+ *
+ * Only `http:` and `https:` are accepted. The pseudo-URL `about:blank` is
+ * special-cased and permitted (it's the only safe `about:` page — no local
+ * data, no chrome internals). All other schemes are refused before the
+ * underlying agent-browser CLI is invoked, so the agent cannot:
+ *   - read local files via `file:` URLs,
+ *   - access browser internals via `chrome:` / `chrome-extension:` URLs,
+ *   - execute page-side JavaScript via `javascript:` URLs,
+ *   - render attacker-controlled inline payloads via `data:` URLs,
+ *   - bypass the same-origin policy via `view-source:` URLs,
+ *   - touch privileged `about:` pages (about:config, about:cache, …).
+ */
+const BLOCKED_URL_SCHEMES = new Set([
+    'file:',
+    'chrome:',
+    'chrome-extension:',
+    'javascript:',
+    'data:',
+    'view-source:',
+]);
+/**
+ * Validate the URL scheme of a user-supplied URL before forwarding it to the
+ * agent-browser CLI. Throws a `ConnectorError` with a human-readable message
+ * (and a stable code suitable for tool error responses) when the scheme is
+ * not on the allow-list.
+ */
+export function validateUrlScheme(url) {
+    // Special case: `about:blank` is the only `about:` URL we accept. We match
+    // it textually to sidestep any quirks in URL parsing for opaque schemes.
+    if (url.toLowerCase() === 'about:blank')
+        return;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new ConnectorError(`URL scheme not allowed: invalid URL ${JSON.stringify(url)}`, 'URL_SCHEME_REJECTED', 'Pass a valid http: or https: URL (or about:blank). Only http and https schemes are permitted.');
+    }
+    const proto = parsed.protocol.toLowerCase();
+    if (proto === 'http:' || proto === 'https:')
+        return;
+    if (proto === 'about:') {
+        // We already returned above for about:blank — anything else here is
+        // about:config / about:cache / about:debugging etc.
+        throw new ConnectorError(`URL scheme not allowed: ${proto} (only about:blank is permitted, got ${url})`, 'URL_SCHEME_REJECTED', 'Only http://, https://, and about:blank URLs are accepted by the browser-automation connector.');
+    }
+    // Default-deny: explicit deny-list match OR unknown scheme — both rejected.
+    // The deny-list is enumerated for documentation; the protocol check above
+    // is what actually enforces the policy.
+    void BLOCKED_URL_SCHEMES; // referenced so the import survives tree-shaking
+    throw new ConnectorError(`URL scheme not allowed: ${proto}. Only http: and https: schemes are permitted (about:blank also allowed).`, 'URL_SCHEME_REJECTED', 'Pass an http://, https://, or about:blank URL. Schemes like file:, chrome:, chrome-extension:, javascript:, data:, view-source:, and about: (other than about:blank) are refused.');
+}
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On ConnectorError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof ConnectorError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+/**
+ * Wraps a tool handler that returns a CallToolResult directly (e.g. for image responses).
+ */
+export function withErrorHandlingRaw(fn) {
+    return async (args, extra) => {
+        try {
+            return await fn(args, extra);
+        }
+        catch (error) {
+            if (error instanceof ConnectorError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@mindstone/mcp-server-browser-automation",
+  "version": "0.1.7",
+  "mcpName": "io.github.mindstone/mcp-server-browser-automation",
+  "description": "Browser automation MCP server \u2014 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",
+  "type": "module",
+  "bin": {
+    "mcp-server-browser-automation": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mindstone/mcp-servers.git",
+    "directory": "connectors/browser-automation"
+  },
+  "homepage": "https://github.com/mindstone/mcp-servers/tree/main/connectors/browser-automation",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "graceful-fs": "^4.2.11",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "overrides": {
+    "fast-uri": "^3.1.2",
+    "hono": "^4.12.18",
+    "ip-address": "^10.2.0"
+  }
+}