BTAP exposes three capability layers so an agent can choose the narrowest interface that matches the task:

• Page capability — DOM inspection, JavaScript, waiting, scrolling, screenshots, and page_* CDP input inside a named tab. This is the default path for ordinary web workflows and does not use the operating system mouse or keyboard.
• Browser capability — the real Chromium profile and its browser-native surface: tabs, downloads, cookies, storage, permissions, bookmarks, extensions, service-worker messaging, and raw CDP. These operations can work without a foreground tab.
• Desktop capability — explicit inspection and cancellation attempts for a foreground Windows standard file dialog owned by registered Chrome or Edge. Call inspect_native_file_dialog first, then use its short-lived ticket with cancel_native_file_dialog; both require desktop_opt_in=true and [desktop]. Other browser UI and unsupported native layouts remain outside this surface. The seven global OS input/screenshot tools removed in 0.5.0 remain removed.

resolve_leave_dialog remains a page-scoped, lab-only recovery workflow; its final Enter fallback is a restricted exception, not a general desktop surface. get_setup_status returns tool counts and capability groups in data.capability_registry. MCP tools/list supplies the actual tool schemas and explicit readOnlyHint, destructiveHint, idempotentHint, and openWorldHint for every tool. These describe all supported parameter paths: tools with optional script execution, buffer clearing, or file writes are not classified as read-only. get_setup_status can tighten an existing Windows token file's ACL and is also classified as state-changing. Annotations help hosts plan calls; they do not grant permission or replace BTAP's ownership and concurrency checks.

Every public tool now returns the btap.result.v1 envelope without renaming tools: successful operation data is in data, explicit legacy failure payloads remain in legacy, and error/error_code, retryable, target, and diagnostics provide stable machine-readable status. Failures also set MCP isError=true. Arrays, objects, HTML, and other large bodies are read from data or legacy; only small scalar operation fields are projected at the top level for compatibility. Use the envelope's retry verdict: an explicit retry_safe=false or possible execution overrides a connection error's usual retry hint.

claude mcp add browsertap -- browsertap

Add --scope user to make it available across all projects. For a virtualenv install:

claude mcp add browsertap -- /absolute/path/to/.venv/bin/browsertap

On Windows PowerShell, use the absolute path to .venv\Scripts\browsertap.exe instead.

Verify with /mcp.

Follow the MCP install guide and use the standard config above. An example file is included at examples/claude-desktop-config.json.

Put the standard config in .cursor/mcp.json for one project, or ~/.cursor/mcp.json globally. An example file is included at examples/cursor-mcp.json.

code --add-mcp '{"name":"browsertap-mcp","command":"browsertap"}'

Or write it into .vscode/mcp.json by hand — note that VS Code's key is servers, not mcpServers.

Add to ~/.hermes/config.yaml:

mcp_servers:
  browsertap:
    command: browsertap
    timeout: 120
    connect_timeout: 60

browsertap print-hermes-config prints this snippet. An example file is included at examples/hermes-config.yaml. Verify with hermes mcp list.

Any MCP client that speaks stdio will work. Follow its own install guide and use the standard config above.

• get_setup_status — report package_version, bridge_version, extension_version, protocol_version, connection state, ports, tabs, and the required recovery action. A missing bridge listener is started automatically when spawning is enabled; restart_bridge_required=true means a bridge that is still running must be replaced with browsertap bridge --restart. reload_extension_required=true identifies the unpacked-extension platform limit and requires a manual Reload; a version number that differs on its own no longer sets it, because Chrome parses manifest.json at load time and never re-parses it without a Reload, so a release bump would otherwise demand a click whose only effect is on that number. restart_mcp_session_required=true is the opposite direction: a component is newer than the running server, so the stale build is this process and only restarting the MCP session or client clears it — the other two flags stay false, because a restart or reload would report the same mismatch again. extension_build_stamp is the stronger signal and answers the question the four version fields cannot: it is a hash of the extension sources compiled into background.js, reported by the worker actually running, so comparing it to expected_extension_build_stamp (a fresh hash of the directory) is decisive in both directions where version equality was measured wrong twice. Read the answer from extension_build_verdict: matches_tree (the worker is running this code), stale_worker (it is not -- Reload), stamp_not_regenerated (an extension file was edited without running python -m scripts.extension_stamp --write, so the comparison proves nothing either way) or unverifiable (the extension predates the stamp, or the directory could not be read -- see extension_build_error). extension_build_enforced=false means no comparison happened, so treat it as unknown rather than as a pass. Answers while another tool is still running; default_session_id is this request's snapshot of the MCP process default and default_session_settled=true because another call's temporary target is isolated. No parameters. extension_status_available=false means the extension has not supplied runtime status: starting asks to wait_for_extension, and extension_unavailable asks to check_extension_connection. Missing status alone does not request a Reload. Compatibility checks, including legacy replies missing required fields, apply once runtime status is available. On Windows, inspecting an existing token file can tighten its ACL to the current user. The token-file state check itself does not create a missing file; get_setup_status may still create one during bridge startup or authentication initialization.
• get_automation_profile — inspect whether the current MCP process uses lab or safe.
• set_automation_profile — switch the current MCP process between lab|safe; the override is not persisted and does not reload the extension.
  • mode (string): lab or safe
