browser-devtools-mcp 0.3.2 → 0.3.4

package/README.md

@@ -45,7 +45,7 @@ Choose the platform by running the appropriate MCP server or CLI:
 - **Browser Automation**: Navigation, input, clicking, scrolling, viewport control
 - **Execution Monitoring**: Console message capture, HTTP request/response tracking
 - **OpenTelemetry Integration**: Automatic trace injection into web pages, UI trace collection, and backend trace correlation via trace context propagation
-- **JavaScript Execution**: Execute code in browser page context or in Node.js VM sandbox on the server
+- **JavaScript Execution**: Use the **execute** tool to batch-execute tool calls and run custom JavaScript; on the browser platform the VM receives \`page\` (Playwright Page) so you can use \`page.evaluate()\` or the Playwright API
 - **Session Management**: Long-lived, session-based debugging with automatic cleanup
 - **Multiple Transport Modes**: Supports both stdio and HTTP transports
 
@@ -53,7 +53,6 @@ Choose the platform by running the appropriate MCP server or CLI:
 
 - **Connection**: Connect to Node.js processes by PID, process name, port, WebSocket URL, or Docker container
 - **Non-Blocking Debugging**: Tracepoints, logpoints, exceptionpoints without pausing execution
-- **JavaScript Execution**: Run arbitrary JavaScript in the connected Node process via `run_js-in-node` (CDP Runtime.evaluate)—use `return` to get output; async/await supported. Inspect `process.memoryUsage()`, call `require()` modules, read globals
 - **Source Map Support**: Resolves bundled/minified code to original source locations; `debug_resolve-source-location` translates stack traces and bundle locations to original source
 - **OpenTelemetry Integration**: When the Node process uses `@opentelemetry/api`, tracepoint/logpoint snapshots automatically include `traceContext` (traceId, spanId) for correlating backend traces with browser traces
 - **Docker Support**: Connect to Node.js processes running inside Docker containers (`containerId` / `containerName`)
@@ -77,18 +76,16 @@ Choose the platform by running the appropriate MCP server or CLI:
 - **Resize Window**: Resize the real browser window (OS-level) using Chrome DevTools Protocol
 
 ### Navigation Tools
-- **Go To**: Navigate to URLs with configurable wait strategies. By default (`includeSnapshot: true`) returns an ARIA snapshot with refs (`output`, `refs`); set `includeSnapshot: false` for url/status/ok only. Use `snapshotInteractiveOnly` and `snapshotCursorInteractive` to control which elements get refs (same as `a11y_take-aria-snapshot`).
-- **Go Back**: Navigate backward in history. Same snapshot/refs behavior as Go To when `includeSnapshot` is true.
-- **Go Forward**: Navigate forward in history. Same snapshot/refs behavior as Go To when `includeSnapshot` is true.
-- **Reload**: Reload the current page. Same snapshot/refs behavior as Go To when `includeSnapshot` is true.
+- **Go To**: Navigate to URLs with configurable wait strategies. By default **waitForNavigation** is `true`: after navigation completes, waits for network idle before taking snapshot/screenshot; set `waitForNavigation: false` to skip the network idle wait. **waitForTimeoutMs** (default 30000) is the timeout for that wait when `waitForNavigation` is true. By default (`includeSnapshot: true`) returns an ARIA snapshot with refs (`output`, `refs`); set `includeSnapshot: false` for url/status/ok only. Use **snapshotOptions** (e.g. `interactiveOnly`, `cursorInteractive`) to control which elements get refs (same as `a11y_take-aria-snapshot`). Optional **includeScreenshot** saves a screenshot to disk and returns `screenshotFilePath`; use **screenshotOptions** (outputPath, name, fullPage, type, annotate, includeBase64) — defaults: OS temp dir, name "screenshot"; set `includeBase64: true` only when the file cannot be read from the path (e.g. remote, container).
+- **Go Back / Go Forward**: Navigate backward or forward in history. Same **waitForNavigation** (default true), **waitForTimeoutMs**, snapshot/refs and optional screenshot behavior as Go To.
+- **Reload**: Reload the current page. Same **waitForNavigation** (default true), **waitForTimeoutMs**, snapshot/refs and optional screenshot behavior as Go To.
 
 ### Run Tools
-- **JS in Browser**: Execute JavaScript code inside the active browser page (page context with access to window, document, DOM, and Web APIs)
-- **JS in Sandbox**: Execute JavaScript code in a Node.js VM sandbox on the MCP server (with access to Playwright Page, console logging, and safe built-ins)
+- **Execute**: Batch-execute multiple tool calls in a single request via custom JavaScript. Use `callTool(name, input, returnOutput?)` to invoke any registered tool. Reduces round-trips and token usage. Includes wall-clock timeout, max tool call limit (50), console log capture, and fail-fast error handling with `failedTool` diagnostics. On the **browser** platform the VM also receives the session execution context: `page` (Playwright Page) is available — use the Playwright API (e.g. `page.locator()`, `page.goto()`) or `page.evaluate()` to run script in the browser. On the **Node** platform no extra bindings are injected. **Also available via CLI**: use the subcommand `run execute` or call the daemon HTTP API (POST `/call`) with `toolName: "execute"`.
 
 ### Observability (O11Y) Tools
 - **Console Messages**: Capture and filter browser console logs with advanced filtering (level, search, timestamp, sequence number)
-- **HTTP Requests**: Monitor network traffic with detailed request/response data, filtering by resource type, status code, and more
+- **HTTP Requests**: Monitor network traffic with filtering by resource type, status code, and more. Request headers, response headers, and response body are opt-in (`includeRequestHeaders`, `includeResponseHeaders`, `includeResponseBody`; default off). Response body is not stored for static assets (e.g. .js, .css, .map)
 - **Web Vitals**: Collect Core Web Vitals (LCP, INP, CLS) and supporting metrics (TTFB, FCP) with ratings and recommendations based on Google's thresholds
 - **OpenTelemetry Tracing**: Automatic trace injection into web pages, UI trace collection (document load, fetch, XMLHttpRequest, user interactions), and trace context propagation for backend correlation
 - **Trace ID Management**: Get, set, and generate OpenTelemetry compatible trace IDs for distributed tracing across API calls
@@ -147,6 +144,7 @@ Non-blocking debugging tools that capture snapshots without pausing execution. I
 - Configurable limits (max snapshots, call stack depth, async segments)
 - Sequence numbers for efficient snapshot polling
 - OpenTelemetry trace context in Node snapshots (traceId, spanId when process uses @opentelemetry/api)
+- **Snapshot capture**: 1 call stack frame with scopes (both platforms) to keep payloads small. **Output trimming** for `get-probe-snapshots`: default scopes = `local` only (both Browser and Node), 20 variables/scope. Override via `maxCallStackDepth`, `includeScopes`, `maxVariablesPerScope`.
 
 ## Prerequisites
 
@@ -160,6 +158,39 @@ like VS Code, Claude, Cursor, Windsurf, GitHub Copilot via the `browser-devtools
 
 No manual installation required! The server can be run directly using `npx`, which automatically downloads and runs the package.
 
