@pyrokine/mcp-chrome 2.4.4 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +495 -115
  2. package/README_zh.md +423 -128
  3. package/dist/anti-detection/injection.js +3 -3
  4. package/dist/cdp/client.d.ts +1 -1
  5. package/dist/cdp/client.d.ts.map +1 -1
  6. package/dist/cdp/client.js +18 -7
  7. package/dist/cdp/client.js.map +1 -1
  8. package/dist/cdp/launcher.d.ts +2 -3
  9. package/dist/cdp/launcher.d.ts.map +1 -1
  10. package/dist/cdp/launcher.js +84 -24
  11. package/dist/cdp/launcher.js.map +1 -1
  12. package/dist/core/auto-wait.d.ts +3 -3
  13. package/dist/core/auto-wait.d.ts.map +1 -1
  14. package/dist/core/auto-wait.js +45 -20
  15. package/dist/core/auto-wait.js.map +1 -1
  16. package/dist/core/browser-driver.d.ts +105 -15
  17. package/dist/core/browser-driver.d.ts.map +1 -1
  18. package/dist/core/browser-driver.js.map +1 -1
  19. package/dist/core/errors.d.ts +22 -4
  20. package/dist/core/errors.d.ts.map +1 -1
  21. package/dist/core/errors.js +90 -7
  22. package/dist/core/errors.js.map +1 -1
  23. package/dist/core/locator.d.ts +7 -0
  24. package/dist/core/locator.d.ts.map +1 -1
  25. package/dist/core/locator.js +54 -29
  26. package/dist/core/locator.js.map +1 -1
  27. package/dist/core/os-mouse.d.ts +15 -2
  28. package/dist/core/os-mouse.d.ts.map +1 -1
  29. package/dist/core/os-mouse.js +52 -8
  30. package/dist/core/os-mouse.js.map +1 -1
  31. package/dist/core/session.d.ts +39 -22
  32. package/dist/core/session.d.ts.map +1 -1
  33. package/dist/core/session.js +632 -153
  34. package/dist/core/session.js.map +1 -1
  35. package/dist/core/types.d.ts +2 -0
  36. package/dist/core/types.d.ts.map +1 -1
  37. package/dist/core/types.js.map +1 -1
  38. package/dist/core/unified-session.d.ts +105 -27
  39. package/dist/core/unified-session.d.ts.map +1 -1
  40. package/dist/core/unified-session.js +554 -138
  41. package/dist/core/unified-session.js.map +1 -1
  42. package/dist/core/utils.d.ts +5 -0
  43. package/dist/core/utils.d.ts.map +1 -1
  44. package/dist/core/utils.js +475 -54
  45. package/dist/core/utils.js.map +1 -1
  46. package/dist/extension/bridge.d.ts +49 -39
  47. package/dist/extension/bridge.d.ts.map +1 -1
  48. package/dist/extension/bridge.js +318 -131
  49. package/dist/extension/bridge.js.map +1 -1
  50. package/dist/extension/http-server.d.ts +3 -0
  51. package/dist/extension/http-server.d.ts.map +1 -1
  52. package/dist/extension/http-server.js +28 -2
  53. package/dist/extension/http-server.js.map +1 -1
  54. package/dist/index.js +7 -0
  55. package/dist/index.js.map +1 -1
  56. package/dist/tools/browse.d.ts.map +1 -1
  57. package/dist/tools/browse.js +248 -172
  58. package/dist/tools/browse.js.map +1 -1
  59. package/dist/tools/challenge.d.ts +1 -1
  60. package/dist/tools/challenge.d.ts.map +1 -1
  61. package/dist/tools/challenge.js +86 -51
  62. package/dist/tools/challenge.js.map +1 -1
  63. package/dist/tools/cookies.d.ts.map +1 -1
  64. package/dist/tools/cookies.js +5 -3
  65. package/dist/tools/cookies.js.map +1 -1
  66. package/dist/tools/diagnostics.d.ts +3 -3
  67. package/dist/tools/diagnostics.d.ts.map +1 -1
  68. package/dist/tools/diagnostics.js +13 -12
  69. package/dist/tools/diagnostics.js.map +1 -1
  70. package/dist/tools/evaluate.d.ts.map +1 -1
  71. package/dist/tools/evaluate.js +67 -26
  72. package/dist/tools/evaluate.js.map +1 -1
  73. package/dist/tools/extract.d.ts.map +1 -1
  74. package/dist/tools/extract.js +137 -197
  75. package/dist/tools/extract.js.map +1 -1
  76. package/dist/tools/input.d.ts +1 -1
  77. package/dist/tools/input.d.ts.map +1 -1
  78. package/dist/tools/input.js +445 -197
  79. package/dist/tools/input.js.map +1 -1
  80. package/dist/tools/logs.d.ts.map +1 -1
  81. package/dist/tools/logs.js +5 -5
  82. package/dist/tools/logs.js.map +1 -1
  83. package/dist/tools/manage.d.ts.map +1 -1
  84. package/dist/tools/manage.js +395 -86
  85. package/dist/tools/manage.js.map +1 -1
  86. package/dist/tools/page-context.d.ts +17 -0
  87. package/dist/tools/page-context.d.ts.map +1 -0
  88. package/dist/tools/page-context.js +103 -0
  89. package/dist/tools/page-context.js.map +1 -0
  90. package/dist/tools/png.d.ts +5 -0
  91. package/dist/tools/png.d.ts.map +1 -1
  92. package/dist/tools/png.js +84 -19
  93. package/dist/tools/png.js.map +1 -1
  94. package/dist/tools/post-condition.d.ts.map +1 -1
  95. package/dist/tools/post-condition.js +24 -7
  96. package/dist/tools/post-condition.js.map +1 -1
  97. package/dist/tools/schema.d.ts +9 -0
  98. package/dist/tools/schema.d.ts.map +1 -1
  99. package/dist/tools/schema.js +15 -0
  100. package/dist/tools/schema.js.map +1 -1
  101. package/dist/tools/target-diagnostics.d.ts +9 -1
  102. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  103. package/dist/tools/target-diagnostics.js +89 -33
  104. package/dist/tools/target-diagnostics.js.map +1 -1
  105. package/dist/tools/wait.d.ts.map +1 -1
  106. package/dist/tools/wait.js +38 -32
  107. package/dist/tools/wait.js.map +1 -1
  108. package/extension/dist/assets/content.ts-loader-DUWbDHRS.js +13 -0
  109. package/extension/dist/assets/content.ts-qe6IB5DK.js +13 -0
  110. package/extension/dist/assets/{index.ts-Bqcu2qiN.js → index.ts-D7_LCUoV.js} +2477 -2201
  111. package/extension/dist/assets/page-scripts-D508WLkW.js +1378 -0
  112. package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-B-eVq48O.js} +54 -5
  113. package/extension/dist/manifest.json +4 -3
  114. package/extension/dist/service-worker-loader.js +1 -1
  115. package/extension/dist/src/popup/popup.html +11 -1
  116. package/package.json +16 -8
  117. package/scripts/start-chrome.ps1 +58 -0
  118. package/extension/dist/assets/content.ts-Cj_iiU2s.js +0 -25
package/README.md CHANGED
@@ -13,7 +13,8 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
13
13
 
14
14
  - **Dual Mode**: Extension mode shares your login sessions; CDP mode for headless/isolated scenarios
15
15
  - **8 Unified Tools**: Action-based design covering browse, input, extract, wait, evaluate, manage, cookies, logs
16
- - **Multi-Tab Parallel**: `tabId` parameter enables operations on any tab without switching focus
16
+ - **Multi-Page Targeting**: `targetId` selects a page in either backend without changing browser focus; `tabId` remains
17
+ an alias
17
18
  - **iframe Penetration**: `frame` parameter targets elements inside iframes (CSS selector or index, Extension mode)
18
19
  - **Semantic Targeting**: 11 ways to locate elements (role, text, label, CSS, CSS+text combo, XPath, coordinates, etc.)
19
20
  - **Auto-Wait**: Built-in clickability and input-ready detection with deadline-based timeout budget
@@ -24,6 +25,40 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
24
25
  - **Anti-Detection**: Optional fingerprint masking and behavior simulation
25
26
  - **Structured Errors**: Every error includes code, message, suggestion, and context
26
27
 