• list_tabs — list connected tabs under data.tabs, including their full session handles and browser fields. Answers while another tool is still running; default_session_id is this request's snapshot of the MCP process default and default_session_settled=true. Parallel agents should still pass an explicit target. No parameters. A timed-out inventory releases that read's bridge reservation. Pending mutations keep their reservations; a release does not establish whether another operation happened.
• list_all_tabs — (no tab needed) list every open tab, including chrome-extension:// pages that list_tabs hides. Those never become sessions, so they have no session id; drive them with cdp_command(tab_id=...).
  • session_id (string, optional): which browser/profile to ask.
• switch_tab — set this MCP process's target tab for later calls. A url_pattern must match exactly one tab; if several match, select one with its full session_id. A browser filter matching multiple profiles also requires an explicit session_id. It does not raise the tab or focus the browser: activate defaults to false. Pass activate=true, or call activate_tab, when you need the tab in front.
  • session_id (string, optional), url_pattern (string, optional): substring match, browser (string, optional): chrome, edge, or opera, activate (boolean, optional): default false.
• activate_tab — bring a tab to the foreground and focus its window. This is the explicit way to raise a tab, and the only one that does not involve approving physical input. Check on_screen in the reply: BTAP first asks Windows to restore a minimised browser, but on_screen=false means visibility still could not be confirmed and screen-coordinate input must not be sent.
  • session_id (string, optional)
• open_url — navigate the current tab. Global behavior remains dismiss; lab automatically accepts beforeunload on configured shell/IDE hosts. If the extension's navigate route is unavailable on a heavy SPA, BTAP falls back to Page.navigate. A CDP result with isDownload=true returns {type:"download",status:"triggered"} instead of only navigation_failed; the accompanying ERR_ABORTED is normal for that download navigation.
  • url (string), session_id (string, optional), timeout (number, optional): default 15, beforeunload (string, optional): default dismiss, intent_leave (boolean, optional): false forces page preservation
• download_file — download an HTTP(S) URL through Chrome's native download manager, using that browser profile's cookies and authenticated session. It waits by default and returns status="completed" plus a verified absolute path; interrupted downloads return failed, while a timeout or wait=false returns in_progress with download_id. An explicit session_id must still be live and is never replaced with another profile. Use this for attachments instead of page fetch.
  • url (string), filename (string, optional): relative download name, directory (string, optional): arbitrary absolute destination directory; creates parents, wait (boolean, optional): default true; directory requires true, timeout (number, optional): default 60 seconds, maximum 1800, session_id (string, optional): selects the browser profile, overwrite (boolean, optional): default false; an existing final destination raises an error unless explicitly true. If a directory download times out, directory_applied=false: the move is no longer tracked and Chrome may finish into its default download directory.
• open_new_tab — open a background tab in this MCP process's selected browser/profile, unless session_id or client_id selects another. Creates a unique operation_id and waits a bounded time for exact session/generation registration; pass active=true for foreground work. Returns {operation_id,tab_id,session_id,generation,ready,owned,opener,owner_id,load_status}. The extension deduplicates by operation id. Ownership requires a completed record with exact client_id+tab_id+generation, even when ready=false; ready only reports immediate availability for session tools. Before create dispatch, registry uncertainty returns status="unknown",may_have_created=false,retry_safe=true; after dispatch, uncertainty returns may_have_created=true,retry_safe=false. With may_have_created=false,retry_safe=true, resolve the reported failure and retry without operation_id. To recover a dispatched create with retry_safe=false, pass the same operation_id, returned client_id, and owner_id: recovery reads the durable record without replaying tabs/create. A failed recovery probe preserves that uncertainty and owner capability. If the initial recovery probe finds no record, reconciliation.resume_required=false directs the caller to list_tabs() and inspection of that browser instead of another recovery call. Missing records, matching URLs, or unchanged tab counts cannot prove non-creation or ownership; keep the outcome unknown unless exact identity and task ownership resolve it. Keep owner_id for cleanup of registered task-owned tabs with their exact session/generation. Use this native API for reliable new tabs; page window.open() or anchor clicks may be blocked without a user gesture.
  • url (string), timeout (number, optional): default 15, active (boolean, optional): default false, session_id (optional browser/profile selector), owner_id (optional capability to group several tabs under one task owner), operation_id (optional recovery handle), client_id (optional browser/profile client selector for creation or recovery)
  • A pending create left by a worker restart becomes terminal unknown. Bounded record retention also keeps a replay guard for retired operation IDs; a refused old ID does not prove non-creation. Follow reconciliation.resume_required=false with inspection of that browser, preserving unknown outcomes and exact ownership evidence.
  • A failed status probe may return reconciliation.bridge_operation. Its wire operation_id can be queried with get_execute_js_result in the same MCP session; the outer creation operation_id still belongs to open_new_tab recovery. The probe's reservation_held=false does not prove an earlier create was absent or safe to replay.