+---
+
+### 📦 Playwright browser binaries (required for browser platform)
+
+> **The browser platform needs Playwright browser binaries (e.g. Chromium) to control the browser.**  
+> If you use **npx** to run the server, browsers are not downloaded at install time — you must install them once (see below). With a normal `npm install`, Playwright’s own packages may install Chromium automatically.
+
+| Goal | What to do |
+|------|------------|
+| **Install at first run (npx)** | Set env before running: `BROWSER_DEVTOOLS_INSTALL_CHROMIUM=true npx -y browser-devtools-mcp` |
+| **Install manually anytime** | Run: `npx playwright install chromium` (or `firefox`, `webkit`) |
+| **Skip download (CI / system browser)** | Set: `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` |
+
+**1. Opt-in at install time** — set env vars before `npm install` or `npx` so the postinstall script downloads the chosen browsers:
+   - **Chromium** (chromium + chromium-headless-shell + ffmpeg):
+     ```bash
+     BROWSER_DEVTOOLS_INSTALL_CHROMIUM=true npx -y browser-devtools-mcp
+     ```
+   - **Firefox:** `BROWSER_DEVTOOLS_INSTALL_FIREFOX=true`
+   - **WebKit:** `BROWSER_DEVTOOLS_INSTALL_WEBKIT=true`
+   Combine as needed, e.g. `BROWSER_DEVTOOLS_INSTALL_CHROMIUM=true BROWSER_DEVTOOLS_INSTALL_FIREFOX=true npx -y browser-devtools-mcp`.
+
+**2. Install via Playwright CLI** (same global cache):
+   ```bash
+   npx playwright install chromium   # or firefox, webkit
+   ```
+   On Linux, include system dependencies:
+   ```bash
+   npx playwright install --with-deps chromium
+   ```
+
+---
+
 ### CLI Arguments
 
 Browser DevTools MCP server supports the following CLI arguments for configuration:
@@ -201,6 +232,9 @@ Add the following configuration into the `claude_desktop_config.json` file.
 See the [Claude Desktop MCP docs](https://modelcontextprotocol.io/docs/develop/connect-local-servers) for more info.
 
 **Browser platform (default):**
+
+> **→ Browser platform requires Playwright browser binaries.** See [📦 Playwright browser binaries](#-playwright-browser-binaries-required-for-browser-platform) for one-time install (env vars or `npx playwright install chromium`).
+
 ```json
 {
   "mcpServers": {
@@ -242,6 +276,8 @@ Then, go to `Settings` > `Connectors` > `Add Custom Connector` in Claude Desktop
 Run the following command.
 See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.
 
+> **→ Browser platform requires Playwright browser binaries.** See [📦 Playwright browser binaries](#-playwright-browser-binaries-required-for-browser-platform) for one-time install (env vars or `npx playwright install chromium`).
+
 #### Local Server
 ```bash
 claude mcp add browser-devtools -- npx -y browser-devtools-mcp
@@ -268,6 +304,8 @@ Replace `<SERVER_URL>` with your server URL (e.g., `http://localhost:3000/mcp` i
 Add the following configuration into the `~/.cursor/mcp.json` file (or `.cursor/mcp.json` in your project folder).
 See the [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.
 
+> **→ Browser platform requires Playwright browser binaries.** See [📦 Playwright browser binaries](#-playwright-browser-binaries-required-for-browser-platform) for one-time install (env vars or `npx playwright install chromium`).
+
 #### Local Server
 ```json
 {
@@ -307,6 +345,8 @@ Replace `<SERVER_URL>` with your server URL (e.g., `http://localhost:3000/mcp` i
 Add the following configuration into the `.vscode/mcp.json` file.
 See the [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
 
+> **→ Browser platform requires Playwright browser binaries.** See [📦 Playwright browser binaries](#-playwright-browser-binaries-required-for-browser-platform) for one-time install (env vars or `npx playwright install chromium`).
+
 #### Local Server
 ```json
 {
@@ -352,6 +392,8 @@ Replace `<SERVER_URL>` with your server URL (e.g., `http://localhost:3000/mcp` i
 Add the following configuration into the `~/.codeium/windsurf/mcp_config.json` file. 
 See the [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more info.
 
+> **→ Browser platform requires Playwright browser binaries.** See [📦 Playwright browser binaries](#-playwright-browser-binaries-required-for-browser-platform) for one-time install (env vars or `npx playwright install chromium`).
+
 #### Local Server
 ```json
 {
@@ -392,6 +434,8 @@ Add the following configuration to the `mcpServers` section of your Copilot Codi
 `Repository` > `Settings` > `Copilot` > `Coding agent` > `MCP configuration`.
 See the [Copilot Coding Agent MCP docs](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp) for more info.
 
+> **→ Browser platform requires Playwright browser binaries.** See [📦 Playwright browser binaries](#-playwright-browser-binaries-required-for-browser-platform) for one-time install (env vars or `npx playwright install chromium`).
+
 #### Local Server
 ```json
 {
@@ -540,6 +584,8 @@ browser-devtools-cli --help
 node-devtools-cli --help
 ```
 
+To install Playwright browser binaries (required for the browser CLI when not using a system browser), run `npx playwright install chromium` (see [Playwright browser binaries](#playwright-browser-binaries)).
+
 ### Global Options
 
 | Option | Description | Default |
@@ -577,8 +623,6 @@ node-devtools-cli
 ├── completion                # Generate shell completion scripts
 ├── interactive (repl)        # Start interactive REPL mode
 ├── update                    # Check for updates
-├── run                       # Script execution commands
-│   └── js-in-node            # Run JavaScript in the connected Node process
 └── debug                     # Debug commands
     ├── connect               # Connect to Node.js process (pid, processName, inspectorPort, containerId, etc.)
     ├── disconnect            # Disconnect from current process
@@ -591,7 +635,7 @@ node-devtools-cli
 
 ### Browser CLI Commands
 
-`browser-devtools-cli` organizes tools into domain-based subcommands:
+`browser-devtools-cli` organizes tools into domain-based subcommands. **Object parameters** (e.g. `screenshotOptions`, `snapshotOptions`) must be passed as a JSON string: `--screenshot-options '{"outputPath":"/tmp","name":"myshot"}'` or `--snapshot-options '{"interactiveOnly":false}'`. Run `browser-devtools-cli navigation go-to --help` (or the relevant subcommand) to see all options.
 
 ```
 browser-devtools-cli
@@ -649,15 +693,14 @@ browser-devtools-cli
 │   ├── get-component-for-element
 │   └── get-element-for-component
 ├── run                       # Script execution commands
-│   ├── js-in-browser         # Run JS in browser
-│   └── js-in-sandbox         # Run JS in sandbox
+│   └── execute               # Batch-execute tool calls via JS (VM has page on browser)
 ├── stub                      # HTTP stubbing commands
 │   ├── mock-http-response    # Mock HTTP responses
 │   ├── intercept-http-request # Intercept requests
 │   ├── list                  # List stubs
 │   └── clear                 # Clear stubs
 ├── sync                      # Synchronization commands
-│   └── wait-for-network-idle # Wait for network idle
+│   └── wait-for-network-idle # Wait for network idle (configurable idle time / threshold)
 ├── debug                     # Non-blocking debugging commands
 │   ├── put-tracepoint        # Set a tracepoint (captures call stack)
 │   ├── remove-probe         # Remove a tracepoint, logpoint, or watch by ID (type + id)
@@ -666,7 +709,7 @@ browser-devtools-cli
 │   ├── put-exceptionpoint    # Enable exception catching
 │   ├── add-watch             # Add a watch expression
 │   ├── clear-probes          # Clear tracepoints, logpoints, and/or watches (optional types; omit to clear all)
-│   ├── get-probe-snapshots           # Get tracepoint/logpoint/exceptionpoint snapshots (optional types; response: tracepointSnapshots, logpointSnapshots, exceptionpointSnapshots)
+│   ├── get-probe-snapshots           # Get tracepoint/logpoint/exceptionpoint snapshots (1 frame captured; default scopes: local only; 20 vars/scope; override: maxCallStackDepth, includeScopes, maxVariablesPerScope)
 │   ├── clear-probe-snapshots         # Clear tracepoint/logpoint/exceptionpoint snapshots (optional types; omit to clear all)
 │   └── status                # Get debugging status
 └── figma                     # Figma integration commands
@@ -1072,6 +1115,7 @@ The CLI uses a daemon server architecture for efficient browser management:
 2. **Shared browser**: Multiple CLI invocations share the same browser instance
 3. **Session isolation**: Each session ID gets its own isolated browser context
 4. **Auto-cleanup**: Idle sessions are automatically cleaned up after inactivity
+5. **Full tool set**: The daemon exposes the same tools as MCP (including **execute** for batch execution). Tools can be invoked via CLI subcommands (e.g. `navigation go-to`, `run execute`) or via the daemon HTTP API (POST `/call` with `toolName` and `toolInput`).
 
 The daemon listens on port 2020 by default. Use `--port` to specify a different port.
 
@@ -1103,10 +1147,14 @@ The server can be configured using environment variables. Configuration is divid
 | `TOOL_OUTPUT_SCHEMA_DISABLE` | When true, omit tool output schema from MCP tool registration (can reduce token usage for some clients) | `false` |
 | `AVAILABLE_TOOL_DOMAINS` | Optional comma-separated list of tool domains to enable. When set, only tools from these domains are registered; unset means all tools. **Browser domains:** `a11y`, `content`, `debug`, `figma`, `interaction`, `navigation`, `o11y`, `react`, `run`, `stub`, `sync`. **Node domains:** `debug`, `run`. Example: `AVAILABLE_TOOL_DOMAINS=navigation,interaction,a11y` | (all tools) |
 
+Tool inputs are validated with a strict schema; unknown or misspelled argument keys (e.g. `port` instead of `inspectorPort`) cause a validation error.
+
 ### Node Platform Configuration
 
 | Variable | Description | Default |
 |----------|-------------|---------|
+| `NODE_SERVER_INSTRUCTIONS_ENABLE` | When true, include server instructions in MCP server info | `true` |
+| `NODE_POLICY_DEBUGGING_ENABLE` | When true, include NODE_DEBUGGING_POLICY in server policies | `false` |
 | `NODE_CONSOLE_MESSAGES_BUFFER_SIZE` | Maximum console messages to buffer from Node.js process | `1000` |
 | `NODE_INSPECTOR_HOST` | Inspector host for `debug_connect` when MCP runs in Docker (e.g. `host.docker.internal`). Use with host-mapped `inspectorPort` so the MCP connects to the right address. | `127.0.0.1` |
 | `PLATFORM` | Platform to use: `browser` or `node` | `browser` |
@@ -1115,6 +1163,8 @@ The server can be configured using environment variables. Configuration is divid
 
 | Variable | Description | Default |
 |----------|-------------|---------|
+| `BROWSER_SERVER_INSTRUCTIONS_ENABLE` | When true, include server instructions in MCP server info | `true` |
+| `BROWSER_POLICY_UI_DEBUGGING_ENABLE` | When true, include UI_DEBUGGING_POLICY in server policies | `false` |
 | `CONSOLE_MESSAGES_BUFFER_SIZE` | Maximum console messages to buffer | `1000` |
 | `HTTP_REQUESTS_BUFFER_SIZE` | Maximum HTTP requests to buffer | `1000` |
 | `BROWSER_HEADLESS_ENABLE` | Run browser in headless mode | `true` |
@@ -1290,11 +1340,13 @@ Once disabled, no data is sent and no network requests are made to PostHog.
 ### Interaction Tools
 
 <details>
-<summary><code>interaction_click</code> - Clicks an element on the page.</summary>
+<summary><code>interaction_click</code> - Clicks an element. Set waitForNavigation: true when click opens a new page.</summary>
 
 **Parameters:**
 - `selector` (string, required): Ref (e.g. `e1`, `@e1`, `ref=e1`), getByRole/getByLabel/getByText/getByPlaceholder/getByTitle/getByAltText/getByTestId expression, or CSS selector for the element to click
 - `timeoutMs` (number, optional): Time to wait for the element in ms (default: 10000)
+- `waitForNavigation` (boolean, optional): Wait for navigation triggered by click in parallel (race-free), then for network idle. Use when click opens a new page. Default: false
+- `waitForTimeoutMs` (number, optional): Timeout for navigation and network idle wait in ms. Only when waitForNavigation is true. Default: 30000
 </details>
 
 <details>
@@ -1430,24 +1482,24 @@ Once disabled, no data is sent and no network requests are made to PostHog.
 - `timeout` (number, optional): Maximum operation time in milliseconds (default: 0 - no timeout)
 - `waitUntil` (enum, optional): When to consider navigation succeeded - "load", "domcontentloaded", "networkidle", or "commit" (default: "load")
 - `includeSnapshot` (boolean, optional): When true (default), take an ARIA snapshot with refs after navigation and include `output` and `refs` in the response; when false, only url/status/ok are returned.
-- `snapshotInteractiveOnly` (boolean, optional): When includeSnapshot is true, if set, only interactive elements get refs (same as a11y_take-aria-snapshot).
-- `snapshotCursorInteractive` (boolean, optional): When includeSnapshot is true, if set, also include cursor-interactive elements in refs (same as a11y_take-aria-snapshot).
+- `snapshotOptions` (object, optional): When includeSnapshot is true, options for the snapshot. **interactiveOnly** (boolean, default false): only interactive elements get refs; **cursorInteractive** (boolean, default false): include cursor-interactive elements (same as a11y_take-aria-snapshot).
+- `includeScreenshot` (boolean, optional): When true, take a screenshot after navigation; saved to disk, path returned in `screenshotFilePath`. Default false.
+- `screenshotOptions` (object, optional): When includeScreenshot is true. **outputPath** (string, default: OS temp dir), **name** (string, default: "screenshot"), **fullPage** (boolean, default true), **type** ("png" | "jpeg", default "png"), **annotate** (boolean, default true), **includeBase64** (boolean, default false): include image in response as separate MCP content part — use only when file cannot be read from path (e.g. remote, container).
 
-**Returns:**
-- `url` (string): Final URL after navigation
-- `status` (number): HTTP status code
-- `statusText` (string): HTTP status text
-- `ok` (boolean): Whether navigation was successful (2xx status)
+**Returns:** (order: url, status, statusText, ok, screenshotFilePath, output, refs, image)
+- `url`, `status`, `statusText`, `ok`: Navigation result.
+- `screenshotFilePath` (string, optional): When includeScreenshot is true, full path of the saved screenshot file.
 - `output` (string, optional): When includeSnapshot is true, ARIA snapshot text (page URL, title, YAML tree).
 - `refs` (record, optional): When includeSnapshot is true, map of ref id (e1, e2, ...) to role/name/selector; use in interaction tools (e.g. click @e1).
+- `image` (object, optional): When includeScreenshot and screenshotOptions.includeBase64 are true, image data (data, mimeType) sent as separate image content part by MCP.
 </details>
 
 <details>
 <summary><code>navigation_go-back-or-forward</code> - Navigates back or forward in browser history.</summary>
 
-**Parameters:** `direction` (required: `"back"` or `"forward"`), `timeout`, `waitUntil`, `includeSnapshot` (default true), `snapshotInteractiveOnly`, `snapshotCursorInteractive` — same semantics as navigation_go-to for snapshot/refs.
+**Parameters:** `direction` (required: `"back"` or `"forward"`), `timeout`, `waitUntil`, `includeSnapshot` (default true), `snapshotOptions` (object: interactiveOnly, cursorInteractive), `includeScreenshot` (boolean, default false), `screenshotOptions` (object: outputPath, name, fullPage, type, annotate, includeBase64) — same semantics as navigation_go-to.
 
-**Returns:** `url`, `status`, `statusText`, `ok`; when includeSnapshot is true also `output` and `refs` (ARIA snapshot with refs).
+**Returns:** Same shape as navigation_go-to (url, status, statusText, ok, screenshotFilePath, output, refs, image).
 </details>
 
 <details>
@@ -1457,107 +1509,66 @@ Once disabled, no data is sent and no network requests are made to PostHog.
 - `timeout` (number, optional): Maximum operation time in milliseconds (default: 0 - no timeout)
 - `waitUntil` (enum, optional): When to consider navigation succeeded - "load", "domcontentloaded", "networkidle", or "commit" (default: "load")
 - `includeSnapshot` (boolean, optional): When true (default), take an ARIA snapshot with refs after reload and include `output` and `refs`; when false, only url/status/ok.
-- `snapshotInteractiveOnly` (boolean, optional): When includeSnapshot is true, control which elements get refs (same as a11y_take-aria-snapshot).
-- `snapshotCursorInteractive` (boolean, optional): When includeSnapshot is true, include cursor-interactive elements in refs (same as a11y_take-aria-snapshot).
+- `snapshotOptions` (object, optional): When includeSnapshot is true. **interactiveOnly** (boolean, default false), **cursorInteractive** (boolean, default false) — same as a11y_take-aria-snapshot.
+- `includeScreenshot` (boolean, optional): When true, take a screenshot after reload; saved to disk. Default false.
+- `screenshotOptions` (object, optional): When includeScreenshot is true; same shape as navigation_go-to (outputPath, name, fullPage, type, annotate, includeBase64).
 
-**Returns:**
-- `url` (string): Final URL after reload
-- `status` (number): HTTP status code
-- `statusText` (string): HTTP status text
-- `ok` (boolean): Whether reload was successful (2xx status)
-- `output` (string, optional): When includeSnapshot is true, ARIA snapshot text.
-- `refs` (record, optional): When includeSnapshot is true, map of ref id to role/name/selector for use in interaction tools.
+**Returns:** Same shape as navigation_go-to (url, status, statusText, ok, screenshotFilePath, output, refs, image).
 </details>
 
 ### Run Tools
 
 <details>
-<summary><code>run_js-in-browser</code> - Runs custom JavaScript INSIDE the active browser page using Playwright's "page.evaluate()".</summary>
+<summary><code>execute</code> - Batch-execute multiple tool calls in a single request via custom JavaScript. Reduces round-trips and token usage.</summary>
 
 **Parameters:**
-- `script` (string, required): JavaScript code to execute
+- `code` (string, required): JavaScript code to run in a sandboxed VM. Wrapped in an async IIFE, so `await` and `return` work directly. Use `callTool(name, input, returnOutput?)` to invoke any registered MCP tool.
+- `timeoutMs` (number, optional): Wall-clock timeout for the entire execution in ms, including all awaited tool calls and sleep (default: 30000, max: 120000)
 
 **Returns:**
-- `result` (any): Result of the evaluation. This value can be of any type, including primitives, arrays, or objects. It represents the direct return value of the JavaScript expression executed in the page context.
-
-**Notes:**
-- The code executes in the PAGE CONTEXT (real browser environment):
-  - Has access to window, document, DOM, Web APIs
-  - Can read/modify the page state
-  - Runs with the same permissions as the loaded web page
-- The code runs in an isolated execution context, but within the page
-- No direct access to Node.js APIs
-- Return value must be serializable
-
-**Typical use cases:**
-- Inspect or mutate DOM state
-- Read client-side variables or framework internals
-- Trigger browser-side logic
-- Extract computed values directly from the page
-</details>
-
-<details>
-<summary><code>run_js-in-sandbox</code> - Runs custom JavaScript inside a Node.js VM sandbox on the MCP server (NOT in the browser).</summary>
-
-**Parameters:**
-- `code` (string, required): JavaScript code to run on the MCP server in a VM sandbox. The code is wrapped in an async IIFE, so `await` is allowed. Use `return ...` to return a value
-- `timeoutMs` (number, optional): Max VM CPU time for synchronous execution in milliseconds (default: 5000, max: 30000)
-
-**Returns:**
-- `result` (any): Return value of the sandboxed code (best-effort JSON-safe). If user returns undefined but logs exist, returns `{ logs }`. If error occurs, returns `{ error, logs }`
-
-**Available bindings:**
-- `page`: Playwright Page (main interaction surface)
-- `console`: captured logs (log/warn/error)
-- `sleep(ms)`: async helper
-
-**Safe built-ins:**
-- Math, JSON, Number, String, Boolean, Array, Object, Date, RegExp
-- isFinite, isNaN, parseInt, parseFloat
-- URL, URLSearchParams
-- TextEncoder, TextDecoder
-- structuredClone
-- crypto.randomUUID()
-- AbortController
-- setTimeout / clearTimeout
+- `toolOutputs` (array): Tool outputs where `callTool` was called with `returnOutput=true`. Each entry has `name` (tool name) and `output` (tool result).
+- `logs` (array): Captured `console.log/warn/error` calls. Each entry has `level` and `message`.
+- `result` (any, optional): Return value of the code (JSON-safe). Undefined on error or when nothing is returned.
+- `error` (string, optional): Error message with stack trace on failure. Partial `toolOutputs`/`logs` are still returned.
+- `failedTool` (object, optional): Present when a `callTool` invocation caused the error. Contains `name` (tool that failed) and `error` (error message).
+
+**Bindings:**
+- `await callTool(name, input, returnOutput?)`: Invoke any registered MCP tool. Always use with `await`. When `returnOutput=true`, the output is included in the response `toolOutputs` array. Throws on failure — execution stops at the first error.
+- `console.log/warn/error`: Captured in the response `logs` array (max 500 entries).
+- `sleep(ms)`: Async delay helper.
+
+**Session execution context (injected into VM):**
+- **Browser platform:** `page` (Playwright Page) is available. Use the Playwright API (e.g. `page.locator()`, `page.goto()`) or `await page.evaluate(() => { ... })` / `page.evaluateHandle()` to run script in the browser.
+- **Node platform:** No extra bindings (empty object).
+
+**Built-ins (isolated via VM context):**
+- Math, JSON, Date, RegExp, Number, String, Boolean, Array, Object, Promise, Map, Set, WeakMap, WeakSet, Symbol, Proxy, Reflect
+- URL, URLSearchParams, TextEncoder, TextDecoder, structuredClone
+- crypto.randomUUID(), AbortController, setTimeout, clearTimeout
 
 **NOT available:**
-- require, process, fs, Buffer
-- globalThis
-
-**Notes:**
-- This runs on the MCP SERVER (not in the browser)
-- This is NOT a security boundary. Intended for trusted automation logic
-- The timeoutMs parameter limits synchronous execution time, but does not automatically time out awaited Promises
-</details>
-
-<details>
-<summary><code>run_js-in-node</code> - Runs custom JavaScript INSIDE the connected Node.js process (Node platform only).</summary>
-
-**Parameters:**
-- `script` (string, required): JavaScript code to execute in the Node process. Use `return` to pass a value back (e.g. `return process.memoryUsage();`). Async/await is supported (e.g. `return await fetch(url).then(r => r.json());`).
-- `timeoutMs` (number, optional): Max evaluation time in milliseconds (default: 5000, max: 30000)
-
-**Returns:**
-- `result` (any): The result of the evaluation. Can be primitives, arrays, or objects. Must be serializable (JSON-compatible).
+- require, import, process, fs, Buffer, fetch
+
+**Limits:**
+- Max 50 `callTool` invocations per execution
+- Max 500 console log entries
+- Wall-clock timeout covers all async work (tool calls, sleep, etc.)
+- Separate sync CPU guard (10s) prevents tight infinite loops
+
+**Example — fill form, submit (with navigation wait), then snapshot and screenshot:**
+```js
+await callTool('interaction_fill', { selector: '#email', value: 'user@test.com' });
+await callTool('interaction_fill', { selector: '#password', value: 'secret123' });
+await callTool('interaction_click', { selector: 'button[type="submit"]', waitForNavigation: true });
+await callTool('a11y_take-aria-snapshot', {}, true);
+await callTool('content_take-screenshot', {}, true);
+```
 
 **Notes:**
-- Requires `debug_connect` first—must be connected to a Node.js process
-- **You must use `return` to get output** (e.g. `return 2+2;`, `return process.memoryUsage();`). The script runs inside an async function.
-- **Async code supported:** use `await` and return a Promise; the tool waits for it and returns the resolved value.
-- Executes in the NODE PROCESS CONTEXT (real Node.js environment):
-  - Has access to process, require, global, and all loaded modules
-  - Can read/modify process state
-  - Full Node.js APIs (fs, http, etc.)
-- Execution blocks the Node event loop until the script (and any returned Promise) completes
-- Long-running scripts will block the process; use short scripts
-- Return value must be serializable
-
-**Typical use cases:**
-- Inspect process state: `return process.memoryUsage();`, `return process.uptime();`
-- Call loaded modules: `return require('os').loadavg();`
-- Read globals or cached data
-- Async: `return await someAsyncCall();`
+- This is the **recommended** way to perform multi-step interactions. Instead of separate tool calls for each fill/click/select, batch them together for fewer round-trips and lower token usage.
+- Execution runs in an isolated VM context — prototype modifications inside the sandbox do not leak to the host process.
+- All timers created via `setTimeout` are automatically cleaned up when execution ends, preventing dangling callbacks.
+- Image buffers are stripped from `toolOutputs` to keep the response compact; use `screenshotFilePath` to access images.
 </details>
 
 ### Observability (O11Y) Tools
@@ -1592,9 +1603,12 @@ Once disabled, no data is sent and no network requests are made to PostHog.
 - `limit` (object, optional): Limit results (default: last 100). Omit or set `count: 0` for no limit.
   - `count` (number, default 100): Maximum number of requests; 0 = no limit
   - `from` (enum): "start" or "end" (default: "end")
+- `includeRequestHeaders` (boolean, optional): Include request headers in each item (default: false)
+- `includeResponseHeaders` (boolean, optional): Include response headers in each item (default: false)
+- `includeResponseBody` (boolean, optional): Include response body in each item (default: false)
 
 **Returns:**
-- `requests` (array): Array of HTTP requests with URL, method, headers, body, response, timing, and metadata
+- `requests` (array): Array of HTTP requests with URL, method, resourceType, timing, and metadata. Request `headers`, response `headers`, and response `body` are present only when the corresponding `include*` parameter is true.
 </details>
 
 <details>
@@ -2174,7 +2188,7 @@ A dedicated Claude Code plugin is available with slash commands, skills, and age
 **Skills (6 skills):**
 - `browser-testing` - General browser test capabilities
 - `web-debugging` - Console, network, JS debugging
-- `node-debugging` - Node.js backend debugging (tracepoints, logpoints, run_js-in-node)
+- `node-debugging` - Node.js backend debugging (tracepoints, logpoints)
 - `performance-audit` - Web Vitals and performance analysis
 - `visual-testing` - Visual testing and responsive design
 - `observability` - Distributed tracing and monitoring

package/SECURITY.md

@@ -36,10 +36,7 @@ If you discover a security vulnerability in Browser DevTools MCP, please report
 
 Browser DevTools MCP provides powerful browser automation capabilities. Users should be aware of:
 
-1. **Code Execution**: The `run_js-in-browser` and `run_js-in-sandbox` tools execute arbitrary JavaScript code
-   - `run_js-in-browser`: Executes in the page context with full DOM access
-   - `run_js-in-sandbox`: Executes in a Node.js VM sandbox (NOT a security boundary)
-   - Only use with trusted code inputs
+1. **Code Execution**: The `execute` tool runs arbitrary JavaScript in a VM; on the browser platform it receives `page` (Playwright Page) so code can also run script in the browser via `page.evaluate()`. The VM is not a security boundary — only use with trusted code inputs.
 
 2. **Network Access**: The browser can make requests to any URL
    - HTTP requests from the browser inherit the page's cookies and session
@@ -106,11 +103,10 @@ When using HTTP transport (`--transport=streamable-http`):
 
 ### Sandbox Isolation
 
-The `run_js-in-sandbox` tool provides limited isolation:
-- Runs in Node.js VM context
-- No access to `require`, `process`, `fs`, `Buffer`
-- Limited built-in APIs available
-- **Note**: This is NOT a security boundary - treat all input as trusted
+The `execute` tool runs in a Node.js VM context with limited isolation:
+- No access to `require`, `process`, `fs`, `Buffer`, `fetch`
+- Limited built-in APIs available; on browser platform `page` (Playwright Page) is injected
+- **Note**: This is NOT a security boundary — treat all input as trusted
 
 ### OpenTelemetry Security
 

package/dist/cli/runner.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import{isToolEnabled,platformInfo}from"../core-RRWTV5B5.js";import{AMAZON_BEDROCK_ENABLE,AMAZON_BEDROCK_IMAGE_EMBED_MODEL_ID,AMAZON_BEDROCK_TEXT_EMBED_MODEL_ID,AMAZON_BEDROCK_VISION_MODEL_ID,AWS_PROFILE,AWS_REGION,DAEMON_PORT,DAEMON_SESSION_IDLE_CHECK_SECONDS,DAEMON_SESSION_IDLE_SECONDS,FIGMA_ACCESS_TOKEN,FIGMA_API_BASE_URL,OTEL_ENABLE,OTEL_EXPORTER_HTTP_URL,OTEL_EXPORTER_TYPE,OTEL_SERVICE_NAME,OTEL_SERVICE_VERSION}from"../core-DOXUXYCD.js";import{Command,Option}from"commander";import{ZodFirstPartyTypeKind}from"zod";function _unwrapZodType(zodType){let current=zodType,isOptional=!1,defaultValue;for(;;){let typeName=current._def.typeName;if(typeName===ZodFirstPartyTypeKind.ZodOptional)isOptional=!0,current=current._def.innerType;else if(typeName===ZodFirstPartyTypeKind.ZodDefault)isOptional=!0,defaultValue=current._def.defaultValue(),current=current._def.innerType;else if(typeName===ZodFirstPartyTypeKind.ZodNullable)isOptional=!0,current=current._def.innerType;else break}return{innerType:current,isOptional,defaultValue}}function _getDescription(zodType){return zodType._def.description}function _toCamelCase(str){return str.replace(/[-_]([a-z])/g,(_,letter)=>letter.toUpperCase())}function _toKebabCase(str){return str.replace(/([a-z])([A-Z])/g,"$1-$2").toLowerCase()}function _createOption(name,zodType){let{innerType,isOptional,defaultValue}=_unwrapZodType(zodType),description=_getDescription(zodType)||`The ${name} value`,flagName=_toKebabCase(name),typeName=innerType._def.typeName,option;switch(typeName){case ZodFirstPartyTypeKind.ZodString:option=new Option(`--${flagName} <string>`,description);break;case ZodFirstPartyTypeKind.ZodNumber:option=new Option(`--${flagName} <number>`,description),option.argParser(value=>{let n=Number(value);if(!Number.isFinite(n))throw new Error(`Invalid number: ${value}`);return n});break;case ZodFirstPartyTypeKind.ZodBoolean:option=new Option(`--${flagName}`,description);break;case ZodFirstPartyTypeKind.ZodEnum:let enumValues=innerType._def.values;option=new Option(`--${flagName} <choice>`,description).choices(enumValues);break;case ZodFirstPartyTypeKind.ZodArray:option=new Option(`--${flagName} <value...>`,description);break;case ZodFirstPartyTypeKind.ZodObject:case ZodFirstPartyTypeKind.ZodRecord:option=new Option(`--${flagName} <json>`,description),option.argParser(value=>{try{return JSON.parse(value)}catch{throw new Error(`Invalid JSON: ${value}`)}});break;case ZodFirstPartyTypeKind.ZodAny:case ZodFirstPartyTypeKind.ZodUnknown:option=new Option(`--${flagName} <value>`,description),option.argParser(value=>{try{return JSON.parse(value)}catch{return value}});break;case ZodFirstPartyTypeKind.ZodLiteral:let literalValue=innerType._def.value;typeof literalValue=="boolean"?option=new Option(`--${flagName}`,description):(option=new Option(`--${flagName} <value>`,description),option.default(literalValue));break;case ZodFirstPartyTypeKind.ZodUnion:let unionOptions=innerType._def.options;if(unionOptions.every(opt=>opt._def.typeName===ZodFirstPartyTypeKind.ZodLiteral)){let choices=unionOptions.map(opt=>String(opt._def.value));option=new Option(`--${flagName} <choice>`,description).choices(choices)}else option=new Option(`--${flagName} <value>`,description),option.argParser(value=>{try{return JSON.parse(value)}catch{return value}});break;default:option=new Option(`--${flagName} <value>`,description);break}return defaultValue!==void 0&&option.default(defaultValue),!isOptional&&defaultValue===void 0&&option.makeOptionMandatory(!0),option}function _generateOptionsFromSchema(schema,toolName){let options=[];for(let[name,zodType]of Object.entries(schema)){let option=_createOption(name,zodType);option&&options.push(option)}return options}function _parseOptionsToToolInput(options){let result={};for(let[key,value]of Object.entries(options)){let camelKey=_toCamelCase(key);value!==void 0&&(result[camelKey]=value)}return result}function _parseToolName(toolName){let underscoreIndex=toolName.indexOf("_");return underscoreIndex===-1?{domain:"default",commandName:toolName}:{domain:toolName.substring(0,underscoreIndex),commandName:toolName.substring(underscoreIndex+1)}}function registerToolCommands(program,tools2,handler){let domainCommands=new Map;for(let tool of tools2){let{domain,commandName}=_parseToolName(tool.name()),domainCommand=domainCommands.get(domain);domainCommand||(domainCommand=new Command(domain).description(`${domain.charAt(0).toUpperCase()+domain.slice(1)} commands`),domainCommands.set(domain,domainCommand),program.addCommand(domainCommand));let toolCommand=new Command(commandName).description(tool.description().trim()),options=_generateOptionsFromSchema(tool.inputSchema(),tool.name());for(let option of options)toolCommand.addOption(option);toolCommand.action(async opts=>{let toolInput=_parseOptionsToToolInput(opts),globalOptions=program.opts();await handler(tool.name(),toolInput,globalOptions)}),domainCommand.addCommand(toolCommand)}}import{spawn,execSync}from"node:child_process";import{createRequire}from"node:module";import*as path from"node:path";import*as readline from"node:readline";import{fileURLToPath}from"node:url";import{Command as Command2,Option as Option2}from"commander";var require2=createRequire(import.meta.url),__filename=fileURLToPath(import.meta.url),__dirname=path.dirname(__filename),cliProvider=platformInfo.cliInfo.cliProvider,tools=cliProvider.tools.filter(isToolEnabled),DEFAULT_TIMEOUT=3e4,verboseEnabled=!1,quietEnabled=!1;function _debug(message,data){if(verboseEnabled){let timestamp=new Date().toISOString();data!==void 0?console.error(`[${timestamp}] [DEBUG] ${message}`,data):console.error(`[${timestamp}] [DEBUG] ${message}`)}}function _output(message){quietEnabled||console.log(message)}function _error(message){console.error(message)}async function _isDaemonRunning(port){_debug(`Checking if daemon is running on port ${port}`);try{let response=await fetch(`http://localhost:${port}/health`,{method:"GET",signal:AbortSignal.timeout(3e3)});if(response.ok){let isRunning=(await response.json()).status==="ok";return _debug(`Daemon health check result: ${isRunning?"running":"not running"}`),isRunning}return _debug(`Daemon health check failed: HTTP ${response.status}`),!1}catch(err){return _debug(`Daemon health check error: ${err.message}`),!1}}function _buildDaemonEnv(opts){return cliProvider.buildEnv(opts)}function _startDaemonDetached(opts){let daemonServerPath=path.join(__dirname,"..","daemon-server.js"),env=_buildDaemonEnv(opts);_debug(`Starting daemon server from: ${daemonServerPath}`),_debug(`Daemon port: ${opts.port}`);let child=spawn(process.execPath,[daemonServerPath,"--port",String(opts.port)],{detached:!0,stdio:"ignore",env});child.unref(),_debug(`Daemon process spawned with PID: ${child.pid}`),_output(`Started daemon server as detached process (PID: ${child.pid})`)}async function _ensureDaemonRunning(opts){if(await _isDaemonRunning(opts.port))_debug("Daemon is already running");else{_output(`Daemon server is not running on port ${opts.port}, starting...`),_startDaemonDetached(opts);let maxRetries=10,retryDelay=500;_debug(`Waiting for daemon to be ready (max ${maxRetries} retries, ${retryDelay}ms delay)`);for(let i=0;i<maxRetries;i++)if(await new Promise(resolve=>setTimeout(resolve,retryDelay)),_debug(`Retry ${i+1}/${maxRetries}: checking daemon status...`),await _isDaemonRunning(opts.port)){_debug("Daemon is now ready"),_output("Daemon server is ready");return}throw new Error(`Daemon server failed to start within ${maxRetries*retryDelay/1e3} seconds`)}}async function _stopDaemon(port,timeout){try{return(await fetch(`http://localhost:${port}/shutdown`,{method:"POST",signal:AbortSignal.timeout(timeout)})).ok}catch{return!1}}async function _callTool(port,toolName,toolInput,sessionId,timeout){let headers={"Content-Type":"application/json"};sessionId&&(headers["session-id"]=sessionId);let request={toolName,toolInput};_debug(`Calling tool: ${toolName}`),_debug("Tool input:",toolInput),_debug(`Session ID: ${sessionId||"(default)"}`),_debug(`Timeout: ${timeout||"none"}`);let startTime=Date.now(),response=await fetch(`http://localhost:${port}/call`,{method:"POST",headers,body:JSON.stringify(request),signal:timeout?AbortSignal.timeout(timeout):void 0}),duration=Date.now()-startTime;if(_debug(`Tool call completed in ${duration}ms, status: ${response.status}`),!response.ok){let errorBody=await response.json().catch(()=>({}));_debug("Tool call error:",errorBody);let message=errorBody?.toolError?.message||errorBody?.error?.message||`HTTP ${response.status}: ${response.statusText}`;throw new Error(message)}let result=await response.json();return _debug("Tool call result:",result.toolError?{error:result.toolError}:{success:!0}),result}async function _deleteSession(port,sessionId,timeout){try{return(await fetch(`http://localhost:${port}/session`,{method:"DELETE",headers:{"session-id":sessionId},signal:AbortSignal.timeout(timeout)})).ok}catch{return!1}}async function _getDaemonInfo(port,timeout){try{let response=await fetch(`http://localhost:${port}/info`,{method:"GET",signal:AbortSignal.timeout(timeout)});return response.ok?await response.json():null}catch{return null}}async function _listSessions(port,timeout){try{let response=await fetch(`http://localhost:${port}/sessions`,{method:"GET",signal:AbortSignal.timeout(timeout)});return response.ok?await response.json():null}catch{return null}}async function _getSessionInfo(port,sessionId,timeout){try{let response=await fetch(`http://localhost:${port}/session`,{method:"GET",headers:{"session-id":sessionId},signal:AbortSignal.timeout(timeout)});return response.ok?await response.json():null}catch{return null}}function _formatUptime(seconds){let days=Math.floor(seconds/86400),hours=Math.floor(seconds%86400/3600),minutes=Math.floor(seconds%3600/60),secs=seconds%60,parts=[];return days>0&&parts.push(`${days}d`),hours>0&&parts.push(`${hours}h`),minutes>0&&parts.push(`${minutes}m`),parts.push(`${secs}s`),parts.join(" ")}function _formatTimestamp(timestamp){return new Date(timestamp).toISOString()}function _getZodTypeName(schema){let typeName=schema._def.typeName;return typeName==="ZodOptional"||typeName==="ZodNullable"||typeName==="ZodDefault"?_getZodTypeName(schema._def.innerType):typeName==="ZodArray"?`${_getZodTypeName(schema._def.type)}[]`:typeName==="ZodEnum"?schema._def.values.join(" | "):typeName==="ZodLiteral"?JSON.stringify(schema._def.value):typeName==="ZodUnion"?schema._def.options.map(opt=>_getZodTypeName(opt)).join(" | "):{ZodString:"string",ZodNumber:"number",ZodBoolean:"boolean",ZodObject:"object",ZodRecord:"Record<string, any>",ZodAny:"any"}[typeName]||typeName.replace("Zod","").toLowerCase()}function _getZodDescription(schema){if(schema._def.description)return schema._def.description;if(schema._def.typeName==="ZodOptional"||schema._def.typeName==="ZodNullable"||schema._def.typeName==="ZodDefault")return _getZodDescription(schema._def.innerType)}function _isZodOptional(schema){let typeName=schema._def.typeName;return typeName==="ZodOptional"||typeName==="ZodNullable"}function _hasZodDefault(schema){return schema._def.typeName==="ZodDefault"?!0:schema._def.typeName==="ZodOptional"||schema._def.typeName==="ZodNullable"?_hasZodDefault(schema._def.innerType):!1}function _getZodDefault(schema){if(schema._def.typeName==="ZodDefault")return schema._def.defaultValue();if(schema._def.typeName==="ZodOptional"||schema._def.typeName==="ZodNullable")return _getZodDefault(schema._def.innerType)}function _formatOutput(output,indent=0){let prefix="  ".repeat(indent);if(output==null)return`${prefix}(empty)`;if(typeof output=="string")return output.split(`
+import{isToolEnabled,platformInfo}from"../core-FKJAPNIK.js";import{AMAZON_BEDROCK_ENABLE,AMAZON_BEDROCK_IMAGE_EMBED_MODEL_ID,AMAZON_BEDROCK_TEXT_EMBED_MODEL_ID,AMAZON_BEDROCK_VISION_MODEL_ID,AWS_PROFILE,AWS_REGION,DAEMON_PORT,DAEMON_SESSION_IDLE_CHECK_SECONDS,DAEMON_SESSION_IDLE_SECONDS,FIGMA_ACCESS_TOKEN,FIGMA_API_BASE_URL,OTEL_ENABLE,OTEL_EXPORTER_HTTP_URL,OTEL_EXPORTER_TYPE,OTEL_SERVICE_NAME,OTEL_SERVICE_VERSION}from"../core-3M2NFQVF.js";import{Command,Option}from"commander";import{ZodFirstPartyTypeKind}from"zod";function _unwrapZodType(zodType){let current=zodType,isOptional=!1,defaultValue;for(;;){let typeName=current._def.typeName;if(typeName===ZodFirstPartyTypeKind.ZodOptional)isOptional=!0,current=current._def.innerType;else if(typeName===ZodFirstPartyTypeKind.ZodDefault)isOptional=!0,defaultValue=current._def.defaultValue(),current=current._def.innerType;else if(typeName===ZodFirstPartyTypeKind.ZodNullable)isOptional=!0,current=current._def.innerType;else break}return{innerType:current,isOptional,defaultValue}}function _getDescription(zodType){return zodType._def.description}function _toCamelCase(str){return str.replace(/[-_]([a-z])/g,(_,letter)=>letter.toUpperCase())}function _toKebabCase(str){return str.replace(/([a-z])([A-Z])/g,"$1-$2").toLowerCase()}function _createOption(name,zodType){let{innerType,isOptional,defaultValue}=_unwrapZodType(zodType),description=_getDescription(zodType)||`The ${name} value`,flagName=_toKebabCase(name),typeName=innerType._def.typeName,option;switch(typeName){case ZodFirstPartyTypeKind.ZodString:option=new Option(`--${flagName} <string>`,description);break;case ZodFirstPartyTypeKind.ZodNumber:option=new Option(`--${flagName} <number>`,description),option.argParser(value=>{let n=Number(value);if(!Number.isFinite(n))throw new Error(`Invalid number: ${value}`);return n});break;case ZodFirstPartyTypeKind.ZodBoolean:option=new Option(`--${flagName}`,description);break;case ZodFirstPartyTypeKind.ZodEnum:let enumValues=innerType._def.values;option=new Option(`--${flagName} <choice>`,description).choices(enumValues);break;case ZodFirstPartyTypeKind.ZodArray:option=new Option(`--${flagName} <value...>`,description);break;case ZodFirstPartyTypeKind.ZodObject:case ZodFirstPartyTypeKind.ZodRecord:option=new Option(`--${flagName} <json>`,description),option.argParser(value=>{try{return JSON.parse(value)}catch{throw new Error(`Invalid JSON: ${value}`)}});break;case ZodFirstPartyTypeKind.ZodAny:case ZodFirstPartyTypeKind.ZodUnknown:option=new Option(`--${flagName} <value>`,description),option.argParser(value=>{try{return JSON.parse(value)}catch{return value}});break;case ZodFirstPartyTypeKind.ZodLiteral:let literalValue=innerType._def.value;typeof literalValue=="boolean"?option=new Option(`--${flagName}`,description):(option=new Option(`--${flagName} <value>`,description),option.default(literalValue));break;case ZodFirstPartyTypeKind.ZodUnion:let unionOptions=innerType._def.options;if(unionOptions.every(opt=>opt._def.typeName===ZodFirstPartyTypeKind.ZodLiteral)){let choices=unionOptions.map(opt=>String(opt._def.value));option=new Option(`--${flagName} <choice>`,description).choices(choices)}else option=new Option(`--${flagName} <value>`,description),option.argParser(value=>{try{return JSON.parse(value)}catch{return value}});break;default:option=new Option(`--${flagName} <value>`,description);break}return defaultValue!==void 0&&option.default(defaultValue),!isOptional&&defaultValue===void 0&&option.makeOptionMandatory(!0),option}function _generateOptionsFromSchema(schema,toolName){let options=[];for(let[name,zodType]of Object.entries(schema)){let option=_createOption(name,zodType);option&&options.push(option)}return options}function _parseOptionsToToolInput(options){let result={};for(let[key,value]of Object.entries(options)){let camelKey=_toCamelCase(key);value!==void 0&&(result[camelKey]=value)}return result}function _parseToolName(toolName){let underscoreIndex=toolName.indexOf("_");return underscoreIndex===-1?{domain:"default",commandName:toolName}:{domain:toolName.substring(0,underscoreIndex),commandName:toolName.substring(underscoreIndex+1)}}function registerToolCommands(program,tools2,handler){let domainCommands=new Map;for(let tool of tools2){let{domain,commandName}=_parseToolName(tool.name()),domainCommand=domainCommands.get(domain);domainCommand||(domainCommand=new Command(domain).description(`${domain.charAt(0).toUpperCase()+domain.slice(1)} commands`),domainCommands.set(domain,domainCommand),program.addCommand(domainCommand));let toolCommand=new Command(commandName).description(tool.description().trim()),options=_generateOptionsFromSchema(tool.inputSchema(),tool.name());for(let option of options)toolCommand.addOption(option);toolCommand.action(async opts=>{let toolInput=_parseOptionsToToolInput(opts),globalOptions=program.opts();await handler(tool.name(),toolInput,globalOptions)}),domainCommand.addCommand(toolCommand)}}import{spawn,execSync}from"node:child_process";import{createRequire}from"node:module";import*as path from"node:path";import*as readline from"node:readline";import{fileURLToPath}from"node:url";import{Command as Command2,Option as Option2}from"commander";var require2=createRequire(import.meta.url),__filename=fileURLToPath(import.meta.url),__dirname=path.dirname(__filename),cliProvider=platformInfo.cliInfo.cliProvider,tools=cliProvider.tools.filter(isToolEnabled),DEFAULT_TIMEOUT=3e4,verboseEnabled=!1,quietEnabled=!1;function _debug(message,data){if(verboseEnabled){let timestamp=new Date().toISOString();data!==void 0?console.error(`[${timestamp}] [DEBUG] ${message}`,data):console.error(`[${timestamp}] [DEBUG] ${message}`)}}function _output(message){quietEnabled||console.log(message)}function _error(message){console.error(message)}async function _isDaemonRunning(port){_debug(`Checking if daemon is running on port ${port}`);try{let response=await fetch(`http://localhost:${port}/health`,{method:"GET",signal:AbortSignal.timeout(3e3)});if(response.ok){let isRunning=(await response.json()).status==="ok";return _debug(`Daemon health check result: ${isRunning?"running":"not running"}`),isRunning}return _debug(`Daemon health check failed: HTTP ${response.status}`),!1}catch(err){return _debug(`Daemon health check error: ${err.message}`),!1}}function _buildDaemonEnv(opts){return cliProvider.buildEnv(opts)}function _startDaemonDetached(opts){let daemonServerPath=path.join(__dirname,"..","daemon-server.js"),env=_buildDaemonEnv(opts);_debug(`Starting daemon server from: ${daemonServerPath}`),_debug(`Daemon port: ${opts.port}`);let child=spawn(process.execPath,[daemonServerPath,"--port",String(opts.port)],{detached:!0,stdio:"ignore",env});child.unref(),_debug(`Daemon process spawned with PID: ${child.pid}`),_output(`Started daemon server as detached process (PID: ${child.pid})`)}async function _ensureDaemonRunning(opts){if(await _isDaemonRunning(opts.port))_debug("Daemon is already running");else{_output(`Daemon server is not running on port ${opts.port}, starting...`),_startDaemonDetached(opts);let maxRetries=10,retryDelay=500;_debug(`Waiting for daemon to be ready (max ${maxRetries} retries, ${retryDelay}ms delay)`);for(let i=0;i<maxRetries;i++)if(await new Promise(resolve=>setTimeout(resolve,retryDelay)),_debug(`Retry ${i+1}/${maxRetries}: checking daemon status...`),await _isDaemonRunning(opts.port)){_debug("Daemon is now ready"),_output("Daemon server is ready");return}throw new Error(`Daemon server failed to start within ${maxRetries*retryDelay/1e3} seconds`)}}async function _stopDaemon(port,timeout){try{return(await fetch(`http://localhost:${port}/shutdown`,{method:"POST",signal:AbortSignal.timeout(timeout)})).ok}catch{return!1}}async function _callTool(port,toolName,toolInput,sessionId,timeout){let headers={"Content-Type":"application/json"};sessionId&&(headers["session-id"]=sessionId);let request={toolName,toolInput};_debug(`Calling tool: ${toolName}`),_debug("Tool input:",toolInput),_debug(`Session ID: ${sessionId||"(default)"}`),_debug(`Timeout: ${timeout||"none"}`);let startTime=Date.now(),response=await fetch(`http://localhost:${port}/call`,{method:"POST",headers,body:JSON.stringify(request),signal:timeout?AbortSignal.timeout(timeout):void 0}),duration=Date.now()-startTime;if(_debug(`Tool call completed in ${duration}ms, status: ${response.status}`),!response.ok){let errorBody=await response.json().catch(()=>({}));_debug("Tool call error:",errorBody);let message=errorBody?.toolError?.message||errorBody?.error?.message||`HTTP ${response.status}: ${response.statusText}`;throw new Error(message)}let result=await response.json();return _debug("Tool call result:",result.toolError?{error:result.toolError}:{success:!0}),result}async function _deleteSession(port,sessionId,timeout){try{return(await fetch(`http://localhost:${port}/session`,{method:"DELETE",headers:{"session-id":sessionId},signal:AbortSignal.timeout(timeout)})).ok}catch{return!1}}async function _getDaemonInfo(port,timeout){try{let response=await fetch(`http://localhost:${port}/info`,{method:"GET",signal:AbortSignal.timeout(timeout)});return response.ok?await response.json():null}catch{return null}}async function _listSessions(port,timeout){try{let response=await fetch(`http://localhost:${port}/sessions`,{method:"GET",signal:AbortSignal.timeout(timeout)});return response.ok?await response.json():null}catch{return null}}async function _getSessionInfo(port,sessionId,timeout){try{let response=await fetch(`http://localhost:${port}/session`,{method:"GET",headers:{"session-id":sessionId},signal:AbortSignal.timeout(timeout)});return response.ok?await response.json():null}catch{return null}}function _formatUptime(seconds){let days=Math.floor(seconds/86400),hours=Math.floor(seconds%86400/3600),minutes=Math.floor(seconds%3600/60),secs=seconds%60,parts=[];return days>0&&parts.push(`${days}d`),hours>0&&parts.push(`${hours}h`),minutes>0&&parts.push(`${minutes}m`),parts.push(`${secs}s`),parts.join(" ")}function _formatTimestamp(timestamp){return new Date(timestamp).toISOString()}function _getZodTypeName(schema){let typeName=schema._def.typeName;return typeName==="ZodOptional"||typeName==="ZodNullable"||typeName==="ZodDefault"?_getZodTypeName(schema._def.innerType):typeName==="ZodArray"?`${_getZodTypeName(schema._def.type)}[]`:typeName==="ZodEnum"?schema._def.values.join(" | "):typeName==="ZodLiteral"?JSON.stringify(schema._def.value):typeName==="ZodUnion"?schema._def.options.map(opt=>_getZodTypeName(opt)).join(" | "):{ZodString:"string",ZodNumber:"number",ZodBoolean:"boolean",ZodObject:"object",ZodRecord:"Record<string, any>",ZodAny:"any"}[typeName]||typeName.replace("Zod","").toLowerCase()}function _getZodDescription(schema){if(schema._def.description)return schema._def.description;if(schema._def.typeName==="ZodOptional"||schema._def.typeName==="ZodNullable"||schema._def.typeName==="ZodDefault")return _getZodDescription(schema._def.innerType)}function _isZodOptional(schema){let typeName=schema._def.typeName;return typeName==="ZodOptional"||typeName==="ZodNullable"}function _hasZodDefault(schema){return schema._def.typeName==="ZodDefault"?!0:schema._def.typeName==="ZodOptional"||schema._def.typeName==="ZodNullable"?_hasZodDefault(schema._def.innerType):!1}function _getZodDefault(schema){if(schema._def.typeName==="ZodDefault")return schema._def.defaultValue();if(schema._def.typeName==="ZodOptional"||schema._def.typeName==="ZodNullable")return _getZodDefault(schema._def.innerType)}function _formatOutput(output,indent=0){let prefix="  ".repeat(indent);if(output==null)return`${prefix}(empty)`;if(typeof output=="string")return output.split(`
 `).map(line=>`${prefix}${line}`).join(`
 `);if(typeof output=="number"||typeof output=="boolean")return`${prefix}${output}`;if(Array.isArray(output))return output.length===0?`${prefix}[]`:output.map(item=>_formatOutput(item,indent)).join(`
 `);if(typeof output=="object"){let lines=[];for(let[key,value]of Object.entries(output))value!==void 0&&(typeof value=="object"&&value!==null&&!Array.isArray(value)?(lines.push(`${prefix}${key}:`),lines.push(_formatOutput(value,indent+1))):Array.isArray(value)?(lines.push(`${prefix}${key}:`),lines.push(_formatOutput(value,indent+1))):lines.push(`${prefix}${key}: ${value}`));return lines.join(`