28
+ ## Migrating to 3.0
29
+
30
+ - `manage(action="closePage")` now requires an explicit `targetId`; it no longer closes an implicit default page.
31
+ - In Extension mode, explicit `adoptPage` grants an existing tab the same managed reading, input, script, screenshot,
32
+ debugger, and log capabilities as a newly created page. No popup read grant is required for managed pages.
33
+ - A single-page ordinary-read grant covers text, HTML, attributes, computed styles and state. It does not enable
34
+ arbitrary JavaScript, CDP/debugger commands, input or screenshots.
35
+ - `tmp:` files belong to the current MCP server session. After a restart, regenerate them or retain needed files under
36
+ `cwd:` before stopping the server.
37
+
38
+ Local zero-config auto-connect is unchanged. Reloading the Extension or restarting the MCP client does not require a
39
+ manual Connect click.
40
+
41
+ ## Request scope and failure handling
42
+
43
+ An input sequence keeps its selected backend and page until the sequence and target restoration finish. Concurrent
44
+ `browse(action="connect")` waits for that scope. A CDP request with `frame` returns a capability error before resolving
45
+ or operating on an Extension page. Extension frame resolution checks the selected document and probes the native iframe
46
+ owner, so reordering same-URL frames cannot redirect execution by a stale DOM index.
47
+
48
+ Explicit `wait="networkidle"` enables Network observation before navigation and waits for requests to finish followed by
49
+ 500 ms of quiet. Missing or interrupted observation returns an error; the default `load` path does not attach a debugger
50
+ for network-idle tracking. CDP network logs retain the HTTP status when a response body fails and record one terminal
51
+ entry per request. Temporary CDP page selection preserves separate log buffers for each target.
52
+
53
+ Input `timeout` includes page selection, preparation and key RPCs. An acknowledgement that arrives after the deadline
54
+ cannot produce success; uncertain execution is reported as `actionStatus="unknown"` with `retryable=false`. Read the
55
+ current page state before deciding the next action.
56
+
57
+ Group operations serialize with page release and recheck membership and managed authority while holding the affected
58
+ page locks. For page creation, use `active`; `activate` is accepted only by `movePage`. Popup settings report failed
59
+ storage writes, and delayed stored values cannot override a newer setting. Default local auto-connect remains enabled
60
+ without a manual pairing or connection step.
61
+
27
62
  ## Compatible Clients
28
63
 
29
64
  | Client | Status |
@@ -63,6 +98,21 @@ claude mcp add chrome -- node "$PWD/dist/index.js"
63
98
 
64
99
  For Extension mode, load `extension/dist` in Chrome.
65
100
 
101
+ ### Windows CDP launch
102
+
103
+ Chrome discovery checks Windows App Paths, `PATH`, installed Chrome channels, Chromium, Chrome for Testing, and
104
+ `MCP_CHROME_PORTABLE_DIR` (or `%USERPROFILE%\\.mcp-chrome\\portable`). To start a separate CDP browser from PowerShell:
105
+
106
+ ```powershell
107
+ & '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
108
+ # Or specify a portable executable and profile explicitly:
109
+ & '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222 -ExecutablePath 'C:\Browsers\chrome.exe' -ProfileDir 'C:\Temp\mcp-chrome-profile'
110
+ ```
111
+
112
+ Then call `browse(action="connect", port=9222)`. The script keeps its Chrome process in the foreground; Chrome exit
113
+ codes are reported by the script. Use a separate profile so an existing Chrome process cannot silently absorb the
114
+ launch.
115
+
66
116
  ## Quick Start
67
117
 
68
118
  ### Mode 1: Extension Mode (Recommended)