• close_tabs — (no tab needed) accept native numeric tab ids or full client:tabId session ids, including chrome-extension:// tabs. The default only_if_agent_owned=true requires the owner_id returned by open_new_tab and verifies the current lifecycle generation before closing, so pre-existing user tabs and another agent's tabs are refused. If the user already closed an owned tab, cleanup returns status=already_gone, closed_by=user without reusing its native id. An actual owned close returns closed_by=agent; an explicit unowned/operator override returns closed_by=none so it is not counted as task-owned cleanup. If already_gone is returned but a page with the same work is still visible, call list_all_tabs and verify URL/title before deciding whether a new session/generation should be closed; BTAP never auto-transfers ownership by URL. A Chrome tabs.onReplaced identity mapping is safe and also migrates the ownership claim. Set only_if_agent_owned=false only when the operator explicitly asked to close an unowned/user tab.
  • tab_id, session_id (optional browser constraint), owner_id (required by the safe default), only_if_agent_owned (boolean, default true)

• scan_page — read the page as simplified HTML or text. Returns links mapping each #rN ref in the content to its absolute URL, and offscreen + hint when content was left outside the viewport. A background tab may report viewport height zero; ordinary DOM/text/API work still continues there, and only visual/layout fidelity requires explicit activate_tab. When the page can be probed, render_state/content_ready distinguish real content from a loading, hydrating, or shell-only SPA; retry or use wait_for before treating an empty shell as final content. cutlist (on by default) collapses long repeated lists and reports a CSS selector for each container it collapsed, derived from that container's own structure. The built-in scan does not write page attributes, ids, or window globals. Optional extra_js runs caller code and can modify the page or send requests.

  • session_id (string, optional), text_only (boolean, optional): default false, cutlist (boolean, optional): default true; collapse repetitive lists, maxchars (integer, optional): default 35000, instruction (string, optional), extra_js (string, optional), timeout (number, optional): default 15, frame (array, optional): non-empty path of CSS strings or structured frame locators, max_targets (integer, optional): default 80, range 0–200 observation.targets adds current locators, control names, editability, rectangles and recommended_tool with a reason. Pass a returned locator unchanged as the page_click / page_type selector; re-observe after page changes. observation.frames lists uninspected child documents: pass an entry's frame back to scan_page to inspect it, including cross-origin/OOPIF frames. Open shadow roots are included; this is a bounded DOM observation, not a complete accessibility tree. max_targets caps controls and frame entries together, separately from the content budget; 0 disables enumeration and truncated=true means more targets or DOM nodes remain uninspected. Rectangles use the observed document's viewport CSS pixels and are not hit-tested. verify_coordinate_target recommends a screenshot to verify a canvas or zero-size target, not an automatic coordinate click. Disabled, inert and readonly controls have no recommended input tool; native selects report select_existing_option. Only top-document file inputs outside shadow roots recommend upload_files, using selector=locator.css; frame/shadow file uploads report unsupported. Frame scans reject extra_js and omit the parent's readiness probe; top-document extra_js preserves its execution semantics and reports target metadata unavailable. The optional built-in readiness probe releases its tab reservation on timeout. Missing render fields mean readiness is unknown; use wait_for for the intended control.

• wait_for — wait until a condition holds, then return. Use this instead of polling scan_page, which re-serializes the whole DOM each time. The server schedules short synchronous page checks under one deadline, avoiding background-page timer throttling. Exactly one condition is required. selector accepts legacy CSS or the structured locator object described under background page input. Caller-provided js is evaluated repeatedly and can have side effects; use a read-only predicate. A timeout with operation_id retains a pending check. Timed-out selector/text/URL probes can release the tab without discarding that receipt: reservation_held=false permits another command, and get_execute_js_result in the same MCP session can collect the delayed reply. Caller-provided js stays reserved. When reservation_held is true or unknown, keep querying the original operation until it settles or releases its reservation. A pending probe is never replayed.

  • selector (string/object, optional): CSS or structured locator, text (string, optional): substring of body text, url_pattern (string, optional): regex on the URL, js (string, optional): expression to become truthy, gone (boolean, optional): wait for the condition to stop holding; default false, timeout (number, optional): default 15, session_id (string, optional)

• wait_for_url — wait for navigation to settle: blocks until the tab URL matches url_pattern (regex, or plain substring — both are tried) and, unless wait_ready=false, document.readyState is complete; then returns final url, title and ready_state. Use after a click or open_url that navigates; wait_for(url_pattern=...) only checks the URL and can return while the new document is still blank. Uses the same bounded synchronous checks and receipt recovery as wait_for. A pending probe with reservation_held=false no longer blocks the tab; its delayed reply remains available through get_execute_js_result in the same MCP session.

  • url_pattern (string): regex or substring to match against the URL, timeout (number, optional): default 15, wait_ready (boolean, optional): require readyState === 'complete', default true, session_id (string, optional)

• scroll_page — scroll and report the new position, so a long page can be read in passes.

  • to (string, optional): default bottom; also accepts top, a pixel offset, or a CSS selector to bring into view, session_id (string, optional), timeout (number, optional): default 15

• execute_js — run JavaScript in the page and return the result. timeout is one end-to-end deadline covering dialog-policy setup, monitor snapshots, delivery/retry, navigation inspection, and cleanup; an explicit session_id is forwarded through every one of those roundtrips instead of relying on the process default. Set wait=false for a genuinely long task: once the extension acknowledges delivery, BTAP returns status="in_progress" plus an operation_id; claim the result with get_execute_js_result instead of replaying the script. dialog_policy="manual" is intentionally unavailable in background mode. When a script navigates the page, status is navigated (not success) with landed_url; the script's return value is genuinely lost in that case and is reported as such rather than substituted. dialog_policy decides what happens if the script opens alert/confirm/prompt: dismiss (default) and accept answer it and report it under dialogs, while manual pauses a synchronous script with the native dialog still open and returns blocked_by_dialog — call handle_dialog to release it. A tab already holding a manual pause returns busy immediately. Use wait_for/wait_for_url instead of delayed setTimeout or sleep Promises when waiting for page state. When the JSON-encoded js_return exceeds the 24 KiB UTF-8 inline limit, BTAP writes the complete value to a private temporary JSON file and returns result_file, result_bytes, result_sha256, and result_format instead of a truncated inline value.

  • A Cannot access contents of the page error must be classified before retrying: if the script attempted window.open or navigation, use open_new_tab (Chrome may block it without a user gesture); if injection into the current tab is forbidden, choose a normal scriptable http/https tab or the supported CDP route. Do not treat the message as proof that reading the current page failed.
  • timeout does not cancel dispatched JavaScript. See Troubleshooting for timeout recovery and frame-preparation errors.
  • script (string), session_id (string, optional), no_monitor (boolean, optional): default false, timeout (number, optional): default 15, dialog_policy (string, optional): dismiss (default), accept, or manual, wait (boolean, optional): default true
  • All routes use the same result conversion: undefined and non-finite numbers become null; BigInt/symbol become strings; DOM, Error and function values become readable representations. Cycles and depth 6 have markers; iterables keep up to 200 items plus a truncation marker. A result_file preserves the complete converted value, including those markers.
  • Once user code starts, a script error does not trigger a second execution. Use an explicit return in a complex async body, preferably (async () => { /* work */ return value; })(). Ambiguous bodies may complete with null; await(expr) can parse as a call to an ordinary function named await, so use the async IIFE when that distinction matters.
  • Unpaired UTF-16 values or keys use the same file export at any size, with result_file_scope="js-value". If writing fails, result_json preserves the complete value with result_json_scope="js-value"; see Complete JSON results for decoding and receipt semantics.