@@ -125,7 +175,8 @@ MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
125
175
  ```
126
176
 
127
177
  To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server
128
- and disable "Allow no-token local connection" in the Extension popup.
178
+ and disable "Allow no-token local connection" in the Extension popup. Disabling that policy immediately cancels pending
179
+ health checks, WebSocket handshakes, and scheduled reconnects, so an older no-token attempt cannot connect afterward.
129
180
 
130
181
  ### Mode 2: CDP Mode (Fallback)
131
182
 
@@ -164,41 +215,155 @@ browse(action="open", url="https://example.com")
164
215
  | `close` | Close the page specified by `targetId` |
165
216
 
166
217
  Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
167
- (whether tab is controlled by MCP Chrome), `isActive` (whether it's the current operation target), `windowId`, `index`,
218
+ (whether the tab is controlled by MCP Chrome), `isActive` (Chrome's active tab within its window), `windowId`, `index`,
168
219
  `pinned`, `incognito`, and `status` (`loading`/`complete`). The tree includes `windowCount`, `focusedWindowId`,
169
- `activeTargetId`, and each window's ordered `tabs` list, so callers can distinguish the active tab inside each window
170
- from the page currently visible in the focused window. `open` auto-creates tab group (cyan color). `open`, `back`,
220
+ `activeTargetId`, and each window's ordered `tabs` list. `defaultTargetId` identifies the selected operation target; CDP
221
+ does not infer Chrome's foreground tab from this selection. `open` auto-creates tab group (cyan color). `open`, `back`,
171
222
  `forward`, and `refresh` accept `diagnostics=true` to return new console warnings/errors and failed network requests
172
- observed during the action, including the first `open` that creates a page automatically. `close` requires `targetId`
173
- and closes only that page. It never closes the entire CDP connection.
223
+ observed during the action, including the first `open` that creates a page automatically. `open` and `refresh` honor
224
+ `wait="load"`, `wait="domcontentloaded"`, and `wait="networkidle"` in both drivers. The wait is registered before the
225
+ command and bound to the new main document, so late lifecycle events from an earlier navigation are ignored. CDP
226
+ `networkidle` waits for the current main-frame loader's `networkIdle` event. Extension `networkidle` waits for the
227
+ current document to complete, all tracked response bodies to finish, and a 500 ms quiet period. Lost request tracking
228
+ causes a timeout instead of a false idle result. `close` requires `targetId` and closes only that page. It never closes
229
+ the entire CDP connection.
230
+
231
+ In Extension mode, `back` and `forward` use native browser history first. Only a native no-history error permits a
232
+ script fallback, and only on a scriptable document; restricted URLs and browser error pages are not injected. With no
233
+ available history they return `navigated=false`. Other native failures are preserved. A destroyed execution context or a
234
+ browser refusing injection into an error page still returns an operation failure, recorded as a warning in the Extension
235
+ rather than a program error. Arbitrary debugger commands are never automatically replayed.
236
+
237
+ For `open`, `back`, `forward`, and `refresh`, `timeout` starts at request entry. Target preparation, queueing, protocol
238
+ calls, page loading, Challenge inspection and clicks, diagnostics, and target restoration share the remaining budget;
239
+ navigation RPCs do not add transport time. An expired queued action is not dispatched, and later requests still wait for
240
+ an earlier in-flight action to settle. Explicit `timeout=0` rejects before navigation dispatch. Page creation retains
241
+ its separate load-wait and transport-time contract.
242
+
243
+ A timeout does not undo a Chrome operation already dispatched. When its result is unknown, the response reports
244
+ `TIMEOUT`, `actionExecuted="unknown"`, `actionStatus="unknown"`, and `retryable=false`; read the actual page state
245
+ instead of replaying navigation. `pageContext.after` uses a fresh snapshot when available; otherwise it is null with
246
+ `contextError`. Exhausted restoration is reported separately without replacing the primary action result. CDP history
247
+ waits accept a main-frame BFCache restore or same-document event from the current session, not an ordinary frame commit,
248
+ a child-frame event, or an event from another session.
249
+
250
+ Challenge click, detach, and inspection RPCs carry the remaining deadline and reject dispatch after queueing or page
251
+ validation exhausts it. OS mouse movement and fallback processes use the same deadline. A CDP press that has started
252
+ always attempts release on the original connection and session; release cleanup waits at most one second and never uses
253
+ a newly selected target. Read-only Challenge checks that expire return `CHALLENGE_TIMEOUT` with the known primary action
254
+ status. An uncertain click returns `TIMEOUT` with that primary status, `verificationStatus="unknown"`,
255
+ `verificationActionExecuted`, and `retryable=false`; neither navigation nor the click is automatically replayed.
256
+
257
+ Evaluate retains Challenge result fields on success, action failure, verification mismatch, and output failure.
258
+ `originResponsePending=true` means verification succeeded but the origin server has not responded; it does not mean the
259
+ destination content has loaded.
260
+
261
+ Page tools accept `targetId` in either backend; the older `tabId` alias is still accepted. If both are supplied, they
262
+ must match. An explicit target changes only the operation scope and restores the previous default afterward.
263
+ `browse.close` and `manage.closePage` require an explicit ID. Page responses, including action failures, include
264
+ `pageContext` with the effective target and its source (`explicit`, `default`, `created`, `reused`, or `unconfirmed`),
265
+ before/after URL and revision, default target before/after, and Chrome's active target when Extension reports it.
266
+ `unconfirmed` means a page-creation action failed without returning a created target ID. CDP reports browser activity as
267
+ unavailable rather than treating the selected operation target as foreground.
268
+
269
+ When an older Extension lacks `page_snapshot`, unconditional page actions can still use a fresh page-list URL. Their
270
+ `pageContext.before` and `after` snapshots report `revision=null` with a `warning` about the unavailable revision and
271
+ atomic conditions. Requests with `expectedUrl` or `expectedRevision` return `DRIVER_CAPABILITY_ERROR`,
272
+ `actionExecuted=false`, and `actionStatus="not_started"` before dispatch; update the Extension to use these conditions.
273
+ Evaluate and input retain `failureStage="precondition"`, with matching top-level and error-context status and no script
274
+ or input events dispatched. Other snapshot errors still stop the action, and compatibility reads share the original
275
+ timeout budget.
276
+
277
+ In Extension mode, a page snapshot that reports the requested tab is missing returns `TARGET_NOT_FOUND` with
278
+ `context.targetId` and the original `context.nativeMessage`. Input rejected before dispatch retains `eventsExecuted=0`
279
+ and `actionExecuted=false`. The failed request is not redirected to another page or replayed. User-script exceptions
280
+ with the same text are not classified as missing pages.
281
+
282
+ Creation failures retain `error.context.createdTargetId`, window ID, actual `managed`, `actionExecuted`,
283
+ `actionStatus="partial"` and `failureStage` when Chrome has returned the identity. If an RPC response is unknown,
284
+ `actionStatus` and `actionExecuted` are `"unknown"`; `pageContext.targetId` is null unless the created identity is
285
+ known, never the previous default page. Failed creation is not automatically repeated or undone.
286
+
287
+ Temporary target restoration is reported separately in `pageContext.targetRestoration`: `restored` selects the previous
288
+ default, `cleared` leaves no default when none existed, `previous_target_closed` clears a closed default, and `failed`
289
+ reports restoration or cleanup errors while clearing the temporary selection. `error` and `cleanupError` retain the
290
+ respective failure messages. The primary action result or original error is preserved; completed input is not replayed
291
+ or reported as unexecuted. `browse attach` and `manage adoptPage` keep their persistent-default behavior. Concurrent
292
+ page responses describe the page actually used by each action.
293
+
294
+ `browse.list` returns each page's revision and metadata. Revisions combine a backend epoch with a per-page counter.
295
+ Extension counts main-frame navigations and MCP actions; CDP counts observed navigation for the attached page and
296
+ conservatively counts sent mutating commands, including evaluations. Neither driver tracks arbitrary DOM changes made by
297
+ the page itself; re-read URL and revision before a conditional action. `browse` navigation/close, `input`, `evaluate`,
298
+ and eligible `manage` page actions accept `expectedUrl` and `expectedRevision`. A mismatch at the backend returns
299
+ `ACTION_PRECONDITION_FAILED` before that page action is sent. A multi-event action checks conditions before its first
300
+ modifying command, not before every event. A failed or timed-out action can still change the revision when it may have
301
+ had partial effects.
302
+
303
+ For `browse`, only `open`, `back`, `forward`, `refresh`, and `close` accept these conditions. Other actions, including
304
+ `attach`, reject them with `INVALID_ARGUMENT` before changing any target.
305
+
306
+ Explicit `manage(action="adoptPage", targetId=...)` makes an existing page fully managed without focusing or navigating
307
+ it. `browse attach` only selects a target. Creation provenance, group membership, and group color do not authorize a
308
+ page. `releasePage` revokes full managed access without closing the tab or changing its window or group; it clears MCP
309
+ log state and removes debugging and console capture resources. If Chrome prevents resource cleanup, the response
310
+ includes `warnings` while managed access is still revoked.
311
+
312
+ Managed access survives a Service Worker restart. Reloading the Extension also restores access to surviving managed
313
+ tabs whose original document identity still matches, without refreshing or adopting them again. Tabs with unavailable
314
+ document identity require explicit `adoptPage` after an Extension reload; ordinary navigation keeps managed access,
315
+ and `releasePage` remains revoked after a restart or reload. A reused tab ID does not authorize a different document.
316
+ A managed tab can keep using this Extension's existing debugger session after a Service Worker restart. Sessions owned
317
+ by other debuggers still return `DEBUGGER_BLOCKED`.
318
+
319
+ Use `manage(action="grantReadAccess", targetId=...)` to grant ordinary reads and `revokeReadAccess` to revoke them; no
320
+ popup click is required. Both require an explicit target and accept `expectedUrl`/`expectedRevision`. Grants belong to
321
+ the calling server instance and the current document identity, URL and revision. Storage failure is an error, not
322
+ successful authorization. The popup remains an optional control. A grant survives a Service Worker restart only while
323
+ that connection and the approved document remain unchanged. Navigation, tab closure, or connection closure revokes it. A
324
+ target ID alone does not authorize reading. The grant covers ordinary content reads, including targeted text, HTML,
325
+ attributes, computed styles, and page state. Scripts, debugger operations, screenshots, input, and cookie access do not
326
+ inherit it; existing cookie operations have separate URL/name filter rules. When page management or navigation is
327
+ refused for lack of managed access, the revision and any valid ordinary-read grant remain unchanged.
328
+ `manage(action="pageMetadata", targetId=...)` reads or updates `taskHint` and `note`, and list results show creation and
329
+ last-use timestamps. Reads and updates accept `expectedUrl`/`expectedRevision`; a mismatch returns
330
+ `ACTION_PRECONDITION_FAILED` without reading or updating notes. This metadata is process-local and is removed when a
331
+ page is closed; it never authorizes content access.
174
332
 
175
333
  ### Access challenges
176
334
 
177
335
  After `open`, `back`, `forward`, `refresh`, `input`, and `evaluate`, MCP Chrome waits for a Cloudflare JS Challenge or
178
- Turnstile checkbox. When Extension mode is active, navigation starts without debugger logging and reads the live tab
179
- title passively for eight seconds. If the interstitial persists, MCP Chrome checks for a visible Turnstile control and
180
- clicks it only when it finds one. Extension inspect uses an isolated world and detaches the debugger first. Same-page
336
+ Turnstile checkbox. When Extension mode is active, navigation starts without debugger logging. While a Challenge title
337
+ persists, MCP Chrome reads the live tab title passively for the first eight seconds. If the interstitial persists, it checks for a visible Turnstile control and
338
+ clicks it only when it finds one. Extension inspect uses an isolated world. Challenge titles detach the debugger before
339
+ inspection; ordinary-page checks retain an existing connection unless a visible verification control or unresolved
340
+ challenge content is found. Same-page
181
341
  fixture buttons use the existing page click. If a Cloudflare Turnstile iframe is present, inspect CSS coordinates are
182
342
  converted to screen coordinates and the OS mouse moves along a path, hovers, then presses and releases: `xdotool` on
183
- Linux uses the focused Chrome window origin plus window chrome insets only when that window title matches the test page,
184
- rather than Chrome `screenX` or `outerHeight - innerHeight`; `cliclick` or System Events on macOS; and PowerShell
343
+ Linux uses the focused Chrome client-window geometry and `xprop` GTK frame extents only when that window title matches
344
+ the test page. Missing tools, invalid geometry, or a viewport mismatch stop the click instead of guessing the content
345
+ origin from Chrome `screenX` or `outerHeight - innerHeight`; `cliclick` or System Events on macOS; and PowerShell
185
346
  `mouse_event` on Windows. Widget clicks target the checkbox on the left of the compact Turnstile card, including when
186
347
  the host wrapper is wider than the card, not the label. If a Cloudflare iframe is already in the DOM, the OS mouse is
187
348
  used even when that iframe reports a zero-size rect, including the later host `Verify you are human` / `请验证您是真人`
188
349
  button. The OS click runs only when the managed test tab is already the active tab in an already-focused window; mixed
189
350
  windows are not focused. Debugger is detached and the viewport is read again before the OS click. Missing OS mouse tools
190
351
  or an unfocused window return a visible error instead of a silent CDP click. A Turnstile widget is clicked only after
191
- two inspections report the same click point. Distant OS-mouse paths start near the control instead of flying across the
192
- screen. The same checkbox or compact widget is clicked at most once; if Cloudflare then shows a visible
193
- `Verify you are human` or `请验证您是真人` button, that button is inspected as `verify` and clicked at most once in the
194
- same wait. Use the default `diagnostics=false` for challenge-protected pages because diagnostics starts debugger console
195
- and network collection.
196
-
197
- Detection covers titles such as `Just a moment...` and `请稍候…`, challenge DOM or body-text markers, and
198
- `Verify you are human` / `请验证您是真人` controls. CDP reads live titles with `Target.getTargetInfo`. A leftover
199
- Cloudflare iframe on a recovered page is not pending. Cached titles do not decide the result. MCP Chrome does not call a
200
- CAPTCHA solver, retry navigation, or export `cf_clearance` values. A CDP timeout does not prove that the site fails in a
201
- user Chrome session; check the returned `mode` before diagnosing the site.
352
+ two inspections report the same click point; unrelated elements do not become widgets just because their sizes match.
353
+ Distant OS-mouse paths start near the control instead of flying across the screen. The same checkbox or compact widget
354
+ is clicked at most once; if Cloudflare then shows a visible `Verify you are human` or `请验证您是真人` button, that
355
+ button is inspected as `verify` and clicked at most once in the same wait. Use the default `diagnostics=false` for
356
+ challenge-protected pages because diagnostics starts debugger console and network collection.
357
+
358
+ Detection covers titles such as `Just a moment...` and `请稍候…`, visible challenge DOM or body-text markers, and
359
+ `Verify you are human` / `请验证您是真人` controls, including visible `button` elements with that exact text. A normal
360
+ title still requires a bounded check of visible content: visible `正在进行安全验证` blocks the action, while hidden
361
+ markers do not. Pages without challenge evidence continue without a fixed eight-second wait. Same-page buttons use
362
+ page input when no Cloudflare iframe is present. CDP reads live titles with `Target.getTargetInfo`. A leftover
363
+ Cloudflare iframe or an old pending header alone does not keep a recovered page pending or trigger scrolling or a
364
+ click. Cached titles do not decide the result. MCP Chrome does not call a CAPTCHA solver, retry navigation, or export
365
+ `cf_clearance` values. A CDP timeout does not prove that the site fails in a user Chrome session; check the returned
366
+ `mode` before diagnosing the site.
202
367
 
203
368
  A resolved challenge returns `challengeResolved=true`, `challengeKind`, `waitedMs`, `clickedTurnstile`, and
204
369
  `clearanceCookiePresent` (name presence only). If the visible page text says verification succeeded and Cloudflare is
@@ -208,7 +373,7 @@ checkbox still counts as pending. Challenge results and errors include `mode`. T
208
373
  `retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is not reported as `js`).