• get_execute_js_result — read or briefly wait for an operation_id, from the same MCP session that submitted it. Accepts handles from execute_js and other timed-out bridge commands. Querying never replays the operation. A completed result can be read repeatedly, including after a lost query response; pending, unknown/expired, and foreign handles return explicit statuses or errors. After reservation expiry, the first valid late terminal reply is retained as late_result (success and data), with late_reply_age in seconds. The original unknown receipt and retry_safe=false remain; the late reply neither restores the reservation nor renews retention. Results are retained for up to 10 minutes, with at most 512 completed operation records; capacity pressure can evict them earlier. A missing result does not prove the operation was never executed. Large successful values use the same lossless result_file metadata as execute_js; for a late value, that metadata is inside late_result and its data becomes null. Accepts the nested reconciliation.bridge_operation.operation_id from a failed open_new_tab status probe. A known read-only wait, inventory or creation-status probe may release its reservation on timeout while retaining its receipt. Check reservation_held; it describes that probe, not the outcome of the tab creation.

  • operation_id (string), timeout (number, optional): default 0, range 0–120

• handle_dialog — inspect or answer a dialog left open on a tab. action="manual" reports it without choosing (blocked_by_dialog, or no_dialog if nothing is open); accept/dismiss answer it and release any paused execute_js or open_url. prompt_text supplies the text for an accepted prompt.

  • action (string), prompt_text (string, optional), session_id (string, optional), timeout (number, optional): default 3, capped at three seconds

• resolve_leave_dialog — for an already-open shell/ttyd/IDE leave prompt: two protocol accepts, then physical Enter only when lab permits it.

  • session_id (string, optional)

• upload_files — set files on a file input, which JavaScript cannot do (input.files is read-only). Runs as one CDP batch so the DOM node ids stay valid across the sequence.

  • selector (string): the <input type=file>, paths (string or array of strings): absolute local paths, session_id (string, optional), timeout (number, optional): default 30

• get_cookies — read cookies for a page.

  • session_id (string, optional), tab_id (integer, optional)

• set_cookies — write cookies into the real browser profile. Takes one cookie object or a list (JSON text is accepted): name is required, plus optional value/url/domain/path/expires (Unix seconds)/httpOnly/secure/sameSite. Uses CDP Network.setCookie, so HttpOnly and cross-path cookies work; falls back to document.cookie only when CDP is unavailable, and then reports which cookies could not carry HttpOnly. Cookies with neither url nor domain are scoped to the current page.

  • cookies (string or list or dict), session_id (string, optional), tab_id (integer, optional), timeout (number, optional): default 20

• delete_cookies — delete a cookie by name. Uses CDP Network.deleteCookies, falling back to expiring it via document.cookie. Scope with domain/path, or url to target one site.

  • name (string), domain (string, optional), path (string, optional), url (string, optional), session_id (string, optional), tab_id (integer, optional), timeout (number, optional): default 20

• storage_get — read localStorage or sessionStorage. Omit key to page with offset/max_items/max_bytes; returns next_offset and truncated. The default timeout is 30s and a failed call does not close the MCP session.

  • key (string, optional), area (string, optional): local (default) or session, session_id (string, optional), timeout (number, optional): default 30, offset (integer, optional), max_items (integer, optional), max_bytes (integer, optional)

• storage_set — write one localStorage/sessionStorage value (non-string values are JSON-encoded first). Verifies by read-back, so a quota-full or privacy-mode failure is reported instead of silently lost.

  • key (string), value (string), area (string, optional): local (default) or session, session_id (string, optional), timeout (number, optional): default 30

Role locators exclude hidden, aria-hidden, and inert controls, including inactive forms retained by SPAs. A visible disabled control can satisfy a query; CSS queries retain DOM-presence semantics. Multiple visible role matches still return ambiguous.

page_click, page_type, and wait_for accept nested same-origin and cross-origin iframe paths, including frames in a separate renderer (OOPIF):

control = {"frame": ["#outer", "#inner"], "css": "#control"}
wait_for(selector=control, session_id=session_id)
page_type("example", selector=control, clear=True, session_id=session_id)
page_click(selector={"frame": ["#outer", "#inner"], "role": "button", "name": "Search"}, session_id=session_id)

Each call binds the actual frame documents and elements. Navigation or replacement after binding returns stale_frame; a later, independent call can locate the new document. Check input_dispatched before recovery: a partial sequence or unknown result must not be replayed. An iframe wait with an outstanding operation_id can retain its reservation; collect that result first. Old extension builds return stale_extension with next_action=reload_extension.

Trusted CDP input events delivered to one named tab. They do not activate the tab, focus its window, or move the desktop cursor — every reply carries foreground_changed: false and input_mode: "cdp". All coordinates are viewport CSS pixels (relative to the top-left of the page area, the space getBoundingClientRect reports), never desktop pixels and never the device pixels capture_page_screenshot returns.

Pass session_id explicitly: the call holds that target in its own context without changing this MCP process's default. A stale handle without evidence of a same-tab replacement is refused. Another MCP call using the same tab can return target_busy; see the concurrent-task boundaries above.

selector remains backward-compatible with CSS strings and also accepts a locator object with exactly one primary key: css, role (optional name), text, or label. Inside a locator object, selector is a compatibility alias for css. exact applies to role/name or text matching; frame walks iframe locators across origin and renderer boundaries; shadow walks open Shadow DOM hosts. A click-only frame-relative point can use {"frame": [...], "x": 20, "y": 30}; its CSS coordinates in the final frame's viewport are converted to top-document coordinates before dispatch. Zero matches return not_found, multiple matches return ambiguous, and closed shadow roots remain inaccessible. Framed clicks refuse non-identity transforms, zoom or perspective on the frame or its ancestors with unsupported_frame_transform; query/type paths remain available.

• page_click — click a CSS/structured selector or viewport coordinates. Exactly one targeting mode: either selector, or both x and y. With a selector, each omitted offset axis uses the element centre; a supplied offset_x or offset_y is measured from the element's top-left corner. {"frame": [...], "x": 20, "y": 30} names a point in the final iframe, converted to top-document CSS coordinates. Point mode is not hit-tested. Missing, ambiguous, non-interactable, closed-shadow, and unsupported transformed-frame targets dispatch no input. Selector mode checks the element and every parent frame for obstruction before dispatch: an overlay returns obscured with occluded_by, and an off-screen point returns outside_viewport. Top-document targets can be scrolled into view (scrolled_into_view); framed clicks do not scroll automatically. A verified click carries hit_verified: true. Screenshot coordinates are device pixels: divide by devicePixelRatio before using them as CSS coordinates. Challenge replies keep the bounded challenge_detected/attempts/challenge_stalled behavior.
  • selector (string/object, optional), x (number, optional), y (number, optional), offset_x (number, optional), offset_y (number, optional), button (string, optional): default left, clicks (integer, optional): default 1, session_id (string, optional), timeout (number, optional): default 15
• page_type — insert text into a CSS/structured-locator field, or into whatever already has focus when selector is omitted. Xterm.js containers/descendants retarget to .xterm-helper-textarea. Missing, ambiguous, read-only, or otherwise unusable targets return a structured status without dispatching text or keys; invalid legacy CSS returns status="invalid_selector" instead of a raw SyntaxError. Successful and failed target resolution includes a redacted active_element descriptor and focus_confirmed when focus was attempted, so omitted-selector input is auditable. clear=true selects the existing value first; submit_key sends one key afterwards.
  • text (string), selector (string/object, optional), clear (boolean, optional): default false, submit_key (string, optional), session_id (string, optional), timeout (number, optional): default 15
• page_press — press a key or a comma-separated modifier chord in the tab, e.g. enter or ctrl,shift,k.
  • keys_csv (string), session_id (string, optional), timeout (number, optional): default 15
• page_drag — drag between two viewport points as one uninterrupted event sequence.
  • x1 (number), y1 (number), x2 (number), y2 (number), duration (number, optional): default 0.3, button (string, optional): default left, session_id (string, optional), timeout (number, optional): default 15

Temporary, origin-scoped permission leases backed by chrome.contentSettings. Every lease records the prior setting and attempts restoration on expiry, explicit reset, and a service-worker or browser restart. Unsupported restoration retains manual_recovery with the prior setting and stops automatic retries.

• set_site_permission — set one permission for one origin, for 60–600 seconds. Supported: notifications, geolocation (or location), camera, microphone. setting is allow, block, or ask. In safe, every allow requires approval; default lab applies it without elicitation (BROWSERTAP_LAB_NO_ELICIT=1 semantics). Declining returns requires_user_action and changes nothing. clipboard returns unsupported, because its exact prior state cannot be restored. Omit origin to use the target tab's current origin; only http/https origins are accepted. If an established lease loses restoration support, manual_recovery retains its prior setting and recovery guidance and stops automatic retries.
  • permission (string), setting (string): allow, block, or ask, origin (string, optional): defaults to the tab's origin, duration_seconds (integer, optional): 60–600, default 300, session_id (string, optional)
• reset_site_permissions — attempt to restore matching leases now, including manual_recovery records. Omit both origin and permission to reset every lease on that browser. Unsupported restoration preserves the prior setting and recovery guidance and stops automatic retries; resolve the cause before another explicit reset.
  • origin (string, optional), permission (string, optional), session_id (string, optional)