209
374
  Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP reputation checks
210
375
  cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears the header flag;
211
- clearing network logs does not.
376
+ ordinary iframe document responses and clearing network logs do not.
212
377
 
213
378
  ### input - Keyboard & Mouse Input
214
379
 
@@ -236,27 +401,79 @@ Special-case parameters:
236
401
  - `keydown` accepts `commands` (e.g. `["selectAll"]`, `["copy"]`, `["paste"]`, `["cut"]`, `["undo"]`, `["redo"]`) to
237
402
  trigger native browser editing commands. A successful response means the browser accepted the command dispatch; use
238
403
  `postCondition` or `extract` to verify the page result. `commands` is precise-mode only; stealth mode throws because
239
- the CDP commands API has no JS-event equivalent.
404
+ the CDP commands API has no JS-event equivalent. An element or coordinate `target` is focused without mouse events
405
+ before command dispatch. Coordinate focus does not toggle checkboxes, follow links, or invoke click listeners. A
406
+ missing or unfocusable target returns an error before commands are sent. Extension `frame` coordinates are local to
407
+ that frame.
240
408
  - `keydown` on a key already held emits `rawKeyDown` with `autoRepeat: true` (Puppeteer-compatible long-press).
241
409
 
242
410
  `events` must contain at least one event. Parameters: `humanize` enables Bézier curve movement and random delays.
243
411
  `diagnostics=true` returns new console warnings/errors and failed network requests after the action. `postCondition`
244
412
  waits for a page state after the events so callers can distinguish dispatched input from completed page behavior.
245
413
  `postCondition.timeout` defaults to 3000 ms and is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and
246
- accepts 50-5000 ms. `tabId` targets a specific tab. `frame` targets an iframe (CSS selector or index). Both are
247
- Extension-mode only. When either scope is provided, the action, diagnostics, and post-condition use the backend selected
248
- for that target scope.
249
-
250
- **`click`-specific**: `force: true` skips actionability checks (useful for testing or hidden elements). Actionability
251
- failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering element details, candidate blockers, and
252
- suggestions. **`type`-specific**: `mode="controlled"` or `dispatch: true` sets `.value` directly and fires `input`/
253
- `change` events — use for React/Vue controlled inputs where keyboard events don't update state. Requires a
254
- non-coordinate `target`. Extension mode only. Controlled input and target lookup failures return structured context with
255
- `target`, `matchCount`, `nth`, `activeElement`, `selection`, and candidate controls. Password input values are omitted
256
- from failure diagnostics, and input `find` or replacement `text` values are redacted from failed responses. For `select`
257
- and `replace`, event-level `nth` selects the Nth text occurrence while nested `target.nth` selects the Nth matching
258
- element; both are zero-based and may be used together. Locator targets for `select` and `replace` work in CDP mode
259
- without Extension ref IDs.
414
+ accepts 50-5000 ms. A `postCondition.script` may be an expression, function, async function, or Promise expression;
415
+ functions are invoked and the final Promise value is awaited before matching, while thrown or rejected errors fail the
416
+ check. `targetId` (or legacy `tabId`) selects a page in either backend; `frame` selects an iframe (CSS selector or
417
+ index) in Extension mode. When either scope is provided, the action, diagnostics, and post-condition use the backend
418
+ selected for that target scope.
419
+
420
+ If the frame, execution context, or debugger becomes unavailable during verification, the check returns
421
+ `verificationStatus="unavailable"`. A script that throws or rejects, even with the same error text, returns `error`.
422
+ An already completed action keeps `actionStatus="completed"` and `failureStage="verification"`; verification does not
423
+ replay the action.
424
+
425
+ For keyboard `type`, `timeout` includes Challenge waiting, focus preparation, character input, and `delay`/`humanize`
426
+ delays. Extension precise/stealth and CDP use the remaining budget. An explicit budget such as `timeout=45000` allows
427
+ valid input to take longer than the default 30000 ms. When the budget expires, subsequent characters and events stop.
428
+ Already dispatched input cannot be undone, so a timeout may leave partial input. A response with `actionExecuted=true`,
429
+ `actionStatus="unknown"`, and `retryable=false` requires an independent page read to check the actual value; do not
430
+ replay the whole event sequence.
431
+
432
+ Mouse target lookup, stepped movement, and `humanize` delays also share the remaining input budget. Each movement and
433
+ the subsequent click check the deadline; expiry stops further movement and clicking. Already dispatched native events
434
+ cannot be undone. Read the page independently after an unknown result instead of replaying the action.
435
+
436
+ Command focus, text selection, and replacement share the remaining event budget. Expiry stops subsequent actions; Shift
437
+ release is still attempted without hiding an earlier action error. Stepped CDP touch movement also stops at the
438
+ deadline.
439
+
440
+ Stealth left clicks emit `click`, middle clicks emit `auxclick`, and right clicks emit `contextmenu`. Each press/release
441
+ pair carries its click `detail`; only left multiple clicks emit `dblclick` at `detail=2`. Separate stealth `mouseup`
442
+ events follow the same button mapping.
443
+
444
+ In stealth mode, `delay` separates characters; the first character has no initial wait. Background page timer throttling
445
+ can lengthen subsequent intervals, but the same deadline still stops further input.
446
+
447
+ Precise Extension and CDP keyboard input use the current caret and selection. A `target` is clicked before typing and
448
+ can change the insertion point. To append to a contenteditable element, focus it, place the caret at its end, then send
449
+ `type` without a `target` so that it does not click again.
450
+
451
+ CDP clicks and keyboard input also wait for stable element position and size in background pages without activating
452
+ them. Visibility, enabled-state, viewport, and click coverage checks still apply. Target lookup, actionability checks,
453
+ and the final coordinate read share the remaining event budget. If any of these stages exhausts it, no mouse or keyboard
454
+ event is dispatched.
455
+
456
+ **`click`-specific**: `force: true` requires `forceReason` and a non-coordinate element `target`, and skips
457
+ actionability checks (useful for testing or hidden elements), but still dispatches the standard DOM mouse-event sequence
458
+ and does not call framework-private handlers. The same checks apply to middle/right clicks and multiple clicks. Missing
459
+ targets and coordinate targets cannot use `force`. Actionability failures return `ACTIONABILITY_FAILED` with `rect`,
460
+ `clickPoint`, covering element details, candidate blockers, and suggestions. **`type`-specific**: `mode="controlled"` or
461
+ `dispatch: true` sets `.value` directly and fires `input`/ `change` events — use for React/Vue controlled inputs where
462
+ keyboard events don't update state. Requires a non-coordinate `target`. Extension mode only. Controlled input and target
463
+ lookup failures return structured context with `locator`, `matchCount`, `nth`, bounded `candidates`, and an
464
+ `activeElement` summary without input values. The focus summary is `null` when unavailable; a failed DOM query also
465
+ returns `diagnosticError`. Selection-specific errors also report editor and selection state. Password input values are
466
+ omitted from failure diagnostics, and input `find` or replacement `text` values are redacted from failed responses. For
467
+ `select` and `replace`, event-level `nth` selects the Nth text occurrence while nested `target.nth` selects the Nth
468
+ matching element; both are zero-based and may be used together. Locator targets for `select` and `replace` work in CDP
469
+ mode without Extension ref IDs.
470
+
471
+ In both backends, target lookup failures from `input`, `extract`, and `wait` report the failed locator, zero-based `nth`,
472
+ URL, tab/frame scope, managed state, last locator state, and at most 10 candidate summaries within the request budget.
473
+ `matchCount` is the observed total, not the candidate limit; an out-of-range `nth` does not turn 15 matches into zero.
474
+ Unknown counts or managed state are `null`, and unavailable diagnostics include `diagnosticError`. CDP retains
475
+ `ELEMENT_NOT_FOUND` for lookup failures and `TIMEOUT` for element waits, together with existing URL and log fields.
476
+ Diagnostics read the failed target before its scope is restored and never replay input.
260
477
 