• cdp_command — send one CDP command to the selected tab or explicit debuggee. Listed high-risk methods return raw_cdp_blocked before dispatch; params must be a JSON object. Other allowed methods can still change page or profile state. See the raw CDP policy above.
  • method (string): e.g. Page.navigate, params_json (string, optional): JSON object as text, session_id (string, optional), tab_id (integer/string, optional), extension_id (string, optional), target_id (string, optional), timeout (number, optional): default 20
• cdp_batch — send a batch; batch_json must be a JSON object with cmd: "batch" and a commands array of cdp, tabs, or cookies objects. The whole batch passes the raw CDP policy before its first member runs; nested/unknown commands are rejected.
  • batch_json (string), session_id (string, optional)
• debugger_targets — (no tab needed) list every CDP-attachable target, including service workers and extension background pages that list_tabs never shows.
  • session_id (string, optional)
• save_pdf — bounded Page.printToPDF; validates PDF bytes and atomically writes save_path. save_path is relative and resolves under ~/Downloads/browsertap; an absolute path or a .. escape is rejected with ValueError. A timeout forcibly releases its debugger lease.
  • save_path (string), session_id (string, optional), landscape (boolean, optional): default false, print_background (boolean, optional): default true, prefer_css_page_size (boolean, optional): default true, scale (number, optional): default 1.0, range 0.1–2.0, page_ranges (string, optional), timeout (number, optional): default 30

On driving other extensions: Chrome refuses cross-extension debugging at attach time, and all three addressing forms (tab_id, extension_id, target_id) are rejected alike unless Chrome was started with --silent-debugger-extension-api. These parameters are for this extension's own targets and for diagnosis.

• extension_path — absolute path of the unpacked extension, for manual install. No parameters.
• list_extensions — (no tab needed) installed extensions with id, name, enabled state, type, and version.
  • session_id (string, optional)
• set_extension_enabled — (no tab needed) enable or disable an installed extension. Chrome exposes no API to install one, so this only toggles what is already there.
  • extension_id (string), enabled (boolean), session_id (string, optional)
• uninstall_extension — (no tab needed) request removal of another extension. Confirmation defaults on; set it off only for an explicitly selected disposable/test extension. Chrome can refuse either setting because a user gesture is required; changing the flag does not supply that gesture. BTAP cannot uninstall itself through its active response channel.
  • extension_id (string), show_confirm_dialog (boolean, optional): default true, session_id (string, optional)
• get_bookmarks — (no tab needed) read the bookmark tree.
  • session_id (string, optional)
• create_bookmark — (no tab needed) create a bookmark or folder.
  • title (string), url (string, optional): omit to create a folder, parent_id (string, optional), session_id (string, optional)
• remove_bookmark — (no tab needed) atomically save the target subtree under bookmark-backups in the local state directory, then remove the bookmark or folder. Returns backup_path and backup_sha256; backup failure prevents deletion. The managed backup subdirectory must be an ordinary directory, not a symlink or reparse point. Limits: 16 MiB per file, 100 files and 64 MiB total; backups older than 30 days or over capacity are removed on the next backup. A lost deletion receipt keeps the backup evidence but requires inspecting the bookmark tree before retrying.
  • bookmark_id (string), recursive (boolean, optional): default false, session_id (string, optional)
• call_extension — (no tab needed) send JSON to another enabled extension; the target must allow BTAP via externally_connectable.
  • extension_id (string), message_json (string): JSON payload as text, session_id (string, optional)

• network_capture_start — start collecting bounded request/response records and optional bodies. Defaults: 500-entry ring and 256 KiB per body.
  • session_id (string, optional), include_bodies (boolean, optional): default true, max_entries (integer, optional): default 500, range 10–2000, max_body_bytes (integer, optional): default 262144, range 1024–2097152, body_timeout (number, optional): default 5, range 0.1–10 seconds, timeout (number, optional): default 10
• network_capture_stop — return the current capture and release its debugger lease; always call it in cleanup. Returned records can be filtered without changing capture bounds or cleanup. url_pattern is compiled by the browser as a JavaScript RegExp; invalid patterns return a structured error and leave the capture running for retry.
  • session_id (string, optional), url_pattern (string, optional): JavaScript RegExp, resource_type (string, optional), status_min/status_max (integer, optional): 100–599, include_response_bodies (boolean, optional): default true, timeout (number, optional): default 10
• console_capture_start — start collecting console.* and uncaught exceptions.
  • session_id (string, optional), max_entries (integer, optional): default 500, range 10–5000, timeout (number, optional): default 10
• get_console_messages — page through or clear the current console buffer. filter='user' retains page MAIN/default-context output and excludes isolated extension/content-script contexts; empty/all preserves the complete buffer.
  • session_id (string, optional), offset (integer, optional): default 0, max_items (integer, optional): default 200, clear (boolean, optional): default false, filter (string, optional): user or all, timeout (number, optional): default 10
• console_capture_stop — return the remaining console messages and release its debugger lease.
  • session_id (string, optional), timeout (number, optional): default 10

• capture_page_screenshot — page capture via CDP with viewport, full_page, or explicit clip modes. PNG, JPEG, and WebP are supported; quality is valid only for JPEG/WebP. Returns text metadata plus attached MCP image content; save_path only adds a disk copy, and it is relative — it resolves under ~/Downloads/browsertap, with absolute paths and .. escapes rejected. Base64 is omitted unless explicitly requested. The metadata names its own units: image_width/image_height parsed from the returned bytes and pixel_space: "device" (CSS × devicePixelRatio), so a point read off the picture is not fed straight to page_click. A header it cannot parse reports null dimensions plus a dimensions_note rather than a guess — size is the byte count, not a dimension.
  • session_id (string, optional), tab_id (integer, optional), format (string, optional): default png, full_page (boolean, optional): default false, clip (object, optional): x,y,width,height, optional scale, quality (integer, optional): 0–100 for JPEG/WebP, save_path (string, optional), return_base64 (boolean, optional): default false, timeout (number, optional): default 20

• inspect_native_file_dialog — inspect the current foreground Windows standard Shell file dialog owned by a registered Chrome or Edge process. Requires [desktop]. Checks owner/process identity, native controls, visibility and Cancel hit targets, then installs a temporary lifetime marker and returns a 15-second ticket. This has a temporary marker side effect and does not activate a window. Unsupported platforms, portable/unregistered browsers, cross-process owners and unrecognized layouts are refused.
  • desktop_opt_in (boolean, optional): default false; must be true to inspect.
• cancel_native_file_dialog — consume a fresh inspection ticket and send one bounded message to that dialog's Cancel button. Requires [desktop] and the current safe/lab physical-approval policy. Rechecks the cross-process lease, observed Windows quiet-input state, held keys/buttons, identity, foreground and hit targets. Returns status="success", cancelled=true only after observing the original window gone. Uncertain delivery or closure returns unknown, retry_safe=false; inspect state before another action. Each opted-in attempt consumes the ticket, including refusals. Both tools report desktop, on_screen and input_quiet diagnostics.
  • ticket (string, required), desktop_opt_in (boolean, optional): default false; must be true to cancel.

For uploads, use upload_files with the page's file input. Native cancellation is an explicit recovery attempt for an already-open supported dialog. Live verification did not obtain a valid ticket for a real Chrome dialog with a cross-process owner, so successful automatic cancellation remains unverified. Do not open a chooser solely to test recovery. Closing its tab may leave the dialog open, and a user's manual closure is not an automated success. safe requires approval; default lab skips elicitation but still requires opt-in. Tickets expire, are limited to eight per MCP process, and clean up their own markers on consumption, expiry, eviction or orderly shutdown. These checks are not an atomic desktop transaction. See native-dialog design.

mouse_move, mouse_click, mouse_drag, type_text, hotkey, pointer_info and capture_desktop_screenshot no longer exist. They drove the whole desktop rather than one tab, so they acted on whatever happened to be on screen. What to call instead:

A failing page_* call is a targeting problem, not a reason to look for a screen-coordinate fallback — re-read the page with scan_page and fix the locator. Browser chrome, extension popups and OS dialogs are outside page-level input. The explicit native-file-dialog tools above cover only the documented Windows inspection/cancellation boundary.

One global-key fallback survives: resolve_leave_dialog may send Enter after its two protocol attempts fail, in lab only; pure probe timeouts do not trigger it. safe returns requires_user_action without sending Enter. Lab skips elicitation by default; when lab approval prompts are enabled, a declined, cancelled or unavailable prompt also prevents input. The physical gate keeps its cross-process lock (contended → busy, returned immediately, never queued), a short quiet window (you touched the mouse or keyboard → input_activity_detected, nothing sent), then raise the target tab, then act. What that window can detect depends on the OS: only Windows exposes a last-input timestamp, and the pointer position is unavailable under Wayland, in a headless container, and on macOS without the accessibility permission. With no signal at all the window still elapses but has nothing to compare, so the result carries an input_quiet block naming the markers it sampled, with enforced: false when there were none — read a pass on such a machine as unverified rather than as an idle desktop. If the tab cannot be confirmed on screen the result is activation_failed and nothing is sent, so a minimised window produces an error rather than an Enter into the wrong place.