261
478
  ### extract - Content Extraction
262
479
 
@@ -270,26 +487,44 @@ without Extension ref IDs.
270
487
  | `state` | Get page state (URL, title, interactive elements) |
271
488
  | `metadata` | Extract page metadata (title, OG, JSON-LD, etc.) |
272
489
 
490
+ Text extraction uses the browser's `innerText` for HTML pages and selected elements. Rendered regions omit nested
491
+ `style`/`script` source and hidden descendants. Explicitly selected non-rendered HTML follows the browser's `innerText`
492
+ rules; SVG/XML nodes use `textContent`. Use `html` for source markup.
493
+
273
494
  Parameters: `output` saves result to file (or directory for `images=data`). `images` (`info`/`data`) extracts image
274
495
  metadata or data alongside HTML. `frameHtml` extracts the current iframe document after `frame` routing. Screenshot
275
496
  accepts `clip` for coordinate-region capture, `compareWith` for PNG baseline comparison, and `diffOutput` for a PNG diff
276
497
  image. `diffOutput` requires `compareWith`. A `target` screenshot that has no match, whose `nth` is out of range, or
277
498
  whose box has zero size returns a target error rather than silently returning a viewport screenshot. Screenshot
278
499
  responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`, `scale`, `clip`, and
279
- `capabilities`. PNG comparison is capped before decode at 25 MiB per PNG and 12,000,000 pixels; use `clip` or `scale`
280
- for larger captures. Hidden Extension tabs return `HIDDEN_TAB_SCREENSHOT` instead of automatically focusing the browser.
281
- If another debugger blocks the precise screenshot path, viewport fallback reports `degraded`, `fallback`, and
282
- `limitations`; unsupported fallback options return structured `SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns
283
- `interactiveElements`; `metadata` returns `frames` in both Extension and CDP modes. `tabId` targets a specific tab.
284
- `frame` targets an iframe. Both Extension mode only.
500
+ `capabilities`. Capture is limited to 16,384 pixels per side, 12,000,000 pixels total, 48 MiB estimated RGBA memory and
501
+ 25 MiB encoded data. PNG baselines are checked before reading; comparison is capped at 25 MiB per PNG and 12,000,000
502
+ pixels, and decompressed scanlines must exactly match the validated dimensions and are bounded during inflate. Malformed
503
+ or expansion-heavy PNGs are rejected. Use `clip` or `scale` for larger captures. Screenshot and diagnostic bundle
504
+ capabilities report `hiddenTabScreenshot: false` in both Extension and CDP modes. Hidden Extension tabs return
505
+ `HIDDEN_TAB_SCREENSHOT` without automatic activation. If another debugger blocks the precise screenshot path, viewport
506
+ fallback reports `degraded`, `fallback`, and `limitations`; unsupported fallback options return structured
507
+ `SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns `interactiveElements`; `metadata` returns `frames` in both
508
+ Extension and CDP modes. The document `url` is returned in both backends; Extension `frame` routing returns that iframe
509
+ document's URL. CDP frame entries retain declared fields as `null` when unavailable, including DOM selectors and owner
510
+ rectangles; frame-tree order and IDs are preserved. Metadata also returns the page's current `managed` state and a
511
+ `metadata` object with `createdBy`, `createdAt`, `lastUsedAt`, `taskHint`, and `note`, matching `browse list` and
512
+ `manage pageMetadata`. These notes describe the page even when `frame` selects an iframe document. They are local to the
513
+ current Server process; unknown creation provenance stays `unknown`, and another Server does not inherit the notes. They
514
+ are not cross-session ownership or permission evidence. Inline and file outputs include the same fields. `managed`
515
+ describes Extension page management; CDP returns false without restricting normal operations through the CDP connection.
516
+ `targetId` (or `tabId`) selects a page in either backend; `frame` is Extension-only.
285
517
 
286
518
  **`attribute` special prefix**: `computed:<property>` returns the computed CSS style value (e.g. `computed:color`,
287
519
  `computed:font-size`). Use `computed:*` to return all computed style properties as JSON (returns 300+ properties — use
288
520
  `output` to save to file).
289
521
 
290
- **`state`-specific**: `depth` controls DOM traversal depth (default 15). Reduce to limit response size on large pages.
291
- `mode` selects the underlying source — `accessibility` (default, derived from the a11y tree) or `domsnapshot` (raw CDP
292
- `DOMSnapshot.captureSnapshot`, CDP-only; returns a flat node array with computed styles for advanced post-processing).
522
+ **`state`-specific**: `depth` controls accessibility-tree traversal depth (default 15). Reduce it to limit response size
523
+ on large pages. `mode` selects `accessibility` (default, derived from the a11y tree) or `domsnapshot` (raw
524
+ `DOMSnapshot.captureSnapshot`, available through CDP or a managed Extension page). DOMSnapshot captures the whole page
525
+ and rejects `target`, `frame`, and `depth` instead of ignoring those limits. Ordinary read grants do not grant debugger
526
+ access. Unavailable sibling iframe probes are listed in metadata as `unavailableFrames` and per-frame
527
+ `unavailableReason`; a uniquely verified selected iframe remains usable.
293
528
 
294
529
  ### wait - Wait for Conditions
295
530
 
@@ -300,7 +535,11 @@ If another debugger blocks the precise screenshot path, viewport fallback report
300
535
  | `time` | Fixed delay |
301
536
  | `idle` | Wait for DOM or network quiet period |
302
537
 
303
- Parameters: `tabId` targets a specific tab. `frame` targets an iframe. Both Extension mode only.
538
+ Parameters: `targetId` (or `tabId`) selects a page in either backend; `frame` selects an iframe in Extension mode.
539
+
540
+ In CDP mode, `visible` requires a nonzero DOM rectangle and CSS that does not hide the element (`display:none` or
541
+ `visibility:hidden/collapse`). `hidden` accepts these hidden states or a missing element; `attached` and `detached` only
542
+ check whether the element exists.
304
543
 
305
544
  **`idle`-specific**: In Extension mode, after `readyState === 'complete'`, it injects a `MutationObserver` and waits for
306
545
  a quiet period with no DOM changes. In CDP mode, it waits for network quiet instead. `ms` controls the relevant quiet
@@ -310,19 +549,19 @@ period (default 500ms). The response returns `idleKind` and `idlePeriodMs`; Exte
310
549
 
311
550
  Execute JavaScript in page context.
312
551
 
313
- | Parameter | Description |
314
- | ------------------- | ----------------------------------------------------------------------- |
315
- | `script` | JavaScript code. Bare `return` statements are wrapped in IIFE |
316
- | `scriptFile` | Read code from a local file instead of `script` |
317
- | `args` | Arguments passed to a script written as a function expression |
318
- | `mode` | `precise` (default, debugger API) or `stealth` (JS injection) |
319
- | `staleContextRetry` | iframe stale-context policy: `never` (default) or `readOnly` |
320
- | `output` | Save the result to a file |
321
- | `tabId` | Target a specific tab (Extension mode) |
322
- | `frame` | Target an iframe by CSS selector or index (Extension mode) |
323
- | `timeout` | End-to-end budget (ms) |
324
- | `diagnostics` | Return new console warnings/errors and failed requests after execution |
325
- | `postCondition` | Wait for text, selector, URL fragment, or script result after execution |
552
+ | Parameter | Description |
553
+ | -------------------- | --------------------------------------------------------------------------------------------------- |
554
+ | `script` | JavaScript code. Bare `return` statements are wrapped in IIFE |
555
+ | `scriptFile` | Read code from a local file instead of `script` |
556
+ | `args` | Function arguments; `[]` invokes a zero-argument function, omission evaluates the script as written |
557
+ | `mode` | `precise` (default, debugger API) or `stealth` (JS injection) |
558
+ | `staleContextRetry` | iframe stale-context policy: `never` (default) or `readOnly` |
559
+ | `output` | Save the result to a file |
560
+ | `targetId` / `tabId` | Select a page in either backend (`tabId` is an alias) |
561
+ | `frame` | Target an iframe by CSS selector or index (Extension mode) |
562
+ | `timeout` | End-to-end budget (ms) |
563
+ | `diagnostics` | Return new console warnings/errors and failed requests after execution |
564
+ | `postCondition` | Wait for text, selector, URL fragment, or script result after execution |
326
565
 
327
566
  `script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
328
567
  paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
@@ -338,41 +577,115 @@ action. `postCondition` is optional; when it is not provided, `success=true` onl
338
577
  returned. When it is provided and does not match before timeout, the tool returns `POST_CONDITION_FAILED` with the last
339
578
  observed checks. Precise iframe evaluation does not replay a script after a stale execution context by default. Set
340
579
  `staleContextRetry="readOnly"` only when the script has no side effects; the Extension may then resolve a new context
341
- and replay it once within the remaining timeout budget. A stale-context error after `Runtime.evaluate` reports
342
- `actionExecuted=true` and `actionStatus="unknown"`, because earlier side effects may already have happened even though
343
- the final result is unavailable.
580
+ and replay it once within the remaining timeout budget. If Chrome still reports the removed document while resolving
581
+ that retry, the Extension waits for the current document within the same budget; this does not add script executions.
582
+ Permission failures stop immediately. A stale-context error after `Runtime.evaluate` reports `actionExecuted=true` and
583
+ `actionStatus="unknown"`, because earlier side effects may already have happened even though the final result is
584
+ unavailable.
585
+
586
+ For object results in the main frame with Extension precise mode, an explicit `output` uses a 16 Mi (16777216) character
587
+ budget. Without `output`, the 1000000-character budget still applies, including automatic saving. Both paths retain the
588
+ depth limit of 8, the 2000-node budget, and non-serializable result rejection. The character budget counts UTF-16 code
589
+ units, not the output file's UTF-8 bytes; `tmp:` files also remain subject to the temporary output quota. Exceeding a
590
+ result limit reports the current limit and the completed script's output failure without replaying it.
344
591
 
345
592
  ### manage - Page & Environment Management
346
593
 
347
- | Action | Description |
348
- | -------------- | ---------------------------------------------------------- |
349
- | `newPage` | Create new controlled page/tab |
350
- | `closePage` | Close controlled page and return `affected.before/after` |
351
- | `adoptPage` | Mark an existing tab as controlled without focusing it |
352
- | `releasePage` | Remove a controlled tab from management without closing it |
353
- | `movePage` | Move a controlled tab to another window or index |
354
- | `reorderPage` | Reorder a controlled tab inside its window |
355
- | `pinPage` | Pin a controlled tab |
356
- | `unpinPage` | Unpin a controlled tab |
357
- | `activatePage` | Activate a controlled tab and focus its window |
358
- | `focusWindow` | Focus an explicit window |
359
- | `resizeWindow` | Resize or change state for an explicit window |
360
- | `newWindow` | Create a new controlled window |
361
- | `closeWindow` | Close a window only when all tabs are managed |
362
- | `clearCache` | Clear cache/storage (use `cookies` tool to clear cookies) |
363
- | `viewport` | Set viewport size |
364
- | `userAgent` | Set User-Agent |
365
- | `emulate` | Device emulation (iPhone, iPad, etc.) |
366
- | `inputMode` | Query or set input mode (`precise` / `stealth`) |
367
- | `stealth` | Inject anti-detection scripts |
368
- | `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
369
-
370
- Tab/window management actions are Extension-mode only. Actions that change visible browser state require explicit
371
- `targetId` or `windowId` and return `affected.before/after`. `clearCache` is unavailable in Extension mode and returns
372
- `UNSUPPORTED_MODE` without clearing anything. Use scoped `cookies(action="clear")` for cookies or CDP mode for storage
373
- and cache. `focusWindow` only returns success after the target window is observed as focused; otherwise it returns
594
+ | Action | Description |
595
+ | ------------------ | ----------------------------------------------------------------- |
596
+ | `newPage` | Create new controlled page/tab |
597
+ | `pageMetadata` | Read or update per-page `taskHint` and `note` |
598
+ | `closePage` | Close controlled page and return `affected.before/after` |
599
+ | `adoptPage` | Grant full controlled-page access without focusing it |
600
+ | `releasePage` | Remove a controlled tab from management without closing it |
601
+ | `grantReadAccess` | Grant ordinary reads for an explicit page to the calling instance |
602
+ | `revokeReadAccess` | Revoke that instance's ordinary read grant |
603
+ | `updatePage` | Update native tab properties and return actual state |
604
+ | `movePage` | Move a controlled tab to another window or index |
605
+ | `reorderPage` | Reorder a controlled tab inside its window |
606
+ | `pinPage` | Pin a controlled tab |
607
+ | `unpinPage` | Unpin a controlled tab |
608
+ | `activatePage` | Activate an explicit page; Extension requires a controlled tab |
609
+ | `focusWindow` | Focus an explicit window |
610
+ | `resizeWindow` | Resize or change state for an explicit window |
611
+ | `newWindow` | Create a new controlled window |
612
+ | `closeWindow` | Close a window only when all tabs are managed |
613
+ | `updateWindow` | Update native window position, state, focus or attention |
614
+ | `groupPages` | Create a group or add controlled tabs to an existing group |
615
+ | `ungroupPages` | Remove controlled tabs from groups without releasing them |
616
+ | `updateGroup` | Update group title, color and collapsed state |
617
+ | `moveGroup` | Move a group and its tabs to a window or index |
618
+ | `clearCache` | Clear cache/storage (use `cookies` tool to clear cookies) |
619
+ | `viewport` | Set viewport size |
620
+ | `userAgent` | Set User-Agent |
621
+ | `emulate` | Device emulation (iPhone, iPad, etc.) |
622
+ | `inputMode` | Query or set input mode (`precise` / `stealth`) |
623
+ | `stealth` | Inject anti-detection scripts |
624
+ | `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
625
+
626
+ Native tab/window/group configuration uses Extension mode; `activatePage` also supports CDP. Mutations identify their
627
+ existing targets with `targetId`, `targetIds`, `windowId`, or `groupId` and return `affected.before/after`. Group
628
+ results also include `tabsBefore/tabsAfter`; `ungroupPages` removes an empty group through Chrome without revoking the
629
+ tabs' managed state. Window display changes and group title/color/collapse updates use the explicit `windowId` or
630
+ `groupId`, including containers with unmanaged members. They do not grant page permissions. Group moves and window
631
+ closure still require every affected member to be managed. Grouping or ungrouping selected pages checks those pages;
632
+ unrelated sibling changes do not invalidate a valid selection. Default page creation reuses a valid cached MCP window
633
+ even when it contains unmanaged tabs. `clearCache` is unavailable in Extension mode and returns `UNSUPPORTED_MODE`
634
+ without clearing anything. Use scoped `cookies(action="clear")` for cookies or CDP mode for storage and cache.
635
+ `focusWindow` only returns success after the target window is observed as focused; otherwise it returns
374
636
  `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with unmanaged tabs and returns
375
- `WINDOW_HAS_UNMANAGED_TABS`.
637
+ `WINDOW_HAS_UNMANAGED_TABS`. Persistent `adoptPage` and `releasePage` target changes are serialized with scoped tab
638
+ operations, so a concurrent multi-event input remains on its requested tab and the persistent target is applied
639
+ afterward.
640
+
641
+ CDP `activatePage` retains the default operation target and reports the fields available from that backend, without
642
+ inventing an `active` value or system-window focus. In Extension mode, `viewport`, `userAgent`, `emulate`, raw `cdp`,
643
+ and precise `evaluate` support controlled `about:blank` pages. Chrome-internal and Extension pages retain their access
644
+ restrictions. Querying `manage(action="emulate")` without `device` returns the local device catalogue without a live
645
+ page; page conditions are rejected for this query. Setting a device continues to validate the selected page and
646
+ conditions.
647
+
648
+ | Action | Native parameters | Behavior |
649
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
650
+ | `newPage` | `url`, `windowId`, `index`, `active`, `pinned`, `openerTabId`, `groupId`, `timeout` | `active` defaults to false; `groupId=-1` disables grouping; explicit placement is not changed by the default visual group |
651
+ | `updatePage` | `url`, `active`, `pinned`, `highlighted`, `muted`, `autoDiscardable`, `openerTabId` | Requires `targetId`; only `active=true` is supported and does not focus the window; `active=false` is rejected before any update |
652
+ | `groupPages` | `targetIds`, `groupId`, `windowId`, `title`, `color`, `collapsed` | Omit `groupId` to create a group in the members' window; mixed-window members require `windowId`; joining an existing group accepts only `targetIds/groupId` |
653
+ | `ungroupPages` | `targetIds` | Removes group membership and retains controlled-page access |
654
+ | `updateGroup` | `groupId`, `title`, `color`, `collapsed` | An empty title and false collapsed value are applied as supplied |
655
+ | `moveGroup` | `groupId`, `windowId`, `index` | Moves all members; `index=-1` means the end of the window |
656
+ | `newWindow` | `url` or `urls`, `targetId`, `windowType`, `focused`, `incognito`, `left`, `top`, `width`, `height`, `windowState`, `setSelfAsOpener` | `normal` supports multiple URL tabs and an existing controlled tab; `popup` accepts only one page; created tabs are managed with distinct provenance |
657
+ | `updateWindow` / `resizeWindow` | `windowId`, `left`, `top`, `width`, `height`, `windowState`, `focused`, `drawAttention` | Applies supported Chrome window properties and returns observed state |
658
+
659
+ `updateWindow` and `resizeWindow` wait for a stable browser observation when changing state or geometry. Restoring a
660
+ non-normal window with `windowState="normal"` and bounds completes the state transition before applying bounds once.
661
+ OS-adjusted geometry is returned as observed. If observation does not stabilize within the bounded wait,
662
+ `WINDOW_UPDATE_NOT_OBSERVED` reports partial execution and the last observed window state; inspect `browse list` before
663
+ another update.
664
+
665
+ `browse list` defaults to `details="summary"`, returning target identity, URL/title, placement, managed/revision and
666
+ metadata. Set `details="full"` for highlighted/muted/discardable state, opener IDs and available native readonly
667
+ properties. False values are preserved. `targetIds` and `managedOnly=true` filter pages and their window/group
668
+ relations; `totalTargetCount`, `totalWindowCount` and `totalTabCount` distinguish inventory totals from selected counts.
669
+ Window objects reference pages through `targetIds` rather than repeating full targets. Inline favicon data URLs are
670
+ omitted; full details use `favIconInline=true` to indicate one exists. Groups retain title, color, collapsed/shared
671
+ state, window, first-member index and member IDs. Color belongs to a group, not a tab. Readonly properties are returned
672
+ when Chrome supplies them, not accepted as configuration writes. Listing does not read page content, navigate or focus.
673
+
674
+ Older Extensions that return group summaries without member arrays use the same response's window/tab membership to
675
+ populate group members and first-member index. Summary/full details and filters remain available without another RPC.
676
+ If group information is absent entirely, `groups` is omitted with a warning that it is unavailable. A supplied
677
+ `groups: []` means no groups. Malformed group data, including only one member array, returns an error.
678
+
679
+ Moving tabs/groups accepts `index=-1`; page creation requires a nonnegative index. Opener and explicit group/window
680
+ options must identify the same window. Pinned tabs cannot be created inside a group. Window state/bounds conflicts and
681
+ action-inappropriate fields are rejected before mutation. CDP rejects unsupported Chrome UI options rather than ignoring
682
+ them. `url` and `urls` are alternative inputs for `newWindow`; either can accompany `targetId` in a `normal` window. A
683
+ `popup` accepts a single URL or one existing tab, without additional URLs. Known preflight rejections retain
684
+ `actionExecuted=false`, `actionStatus="not_started"`, and `failureStage="preflight"`; rejected updates preserve the page
685
+ revision. Once a native update has been dispatched, a failure still invalidates that revision.
686
+
687
+ `emulate` applies the device viewport, pixel density, touch support, and User-Agent in both backends. `viewport`
688
+ restores desktop metrics, page scale, and disabled touch emulation; restore the User-Agent separately with `userAgent`.
376
689
 
377
690
  **Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
378
691
 
@@ -388,14 +701,23 @@ and cache. `focusWindow` only returns success after the target window is observe
388
701
  | `network` | Network request logs (with URL filter) |
389
702
 
390
703
  Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and
391
- `debug`; raw browser levels such as `warn` and `log` are normalized before filtering and return. Network logs include
392
- completed requests, HTTP 4xx/5xx responses, and failed loads with `errorText`, `method`, `url`, `status`, `timestamp`,
393
- and `duration` when available. URL query parameters commonly used for credentials, signatures, passwords, and tokens are
394
- replaced with `[REDACTED]` in inline responses, diagnostics, and explicit `output` files. Redacted entries include
395
- `urlRedacted`, `urlOriginalLength`, and `redactedQueryParameters`. Inline network results limit each sanitized URL to
396
- 2048 characters and add `urlLength` plus `urlTruncated: true` when shortened. `urlPattern` supports `*` for any number
397
- of characters and `?` for one character. `tabId` targets a specific tab (Extension mode). `frame` is not applicable for
398
- logs.
704
+ `debug`; raw browser levels such as `warn` and `log` are normalized before filtering and return. Clearing fallback
705
+ console logs keeps the hook active. When debugger collection becomes available, fallback capture is disabled. Console
706
+ methods still pointing to the MCP wrapper are restored, while wrappers installed later by the page are preserved.
707
+ Network logs are finalized on `loadingFinished` or `loadingFailed`, not when headers arrive, so body failures retain
708
+ both the HTTP status and `errorText`, and in-flight bodies continue to count against `networkidle`. Entries include
709
+ `method`, `url`, `status`, `timestamp`, and `duration` when available. URL query parameters commonly used for
710
+ credentials, signatures, passwords, and tokens are replaced with `[REDACTED]` in inline responses, diagnostics, and
711
+ explicit `output` files. Redacted entries include `urlRedacted`, `urlOriginalLength`, and `redactedQueryParameters`.
712
+ Inline network results limit each sanitized URL to 2048 characters and add `urlLength` plus `urlTruncated: true` when
713
+ shortened. `urlPattern` supports `*` for any number of characters and `?` for one character. `tabId` targets a specific
714
+ tab (Extension mode). `frame` is not applicable for logs.
715
+
716
+ When the Extension debugger is unavailable, network reads refresh performance entries and mark them with
717
+ `source="performance"`. Status uses the browser's `responseStatus` when available, or `0` otherwise; unknown request
718
+ methods remain empty. Repeated reads preserve record sequences. `clear` clears MCP records and advances the current
719
+ document's read boundary without clearing the page's shared performance timeline. A new document starts a new boundary.
720
+ Read failures return an error rather than an empty log.
399
721
 
400
722
  ### cookies - Cookie Management
401
723
 
@@ -407,7 +729,8 @@ logs.
407
729
  | `clear` | Delete cookies in a URL or domain scope, optionally narrowed by `name` |
408
730
 
409
731
  **Note**: `clear` requires `url` or `domain`. `name` can only further narrow that scope, so a same-named cookie on
410
- another site cannot be removed accidentally.
732
+ another site cannot be removed accidentally. The returned `count` includes only cookies for which Chrome confirms a
733
+ removal; cookies that disappear between listing and removal are not counted.
411
734
 
412
735
  ## Target: Unified Element Locator
413
736
 
@@ -515,12 +838,30 @@ extract(type="html", target={ css: ".article" }, images="info")
515
838
 
516
839
  // Get HTML + image data, save to directory
517
840
  extract(type="html", images="data", output="tmp:page")
518
- // Creates: <system-temp>/claude-tools/mcp-chrome/page/content.html, images/*, index.json
841
+ // Creates: <system-temp>/claude-tools/mcp-chrome/session-<id>/page/content.html, images/*, index.json
519
842
 
520
843
  // Get HTML + image data inline (max 20 images)
521
844
  extract(type="html", target={ css: ".card" }, images="data")
522
845
  ```
523
846
 
847
+ `tmp:` paths belong to the current server session. Temporary output has a 256-entry and 128 MiB session limit; on
848
+ startup, marked sessions older than 24 hours are removed only after their process exits. Use `cwd:` for files that must
849
+ remain accessible after restarting the server. Successful responses that save a `tmp:` file or directory include a
850
+ `retention` field describing the cleanup condition; `cwd:` responses omit it. Output paths reject Windows reserved
851
+ device names, alternate data streams, invalid characters, and trailing spaces or dots. On Windows, private file
852
+ permissions must be verified before writing sensitive content.
853
+
854
+ Invalid path syntax returns `INVALID_ARGUMENT`; `.` components are accepted and `..` components remain rejected. Paths
855
+ outside an allowed root, including symlink escapes, return `PATH_NOT_ALLOWED`. Both errors include the server's actual
856
+ working directory as `error.context.cwd`; scope rejections also include `allowedRoots`. Use `cwd:` with a path relative
857
+ to that directory, or `tmp:` for session output. These checks also apply to `scriptFile` and `compareWith`.
858
+
859
+ Quota rejection returns `TEMP_OUTPUT_QUOTA_EXCEEDED` with `limits`, `usage`, `remaining`, `requested`, and `projected`
860
+ in `error.context`. If `usage.complete` is false, usage is an observed lower bound and `remaining`/`projected` are null.
861
+ Existing output is preserved. An evaluate output failure retains `actionExecuted=true`, `actionStatus=completed`,
862
+ `failureStage=output`, and `retryable=false`; the script is not replayed. Use a repository-relative `cwd:` path for
863
+ subsequent output.
864
+
524
865
  ### Page Metadata
525
866
 
526
867
  ```
@@ -548,6 +889,18 @@ input(events=[
548
889
  Selectors and numeric indices follow the parent document's DOM iframe order. Subframes absent from that DOM, including
549
890
  frames added by other extensions, cannot shift the index or become fallback targets. If the selected element cannot be
550
891
  tied to exactly one Chrome frame, the operation returns `FRAME_IDENTITY_UNAVAILABLE` instead of choosing another frame.
892
+ Precise evaluation matches the complete iframe URL, including query strings and fragments, and uses the selected DOM
893
+ iframe to distinguish frames with the same URL, including `about:srcdoc`. It rejects the operation when that identity
894
+ cannot be confirmed.
895
+
896
+ Frame selection failures return `INVALID_FRAME_SELECTOR`, `FRAME_NOT_IFRAME`, or `FRAME_NOT_FOUND`. Read injections
897
+ report `INVALID_SELECTOR`, `FRAME_STALE_CONTEXT`, `FRAME_INJECTION_DENIED`, `FRAME_SCRIPT_FAILED`,
898
+ `FRAME_INJECTION_FAILED`, or `FRAME_SCRIPT_NO_RESULT`, with the injection or script-result phase. A missing result does
899
+ not establish that the selector is invalid. Empty text, empty element arrays, null attribute values, and void script
900
+ calls keep their existing meaning; errors do not replay the script. When a read fails after resolving a frame,
901
+ `pageContext.frameContext` retains its selected DOM index, Chrome frame ID, and available document identity. Frame URL
902
+ diagnostics remove credentials, query strings, and fragments and are limited to 500 characters. `data:` and
903
+ `javascript:` URLs expose only the protocol; an unparseable URL reports `url=null` and `urlStatus="unavailable"`.
551
904
 
552
905
  ### Wait for Element
553
906
 
@@ -682,21 +1035,48 @@ MIT License - see [LICENSE](LICENSE) for details.
682
1035
  Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and
683
1036
  `retryable`. Verification uses `matched`, `not_matched`, `unavailable`, or `error`; debugger timeouts report the action
684
1037
  as `unknown` when completion cannot be proven. Page-thrown exceptions report `actionExecuted=true` with
685
- `actionStatus="failed"`; result materialization or serialization errors report `actionStatus="completed"` and
686
- `failureStage="output"`. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action
687
- result. Browse and wait errors also retain any diagnostics collected before the action failed. Target diagnostics query
688
- the current tab state instead of relying on cached attach metadata.
1038
+ `actionStatus="failed"`. Once native execution returns a result, local materialization or serialization failures report
1039
+ `actionStatus="completed"` and `failureStage="output"`. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action
1040
+ result. On a page precondition mismatch, input and evaluate report `actionExecuted=false` and
1041
+ `actionStatus="not_started"`. Browse and wait errors also retain any diagnostics collected before the action failed.
1042
+ Target diagnostics query the current tab state instead of relying on cached attach metadata.
1043
+
1044
+ Native script termination, `Internal error`, `Object couldn't be returned by value`, and `Object reference chain is too long`
1045
+ responses from CDP `Runtime` script commands preserve the original error code. evaluate and `manage cdp` return `actionExecuted=true`,
1046
+ `actionStatus="unknown"`, and `retryable=false` without replaying the command. evaluate also returns `retryable=false`
1047
+ when an in-flight RPC timeout or stale execution context leaves the result unknown; timeouts before execution starts
1048
+ remain retryable. Page-thrown exceptions with the same text remain non-retryable action failures.
1049
+
1050
+ Recognized Extension CDP rejections return `CDP_ERROR` with the method, target, native message and available protocol
1051
+ code. The context distinguishes a disabled Debugger domain, stale script ID, browser-level command restriction, missing
1052
+ method, command permission refusal (`Not allowed`), and native result serialization failure. A resource or method lookup failure does not imply that the entire
1053
+ domain is unsupported. These remain failed calls with warning diagnostics; unknown errors retain error-level reporting.
1054
+ A closed tab found during a native snapshot or permission check remains a target failure, separate from page-thrown
1055
+ exceptions with matching text.
1056
+
1057
+ Extension accessibility state never reads `input[type=hidden]` or `input[type=password]` value getters for element names
1058
+ or state text. This applies to the default `all` filter, target subtrees, and file output. Hidden controls may still
1059
+ appear with `visible=false`; labels, placeholders, titles, and ordinary input values remain available. Explicit script,
1060
+ HTML, and attribute reads retain their existing behavior.
689
1061
 
690
1062
  `replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other
691
1063
  input types use a native full-value update and return the requested and actual browser-normalized values. A standalone
692
1064
  `select` on unsupported types returns `UNSUPPORTED_SELECTION`. CDP locator targets for `select` and `replace` are
693
1065
  focused through the CDP locator instead of Extension-only ref IDs. Password values are omitted from input failure
694
1066
  context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text`
695
- values. Target timeouts include bounded locator, tab, frame, match, and candidate context. Explicit `tabId` and `frame`
696
- scopes resolve the active backend before input, wait, logs, or extract work begins, so actions and verification use the
697
- same target backend. Precise iframe evaluation defaults to `staleContextRetry="never"` and does not replay stale
698
- scripts. `readOnly` permits one replay after the Extension verifies the frame identity and resolves a new execution
699
- context. Responses include the policy, `retryAttempted`, bounded `retryReason`, and the final `frameContext` with the
700
- Extension frame, parent frame, URL, CDP frame, and execution context IDs. Ambiguous same-URL frames are rejected. Port
701
- scanning aggregates ordinary pre-open failures at debug level; authentication and protocol rejections from identified
702
- MCP servers produce one bounded warning when the rejection summary changes.
1067
+ values. Password `select`/`replace` responses hide console and network diagnostic bodies on success and failure,
1068
+ returning `diagnostics.redacted=true` with `reason="sensitive_input_or_unresolved_target"`. This also applies when a
1069
+ selection target cannot be identified safely. Ordinary input retains its diagnostics; password protection lasts for the
1070
+ current input request. Target timeouts include bounded locator, tab, frame, match, and candidate context. Explicit
1071
+ `tabId` and `frame` scopes resolve the active backend before input, wait, logs, or extract work begins, so actions and
1072
+ verification use the same target backend. Precise iframe evaluation defaults to `staleContextRetry="never"` and does not
1073
+ replay stale scripts. `readOnly` permits one replay after the Extension verifies the frame identity and resolves a new
1074
+ execution context. Responses include the policy, `retryAttempted`, bounded `retryReason`, and the final `frameContext`
1075
+ with the Extension frame, parent frame, URL, CDP frame, and execution context IDs. Same-URL frames are rejected only
1076
+ when the selected DOM iframe cannot identify one target. Existing iframe targets remain usable after an Extension reload
1077
+ without refreshing or navigating the page. Invalidated probe contexts produce a warning and stop listening instead of
1078
+ throwing an uncaught messaging error. Discovery reports the initial port set and subsequent changes, including transitions
1079
+ to no servers; unchanged scans and automatic reconnects do not repeat that summary. Each scan still checks the entire
1080
+ port range. Explicit disconnect starts a new reporting cycle. Ordinary pre-open failures remain debug-level;
1081
+ authentication and protocol rejections from identified MCP servers produce one bounded warning when the rejection
1082
+ summary changes.