@pyrokine/mcp-chrome 2.4.1 → 3.0.0

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 (141) hide show
  1. package/README.md +546 -192
  2. package/README_zh.md +490 -192
  3. package/dist/anti-detection/behavior.js +1 -1
  4. package/dist/anti-detection/behavior.js.map +1 -1
  5. package/dist/anti-detection/injection.d.ts.map +1 -1
  6. package/dist/anti-detection/injection.js +5 -4
  7. package/dist/anti-detection/injection.js.map +1 -1
  8. package/dist/cdp/client.d.ts +2 -2
  9. package/dist/cdp/client.d.ts.map +1 -1
  10. package/dist/cdp/client.js +24 -10
  11. package/dist/cdp/client.js.map +1 -1
  12. package/dist/cdp/launcher.d.ts +2 -3
  13. package/dist/cdp/launcher.d.ts.map +1 -1
  14. package/dist/cdp/launcher.js +84 -24
  15. package/dist/cdp/launcher.js.map +1 -1
  16. package/dist/core/auto-wait.d.ts +3 -3
  17. package/dist/core/auto-wait.d.ts.map +1 -1
  18. package/dist/core/auto-wait.js +45 -20
  19. package/dist/core/auto-wait.js.map +1 -1
  20. package/dist/core/browser-driver.d.ts +104 -14
  21. package/dist/core/browser-driver.d.ts.map +1 -1
  22. package/dist/core/browser-driver.js +1 -0
  23. package/dist/core/browser-driver.js.map +1 -1
  24. package/dist/core/errors.d.ts +25 -0
  25. package/dist/core/errors.d.ts.map +1 -1
  26. package/dist/core/errors.js +93 -1
  27. package/dist/core/errors.js.map +1 -1
  28. package/dist/core/locator.d.ts.map +1 -1
  29. package/dist/core/locator.js +6 -4
  30. package/dist/core/locator.js.map +1 -1
  31. package/dist/core/os-mouse.d.ts +78 -0
  32. package/dist/core/os-mouse.d.ts.map +1 -0
  33. package/dist/core/os-mouse.js +378 -0
  34. package/dist/core/os-mouse.js.map +1 -0
  35. package/dist/core/session.d.ts +46 -21
  36. package/dist/core/session.d.ts.map +1 -1
  37. package/dist/core/session.js +724 -175
  38. package/dist/core/session.js.map +1 -1
  39. package/dist/core/types.d.ts +12 -0
  40. package/dist/core/types.d.ts.map +1 -1
  41. package/dist/core/types.js +2 -0
  42. package/dist/core/types.js.map +1 -1
  43. package/dist/core/unified-session.d.ts +117 -21
  44. package/dist/core/unified-session.d.ts.map +1 -1
  45. package/dist/core/unified-session.js +619 -129
  46. package/dist/core/unified-session.js.map +1 -1
  47. package/dist/core/utils.d.ts +5 -0
  48. package/dist/core/utils.d.ts.map +1 -1
  49. package/dist/core/utils.js +475 -54
  50. package/dist/core/utils.js.map +1 -1
  51. package/dist/extension/bridge.d.ts +61 -35
  52. package/dist/extension/bridge.d.ts.map +1 -1
  53. package/dist/extension/bridge.js +290 -106
  54. package/dist/extension/bridge.js.map +1 -1
  55. package/dist/extension/http-server.d.ts +3 -0
  56. package/dist/extension/http-server.d.ts.map +1 -1
  57. package/dist/extension/http-server.js +25 -3
  58. package/dist/extension/http-server.js.map +1 -1
  59. package/dist/index.js +7 -0
  60. package/dist/index.js.map +1 -1
  61. package/dist/tools/browse.d.ts +1 -1
  62. package/dist/tools/browse.d.ts.map +1 -1
  63. package/dist/tools/browse.js +291 -175
  64. package/dist/tools/browse.js.map +1 -1
  65. package/dist/tools/challenge.d.ts +153 -0
  66. package/dist/tools/challenge.d.ts.map +1 -0
  67. package/dist/tools/challenge.js +611 -0
  68. package/dist/tools/challenge.js.map +1 -0
  69. package/dist/tools/cookies.d.ts.map +1 -1
  70. package/dist/tools/cookies.js +13 -7
  71. package/dist/tools/cookies.js.map +1 -1
  72. package/dist/tools/diagnostics.d.ts +5 -5
  73. package/dist/tools/diagnostics.d.ts.map +1 -1
  74. package/dist/tools/diagnostics.js +39 -20
  75. package/dist/tools/diagnostics.js.map +1 -1
  76. package/dist/tools/evaluate.d.ts.map +1 -1
  77. package/dist/tools/evaluate.js +106 -23
  78. package/dist/tools/evaluate.js.map +1 -1
  79. package/dist/tools/extract.d.ts.map +1 -1
  80. package/dist/tools/extract.js +199 -208
  81. package/dist/tools/extract.js.map +1 -1
  82. package/dist/tools/input.d.ts +1 -1
  83. package/dist/tools/input.d.ts.map +1 -1
  84. package/dist/tools/input.js +523 -175
  85. package/dist/tools/input.js.map +1 -1
  86. package/dist/tools/logs.d.ts.map +1 -1
  87. package/dist/tools/logs.js +7 -7
  88. package/dist/tools/logs.js.map +1 -1
  89. package/dist/tools/manage.d.ts.map +1 -1
  90. package/dist/tools/manage.js +400 -64
  91. package/dist/tools/manage.js.map +1 -1
  92. package/dist/tools/network-sanitizer.d.ts.map +1 -1
  93. package/dist/tools/network-sanitizer.js +1 -0
  94. package/dist/tools/network-sanitizer.js.map +1 -1
  95. package/dist/tools/page-context.d.ts +17 -0
  96. package/dist/tools/page-context.d.ts.map +1 -0
  97. package/dist/tools/page-context.js +103 -0
  98. package/dist/tools/page-context.js.map +1 -0
  99. package/dist/tools/png.d.ts +5 -0
  100. package/dist/tools/png.d.ts.map +1 -1
  101. package/dist/tools/png.js +89 -22
  102. package/dist/tools/png.js.map +1 -1
  103. package/dist/tools/post-condition.d.ts.map +1 -1
  104. package/dist/tools/post-condition.js +17 -5
  105. package/dist/tools/post-condition.js.map +1 -1
  106. package/dist/tools/schema.d.ts +9 -0
  107. package/dist/tools/schema.d.ts.map +1 -1
  108. package/dist/tools/schema.js +15 -0
  109. package/dist/tools/schema.js.map +1 -1
  110. package/dist/tools/target-diagnostics.d.ts +7 -0
  111. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  112. package/dist/tools/target-diagnostics.js +47 -17
  113. package/dist/tools/target-diagnostics.js.map +1 -1
  114. package/dist/tools/wait.d.ts.map +1 -1
  115. package/dist/tools/wait.js +52 -56
  116. package/dist/tools/wait.js.map +1 -1
  117. package/extension/dist/assets/content.ts-C4imZ6A9.js +13 -0
  118. package/extension/dist/assets/content.ts-loader-CnJuCGhl.js +13 -0
  119. package/extension/dist/assets/{index.ts-GG6dPUPX.js → index.ts-GeHNZBml.js} +2156 -1950
  120. package/extension/dist/assets/page-scripts-CMIY1zhd.js +1379 -0
  121. package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-CgtWL6Py.js} +48 -1
  122. package/extension/dist/manifest.json +4 -3
  123. package/extension/dist/service-worker-loader.js +1 -1
  124. package/extension/dist/src/popup/popup.html +54 -44
  125. package/package.json +11 -8
  126. package/scripts/start-chrome.ps1 +58 -0
  127. package/dist/extension/native-host-installer.d.ts +0 -21
  128. package/dist/extension/native-host-installer.d.ts.map +0 -1
  129. package/dist/extension/native-host-installer.js +0 -147
  130. package/dist/extension/native-host-installer.js.map +0 -1
  131. package/dist/extension/socket-server.d.ts +0 -32
  132. package/dist/extension/socket-server.d.ts.map +0 -1
  133. package/dist/extension/socket-server.js +0 -177
  134. package/dist/extension/socket-server.js.map +0 -1
  135. package/dist/extension/ws-server.d.ts +0 -40
  136. package/dist/extension/ws-server.d.ts.map +0 -1
  137. package/dist/extension/ws-server.js +0 -246
  138. package/dist/extension/ws-server.js.map +0 -1
  139. package/dist/native-host/index.js +0 -280
  140. package/dist/native-host/mcp-chrome-host +0 -2
  141. package/extension/dist/assets/content.ts-Cj_iiU2s.js +0 -25
package/README.md CHANGED
@@ -13,9 +13,10 @@ 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
- - **Semantic Targeting**: 11 ways to locate elements (role, text, label, css, css+text combo, xpath, coordinates, etc.)
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
20
21
  - **Dual Input Mode**: `precise` (debugger API, bypasses CSP) or `stealth` (JS injection, no debug banner)
21
22
  - **Smart Output**: Bare `return` auto-wrapped in IIFE; large results (>100KB) auto-saved to file; `output` writes raw
@@ -24,15 +25,28 @@ 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
+
27
41
  ## Compatible Clients
28
42
 
29
43
  | Client | Status |
30
- |---------------------------|--------|
31
- | Claude Code | ✅ |
32
- | Claude Desktop | ✅ |
33
- | Cursor | ✅ |
34
- | Windsurf | ✅ |
35
- | Any MCP-compatible client | ✅ |
44
+ | ------------------------- | ------ |
45
+ | Claude Code | ✅ |
46
+ | Claude Desktop | ✅ |
47
+ | Cursor | ✅ |
48
+ | Windsurf | ✅ |
49
+ | Any MCP-compatible client | ✅ |
36
50
 
37
51
  ## Installation
38
52
 
@@ -46,7 +60,8 @@ claude mcp add chrome -- mcp-chrome
46
60
  npm root -g
47
61
  ```
48
62
 
49
- For Extension mode, open `chrome://extensions/`, enable Developer mode, click "Load unpacked", and select `<npm-root>/@pyrokine/mcp-chrome/extension/dist`.
63
+ For Extension mode, open `chrome://extensions/`, enable Developer mode, click "Load unpacked", and select
64
+ `<npm-root>/@pyrokine/mcp-chrome/extension/dist`.
50
65
 
51
66
  ### From source
52
67
 
@@ -62,6 +77,21 @@ claude mcp add chrome -- node "$PWD/dist/index.js"
62
77
 
63
78
  For Extension mode, load `extension/dist` in Chrome.
64
79
 
80
+ ### Windows CDP launch
81
+
82
+ Chrome discovery checks Windows App Paths, `PATH`, installed Chrome channels, Chromium, Chrome for Testing, and
83
+ `MCP_CHROME_PORTABLE_DIR` (or `%USERPROFILE%\\.mcp-chrome\\portable`). To start a separate CDP browser from PowerShell:
84
+
85
+ ```powershell
86
+ & '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
87
+ # Or specify a portable executable and profile explicitly:
88
+ & '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222 -ExecutablePath 'C:\Browsers\chrome.exe' -ProfileDir 'C:\Temp\mcp-chrome-profile'
89
+ ```
90
+
91
+ Then call `browse(action="connect", port=9222)`. The script keeps its Chrome process in the foreground; Chrome exit
92
+ codes are reported by the script. Use a separate profile so an existing Chrome process cannot silently absorb the
93
+ launch.
94
+
65
95
  ## Quick Start
66
96
 
67
97
  ### Mode 1: Extension Mode (Recommended)
@@ -89,14 +119,12 @@ Claude Desktop / Other Clients:
89
119
 
90
120
  ```json
91
121
  {
92
- "mcpServers": {
93
- "chrome": {
94
- "command": "node",
95
- "args": [
96
- "/path/to/mcp-chrome/dist/index.js"
97
- ]
122
+ "mcpServers": {
123
+ "chrome": {
124
+ "command": "node",
125
+ "args": ["/path/to/mcp-chrome/dist/index.js"]
126
+ }
98
127
  }
99
- }
100
128
  }
101
129
  ```
102
130
 
@@ -104,9 +132,10 @@ Claude Desktop / Other Clients:
104
132
 
105
133
  The Extension auto-connects to the MCP Server via HTTP/WebSocket (port 19222-19299). Click the toolbar icon to verify
106
134
  connection status. `browse(action="connect")` and the local `/api/info` endpoint report the active Extension background
107
- bundle hash and compare it with the bundle shipped beside the server. `bundleStatus="stale"` means Chrome is still running
108
- an older unpacked Extension bundle; reload the Extension in `chrome://extensions/`. Legacy Extensions without a bundle hash
109
- remain compatible, and bundle identity never disables zero-config auto-connect.
135
+ bundle hash and compare it with the bundle shipped beside the server. `bundleStatus="stale"` means Chrome is still
136
+ running an older unpacked Extension bundle; reload the Extension in `chrome://extensions/`. A legacy Extension that
137
+ lacks `network_challenge_state` falls back to tab-title and DOM challenge detection. Bundle identity never disables
138
+ zero-config auto-connect.
110
139
 
111
140
  ```
112
141
  browse(action="list") // List all tabs
@@ -117,15 +146,16 @@ extract(type="screenshot")
117
146
  **Pairing token**
118
147
 
119
148
  Extension mode keeps zero-config local auto-connect by default. On shared machines, CI runners, or containers where
120
- untrusted local processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the MCP server and enter the
121
- same token in the Extension popup:
149
+ untrusted local processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the MCP server and enter
150
+ the same token in the Extension popup:
122
151
 
123
152
  ```bash
124
153
  MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
125
154
  ```
126
155
 
127
- To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server and
128
- disable "Allow no-token local connection" in the Extension popup.
156
+ To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server
157
+ and disable "Allow no-token local connection" in the Extension popup. Disabling that policy immediately cancels pending
158
+ health checks, WebSocket handshakes, and scheduled reconnects, so an older no-token attempt cannot connect afterward.
129
159
 
130
160
  ### Mode 2: CDP Mode (Fallback)
131
161
 
@@ -142,54 +172,199 @@ browse(action="connect", port=9222)
142
172
  browse(action="open", url="https://example.com")
143
173
  ```
144
174
 
145
- > When the Extension is connected, all tools use Extension mode automatically. CDP mode activates only when the
146
- > Extension is unavailable.
175
+ > A connected Extension is the default for every tool. CDP is used only while the Extension is unavailable. A
176
+ > `browse(action="connect", port=9222)` call explicitly selects CDP for later tools; use `browse(action="connect")` to
177
+ > return to Extension mode. A CDP connection created only as fallback yields to Extension after the Extension
178
+ > reconnects.
147
179
 
148
180
  ## Available Tools (8 Tools)
149
181
 
150
182
  ### browse - Browser Management & Navigation
151
183
 
152
- | Action | Description |
153
- |-----------|---------------------------------------|
154
- | `launch` | Launch new Chrome instance (CDP mode) |
155
- | `connect` | Connect to running Chrome (CDP mode) |
156
- | `list` | List all pages/tabs |
157
- | `attach` | Attach to a specific page/tab |
158
- | `open` | Navigate to URL |
159
- | `back` | Go back in history |
160
- | `forward` | Go forward in history |
161
- | `refresh` | Reload page |
162
- | `close` | Close browser connection |
184
+ | Action | Description |
185
+ | --------- | --------------------------------------------------------------------------- |
186
+ | `launch` | Create a managed Extension tab, or launch CDP when Extension is unavailable |
187
+ | `connect` | Confirm Extension by default; `port` explicitly selects CDP |
188
+ | `list` | List all pages/tabs |
189
+ | `attach` | Attach to a specific page/tab |
190
+ | `open` | Navigate to URL |
191
+ | `back` | Go back in history |
192
+ | `forward` | Go forward in history |
193
+ | `refresh` | Reload page |
194
+ | `close` | Close the page specified by `targetId` |
163
195
 
164
196
  Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
165
- (whether tab is controlled by MCP Chrome), `isActive` (whether it's the current operation target), `windowId`, `index`,
197
+ (whether the tab is controlled by MCP Chrome), `isActive` (Chrome's active tab within its window), `windowId`, `index`,
166
198
  `pinned`, `incognito`, and `status` (`loading`/`complete`). The tree includes `windowCount`, `focusedWindowId`,
167
- `activeTargetId`, and each window's ordered `tabs` list, so callers can distinguish the active tab inside each window
168
- from the page currently visible in the focused window.
169
- `open` auto-creates tab group (cyan color). `open`, `back`, `forward`, and `refresh` accept `diagnostics=true` to return
170
- new console warnings/errors and failed network requests observed during the action, including the first `open` that
171
- creates a page automatically.
199
+ `activeTargetId`, and each window's ordered `tabs` list. `defaultTargetId` identifies the selected operation target; CDP
200
+ does not infer Chrome's foreground tab from this selection. `open` auto-creates tab group (cyan color). `open`, `back`,
201
+ `forward`, and `refresh` accept `diagnostics=true` to return new console warnings/errors and failed network requests
202
+ observed during the action, including the first `open` that creates a page automatically. `open` and `refresh` honor
203
+ `wait="load"`, `wait="domcontentloaded"`, and `wait="networkidle"` in both drivers. The wait is registered before the
204
+ command and bound to the new main document, so late lifecycle events from an earlier navigation are ignored. CDP
205
+ `networkidle` waits for the current main-frame loader's `networkIdle` event. Extension `networkidle` waits for the
206
+ current document to complete, all tracked response bodies to finish, and a 500 ms quiet period. Lost request tracking
207
+ causes a timeout instead of a false idle result. `close` requires `targetId` and closes only that page. It never closes
208
+ the entire CDP connection.
209
+
210
+ In Extension mode, `back` and `forward` use native browser history first. Only a native no-history error permits a
211
+ script fallback, and only on a scriptable document; restricted URLs and browser error pages are not injected. With no
212
+ available history they return `navigated=false`. Other native failures are preserved. A destroyed execution context or a
213
+ browser refusing injection into an error page still returns an operation failure, recorded as a warning in the Extension
214
+ rather than a program error. Arbitrary debugger commands are never automatically replayed.
215
+
216
+ For `open`, `back`, `forward`, and `refresh`, `timeout` starts at request entry. Target preparation, queueing, protocol
217
+ calls, page loading, Challenge inspection and clicks, diagnostics, and target restoration share the remaining budget;
218
+ navigation RPCs do not add transport time. An expired queued action is not dispatched, and later requests still wait for
219
+ an earlier in-flight action to settle. Explicit `timeout=0` rejects before navigation dispatch. Page creation retains
220
+ its separate load-wait and transport-time contract.
221
+
222
+ A timeout does not undo a Chrome operation already dispatched. When its result is unknown, the response reports
223
+ `TIMEOUT`, `actionExecuted="unknown"`, `actionStatus="unknown"`, and `retryable=false`; read the actual page state
224
+ instead of replaying navigation. `pageContext.after` uses a fresh snapshot when available; otherwise it is null with
225
+ `contextError`. Exhausted restoration is reported separately without replacing the primary action result. CDP history
226
+ waits accept a main-frame BFCache restore or same-document event from the current session, not an ordinary frame commit,
227
+ a child-frame event, or an event from another session.
228
+
229
+ Challenge click, detach, and inspection RPCs carry the remaining deadline and reject dispatch after queueing or page
230
+ validation exhausts it. OS mouse movement and fallback processes use the same deadline. A CDP press that has started
231
+ always attempts release on the original connection and session; release cleanup waits at most one second and never uses
232
+ a newly selected target. Read-only Challenge checks that expire return `CHALLENGE_TIMEOUT` with the known primary action
233
+ status. An uncertain click returns `TIMEOUT` with that primary status, `verificationStatus="unknown"`,
234
+ `verificationActionExecuted`, and `retryable=false`; neither navigation nor the click is automatically replayed.
235
+
236
+ Evaluate retains Challenge result fields on success, action failure, verification mismatch, and output failure.
237
+ `originResponsePending=true` means verification succeeded but the origin server has not responded; it does not mean the
238
+ destination content has loaded.
239
+
240
+ Page tools accept `targetId` in either backend; the older `tabId` alias is still accepted. If both are supplied, they
241
+ must match. An explicit target changes only the operation scope and restores the previous default afterward.
242
+ `browse.close` and `manage.closePage` require an explicit ID. Page responses, including action failures, include
243
+ `pageContext` with the effective target and its source (`explicit`, `default`, `created`, `reused`, or `unconfirmed`),
244
+ before/after URL and revision, default target before/after, and Chrome's active target when Extension reports it.
245
+ `unconfirmed` means a page-creation action failed without returning a created target ID. CDP reports browser activity as
246
+ unavailable rather than treating the selected operation target as foreground.
247
+
248
+ When an older Extension lacks `page_snapshot`, unconditional page actions can still use a fresh page-list URL. Their
249
+ `pageContext.before` and `after` snapshots report `revision=null` with a `warning` about the unavailable revision and
250
+ atomic conditions. Requests with `expectedUrl` or `expectedRevision` return `DRIVER_CAPABILITY_ERROR`,
251
+ `actionExecuted=false`, and `actionStatus="not_started"` before dispatch; update the Extension to use these conditions.
252
+ Evaluate and input retain `failureStage="precondition"`, with matching top-level and error-context status and no script
253
+ or input events dispatched. Other snapshot errors still stop the action, and compatibility reads share the original
254
+ timeout budget.
255
+
256
+ In Extension mode, a page snapshot that reports the requested tab is missing returns `TARGET_NOT_FOUND` with
257
+ `context.targetId` and the original `context.nativeMessage`. Input rejected before dispatch retains `eventsExecuted=0`
258
+ and `actionExecuted=false`. The failed request is not redirected to another page or replayed. User-script exceptions
259
+ with the same text are not classified as missing pages.
260
+
261
+ Creation failures retain `error.context.createdTargetId`, window ID, actual `managed`, `actionExecuted`,
262
+ `actionStatus="partial"` and `failureStage` when Chrome has returned the identity. If an RPC response is unknown,
263
+ `actionStatus` and `actionExecuted` are `"unknown"`; `pageContext.targetId` is null unless the created identity is
264
+ known, never the previous default page. Failed creation is not automatically repeated or undone.
265
+
266
+ Temporary target restoration is reported separately in `pageContext.targetRestoration`: `restored` selects the previous
267
+ default, `cleared` leaves no default when none existed, `previous_target_closed` clears a closed default, and `failed`
268
+ reports restoration or cleanup errors while clearing the temporary selection. `error` and `cleanupError` retain the
269
+ respective failure messages. The primary action result or original error is preserved; completed input is not replayed
270
+ or reported as unexecuted. `browse attach` and `manage adoptPage` keep their persistent-default behavior. Concurrent
271
+ page responses describe the page actually used by each action.
272
+
273
+ `browse.list` returns each page's revision and metadata. Revisions combine a backend epoch with a per-page counter.
274
+ Extension counts main-frame navigations and MCP actions; CDP counts observed navigation for the attached page and
275
+ conservatively counts sent mutating commands, including evaluations. Neither driver tracks arbitrary DOM changes made by
276
+ the page itself; re-read URL and revision before a conditional action. `browse` navigation/close, `input`, `evaluate`,
277
+ and eligible `manage` page actions accept `expectedUrl` and `expectedRevision`. A mismatch at the backend returns
278
+ `ACTION_PRECONDITION_FAILED` before that page action is sent. A multi-event action checks conditions before its first
279
+ modifying command, not before every event. A failed or timed-out action can still change the revision when it may have
280
+ had partial effects.
281
+
282
+ For `browse`, only `open`, `back`, `forward`, `refresh`, and `close` accept these conditions. Other actions, including
283
+ `attach`, reject them with `INVALID_ARGUMENT` before changing any target.
284
+
285
+ Explicit `manage(action="adoptPage", targetId=...)` makes an existing page fully managed without focusing or navigating
286
+ it. `browse attach` only selects a target. Creation provenance, group membership, and group color do not authorize a
287
+ page. `releasePage` revokes full managed access without closing the tab or changing its window or group; it clears MCP
288
+ log state and removes debugging and console capture resources. If Chrome prevents resource cleanup, the response
289
+ includes `warnings` while managed access is still revoked.
290
+
291
+ A managed tab can keep using this Extension's existing debugger session after a Service Worker restart. Sessions owned
292
+ by other debuggers still return `DEBUGGER_BLOCKED`.
293
+
294
+ Use `manage(action="grantReadAccess", targetId=...)` to grant ordinary reads and `revokeReadAccess` to revoke them; no
295
+ popup click is required. Both require an explicit target and accept `expectedUrl`/`expectedRevision`. Grants belong to
296
+ the calling server instance and the current document identity, URL and revision. Storage failure is an error, not
297
+ successful authorization. The popup remains an optional control. A grant survives a Service Worker restart only while
298
+ that connection and the approved document remain unchanged. Navigation, tab closure, or connection closure revokes it. A
299
+ target ID alone does not authorize reading. The grant covers ordinary content reads, including targeted text, HTML,
300
+ attributes, computed styles, and page state. Scripts, debugger operations, screenshots, input, and cookie access do not
301
+ inherit it; existing cookie operations have separate URL/name filter rules. When page management or navigation is
302
+ refused for lack of managed access, the revision and any valid ordinary-read grant remain unchanged.
303
+ `manage(action="pageMetadata", targetId=...)` reads or updates `taskHint` and `note`, and list results show creation and
304
+ last-use timestamps. Reads and updates accept `expectedUrl`/`expectedRevision`; a mismatch returns
305
+ `ACTION_PRECONDITION_FAILED` without reading or updating notes. This metadata is process-local and is removed when a
306
+ page is closed; it never authorizes content access.
307
+
308
+ ### Access challenges
309
+
310
+ After `open`, `back`, `forward`, `refresh`, `input`, and `evaluate`, MCP Chrome waits for a Cloudflare JS Challenge or
311
+ Turnstile checkbox. When Extension mode is active, navigation starts without debugger logging and reads the live tab
312
+ title passively for eight seconds. If the interstitial persists, MCP Chrome checks for a visible Turnstile control and
313
+ clicks it only when it finds one. Extension inspect uses an isolated world and detaches the debugger first. Same-page
314
+ fixture buttons use the existing page click. If a Cloudflare Turnstile iframe is present, inspect CSS coordinates are
315
+ converted to screen coordinates and the OS mouse moves along a path, hovers, then presses and releases: `xdotool` on
316
+ Linux uses the focused Chrome client-window geometry and `xprop` GTK frame extents only when that window title matches
317
+ the test page. Missing tools, invalid geometry, or a viewport mismatch stop the click instead of guessing the content
318
+ origin from Chrome `screenX` or `outerHeight - innerHeight`; `cliclick` or System Events on macOS; and PowerShell
319
+ `mouse_event` on Windows. Widget clicks target the checkbox on the left of the compact Turnstile card, including when
320
+ the host wrapper is wider than the card, not the label. If a Cloudflare iframe is already in the DOM, the OS mouse is
321
+ used even when that iframe reports a zero-size rect, including the later host `Verify you are human` / `请验证您是真人`
322
+ button. The OS click runs only when the managed test tab is already the active tab in an already-focused window; mixed
323
+ windows are not focused. Debugger is detached and the viewport is read again before the OS click. Missing OS mouse tools
324
+ or an unfocused window return a visible error instead of a silent CDP click. A Turnstile widget is clicked only after
325
+ two inspections report the same click point; unrelated elements do not become widgets just because their sizes match.
326
+ Distant OS-mouse paths start near the control instead of flying across the screen. The same checkbox or compact widget
327
+ is clicked at most once; if Cloudflare then shows a visible `Verify you are human` or `请验证您是真人` button, that
328
+ button is inspected as `verify` and clicked at most once in the same wait. Use the default `diagnostics=false` for
329
+ challenge-protected pages because diagnostics starts debugger console and network collection.
330
+
331
+ Detection covers titles such as `Just a moment...` and `请稍候…`, challenge DOM or body-text markers, and
332
+ `Verify you are human` / `请验证您是真人` controls, including visible `button` elements with that exact text. Same-page
333
+ buttons use page input when no Cloudflare iframe is present. CDP reads live titles with `Target.getTargetInfo`. A
334
+ leftover Cloudflare iframe on a recovered page is not pending. Cached titles do not decide the result. MCP Chrome does
335
+ not call a CAPTCHA solver, retry navigation, or export `cf_clearance` values. A CDP timeout does not prove that the site
336
+ fails in a user Chrome session; check the returned `mode` before diagnosing the site.
337
+
338
+ A resolved challenge returns `challengeResolved=true`, `challengeKind`, `waitedMs`, `clickedTurnstile`, and
339
+ `clearanceCookiePresent` (name presence only). If the visible page text says verification succeeded and Cloudflare is
340
+ waiting for the origin, the result also has `originResponsePending=true`; verification passed, but the destination page
341
+ is not loaded yet. Hidden template text such as a `display:none` success heading does not count, and a visible Turnstile
342
+ checkbox still counts as pending. Challenge results and errors include `mode`. Timeout returns `CHALLENGE_TIMEOUT` with
343
+ `retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is not reported as `js`).
344
+ Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP reputation checks
345
+ cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears the header flag;
346
+ ordinary iframe document responses and clearing network logs do not.
172
347
 
173
348
  ### input - Keyboard & Mouse Input
174
349
 
175
350
  Event sequence model supporting arbitrary combinations:
176
351
 
177
- | Event Type | Description |
178
- |-----------------------------------------|-----------------------------------------------------------------------------------|
179
- | `keydown` / `keyup` | Key press/release |
180
- | `click` | Click with actionability checks (visible, enabled, not-covered, auto-scroll) |
181
- | `mousedown` / `mouseup` | Mouse button press/release |
182
- | `mousemove` | Mouse movement |
183
- | `wheel` | Mouse wheel scroll |
184
- | `touchstart` / `touchmove` / `touchend` | Touch events |
185
- | `type` | Type text (with optional `delay`, `dispatch` for React/Vue) |
186
- | `wait` | Pause between events |
187
- | `select` | Select text by content (mouse sim) |
188
- | `replace` | Find and replace text |
189
- | `drag` | HTML5 drag-and-drop (DragEvent in MAIN world, with `target` source + `to` target) |
190
- | `editorContext` | Read focused editor and selection context |
191
- | `editorInsert` | Insert text at the current editor selection |
192
- | `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList` |
352
+ | Event Type | Description |
353
+ | --------------------------------------- | ---------------------------------------------------------------------- |
354
+ | `keydown` / `keyup` | Key press/release |
355
+ | `click` | Click after visibility, enabled, coverage, and scroll checks |
356
+ | `mousedown` / `mouseup` | Mouse button press/release |
357
+ | `mousemove` | Mouse movement |
358
+ | `wheel` | Mouse wheel scroll |
359
+ | `touchstart` / `touchmove` / `touchend` | Touch events |
360
+ | `type` | Type text (with optional `delay`, `dispatch` for React/Vue) |
361
+ | `wait` | Pause between events |
362
+ | `select` | Select text by content (mouse sim) |
363
+ | `replace` | Find and replace text |
364
+ | `drag` | HTML5 drag-and-drop (`target` source and `to` destination) |
365
+ | `editorContext` | Read focused editor and selection context |
366
+ | `editorInsert` | Insert text at the current editor selection |
367
+ | `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList` |
193
368
 
194
369
  Special-case parameters:
195
370
 
@@ -199,28 +374,62 @@ Special-case parameters:
199
374
  the CDP commands API has no JS-event equivalent.
200
375
  - `keydown` on a key already held emits `rawKeyDown` with `autoRepeat: true` (Puppeteer-compatible long-press).
201
376
 
202
- Parameters: `humanize` enables Bézier curve movement and random delays. `diagnostics=true` returns new console
203
- warnings/errors and failed network requests after the action. `postCondition` waits for a page state after the events so
204
- callers can distinguish dispatched input from completed page behavior. `postCondition.timeout` defaults to 3000 ms and
205
- is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and accepts 50-5000 ms. `tabId` targets a specific
206
- tab. `frame` targets an iframe (CSS selector or index). Both are Extension-mode only. When either scope is provided, the
207
- action, diagnostics, and post-condition use the backend selected for that target scope.
208
-
209
- **`click`-specific**: `force: true` skips actionability checks (useful for testing or hidden elements). Actionability
210
- failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering element details, candidate blockers, and
211
- suggestions.
212
- **`type`-specific**: `mode="controlled"` or `dispatch: true` sets `.value` directly and fires `input`/`change` events —
213
- use for React/Vue controlled inputs where keyboard events don't update state. Requires a non-coordinate `target`.
214
- Extension mode only. Controlled input and target lookup failures return structured context with `target`, `matchCount`,
215
- `nth`, `activeElement`, `selection`, and candidate controls. Password input values are omitted from failure diagnostics,
216
- and input `find` or replacement `text` values are redacted from failed responses. For `select` and `replace`, event-level
217
- `nth` selects the Nth text occurrence while nested `target.nth` selects the Nth matching element; both are zero-based and
218
- may be used together. Locator targets for `select` and `replace` work in CDP mode without Extension ref IDs.
377
+ `events` must contain at least one event. Parameters: `humanize` enables Bézier curve movement and random delays.
378
+ `diagnostics=true` returns new console warnings/errors and failed network requests after the action. `postCondition`
379
+ waits for a page state after the events so callers can distinguish dispatched input from completed page behavior.
380
+ `postCondition.timeout` defaults to 3000 ms and is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and
381
+ accepts 50-5000 ms. A `postCondition.script` may be an expression, function, async function, or Promise expression;
382
+ functions are invoked and the final Promise value is awaited before matching, while thrown or rejected errors fail the
383
+ check. `targetId` (or legacy `tabId`) selects a page in either backend; `frame` selects an iframe (CSS selector or
384
+ index) in Extension mode. When either scope is provided, the action, diagnostics, and post-condition use the backend
385
+ selected for that target scope.
386
+
387
+ For keyboard `type`, `timeout` includes Challenge waiting, focus preparation, character input, and `delay`/`humanize`
388
+ delays. Extension precise/stealth and CDP use the remaining budget. An explicit budget such as `timeout=45000` allows
389
+ valid input to take longer than the default 30000 ms. When the budget expires, subsequent characters and events stop.
390
+ Already dispatched input cannot be undone, so a timeout may leave partial input. A response with `actionExecuted=true`,
391
+ `actionStatus="unknown"`, and `retryable=false` requires an independent page read to check the actual value; do not
392
+ replay the whole event sequence.
393
+
394
+ Mouse target lookup, stepped movement, and `humanize` delays also share the remaining input budget. Each movement and
395
+ the subsequent click check the deadline; expiry stops further movement and clicking. Already dispatched native events
396
+ cannot be undone. Read the page independently after an unknown result instead of replaying the action.
397
+
398
+ Command focus, text selection, and replacement share the remaining event budget. Expiry stops subsequent actions; Shift
399
+ release is still attempted without hiding an earlier action error. Stepped CDP touch movement also stops at the
400
+ deadline.
401
+
402
+ In stealth mode, `delay` separates characters; the first character has no initial wait. Background page timer throttling
403
+ can lengthen subsequent intervals, but the same deadline still stops further input.
404
+
405
+ Precise Extension and CDP keyboard input use the current caret and selection. A `target` is clicked before typing and
406
+ can change the insertion point. To append to a contenteditable element, focus it, place the caret at its end, then send
407
+ `type` without a `target` so that it does not click again.
408
+
409
+ CDP clicks and keyboard input also wait for stable element position and size in background pages without activating
410
+ them. Visibility, enabled-state, viewport, and click coverage checks still apply. Target lookup, actionability checks,
411
+ and the final coordinate read share the remaining event budget. If any of these stages exhausts it, no mouse or keyboard
412
+ event is dispatched.
413
+
414
+ **`click`-specific**: `force: true` requires `forceReason` and a non-coordinate element `target`, and skips
415
+ actionability checks (useful for testing or hidden elements), but still dispatches the standard DOM mouse-event sequence
416
+ and does not call framework-private handlers. The same checks apply to middle/right clicks and multiple clicks. Missing
417
+ targets and coordinate targets cannot use `force`. Actionability failures return `ACTIONABILITY_FAILED` with `rect`,
418
+ `clickPoint`, covering element details, candidate blockers, and suggestions. **`type`-specific**: `mode="controlled"` or
419
+ `dispatch: true` sets `.value` directly and fires `input`/ `change` events — use for React/Vue controlled inputs where
420
+ keyboard events don't update state. Requires a non-coordinate `target`. Extension mode only. Controlled input and target
421
+ lookup failures return structured context with `locator`, `matchCount`, `nth`, bounded `candidates`, and an
422
+ `activeElement` summary without input values. The focus summary is `null` when unavailable; a failed DOM query also
423
+ returns `diagnosticError`. Selection-specific errors also report editor and selection state. Password input values are
424
+ omitted from failure diagnostics, and input `find` or replacement `text` values are redacted from failed responses. For
425
+ `select` and `replace`, event-level `nth` selects the Nth text occurrence while nested `target.nth` selects the Nth
426
+ matching element; both are zero-based and may be used together. Locator targets for `select` and `replace` work in CDP
427
+ mode without Extension ref IDs.
219
428
 
220
429
  ### extract - Content Extraction
221
430
 
222
431
  | Type | Description |
223
- |--------------|---------------------------------------------------|
432
+ | ------------ | ------------------------------------------------- |
224
433
  | `text` | Extract text content |
225
434
  | `html` | Extract HTML source |
226
435
  | `frameHtml` | Extract HTML from the selected iframe |
@@ -229,16 +438,33 @@ may be used together. Locator targets for `select` and `replace` work in CDP mod
229
438
  | `state` | Get page state (URL, title, interactive elements) |
230
439
  | `metadata` | Extract page metadata (title, OG, JSON-LD, etc.) |
231
440
 
441
+ Text extraction uses the browser's `innerText` for HTML pages and selected elements. Rendered regions omit nested
442
+ `style`/`script` source and hidden descendants. Explicitly selected non-rendered HTML follows the browser's `innerText`
443
+ rules; SVG/XML nodes use `textContent`. Use `html` for source markup.
444
+
232
445
  Parameters: `output` saves result to file (or directory for `images=data`). `images` (`info`/`data`) extracts image
233
446
  metadata or data alongside HTML. `frameHtml` extracts the current iframe document after `frame` routing. Screenshot
234
447
  accepts `clip` for coordinate-region capture, `compareWith` for PNG baseline comparison, and `diffOutput` for a PNG diff
235
- image. Screenshot responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`,
236
- `scale`, `clip`, and `capabilities`. PNG comparison is capped before decode at 25 MiB per PNG and 12,000,000 pixels; use
237
- `clip` or `scale` for larger captures. Hidden Extension tabs return `HIDDEN_TAB_SCREENSHOT` instead of auto-focusing the
238
- browser. If another debugger blocks the precise screenshot path, viewport fallback reports `degraded`, `fallback`, and
239
- `limitations`; unsupported fallback options return structured `SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns
240
- `interactiveElements`; `metadata` returns `frames` in both Extension and CDP modes. `tabId` targets a specific tab.
241
- `frame` targets an iframe. Both Extension mode only.
448
+ image. `diffOutput` requires `compareWith`. A `target` screenshot that has no match, whose `nth` is out of range, or
449
+ whose box has zero size returns a target error rather than silently returning a viewport screenshot. Screenshot
450
+ responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`, `scale`, `clip`, and
451
+ `capabilities`. Capture is limited to 16,384 pixels per side, 12,000,000 pixels total, 48 MiB estimated RGBA memory and
452
+ 25 MiB encoded data. PNG baselines are checked before reading; comparison is capped at 25 MiB per PNG and 12,000,000
453
+ pixels, and decompressed scanlines must exactly match the validated dimensions and are bounded during inflate. Malformed
454
+ or expansion-heavy PNGs are rejected. Use `clip` or `scale` for larger captures. Screenshot and diagnostic bundle
455
+ capabilities report `hiddenTabScreenshot: false` in both Extension and CDP modes. Hidden Extension tabs return
456
+ `HIDDEN_TAB_SCREENSHOT` without automatic activation. If another debugger blocks the precise screenshot path, viewport
457
+ fallback reports `degraded`, `fallback`, and `limitations`; unsupported fallback options return structured
458
+ `SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns `interactiveElements`; `metadata` returns `frames` in both
459
+ Extension and CDP modes. The document `url` is returned in both backends; Extension `frame` routing returns that iframe
460
+ document's URL. CDP frame entries retain declared fields as `null` when unavailable, including DOM selectors and owner
461
+ rectangles; frame-tree order and IDs are preserved. Metadata also returns the page's current `managed` state and a
462
+ `metadata` object with `createdBy`, `createdAt`, `lastUsedAt`, `taskHint`, and `note`, matching `browse list` and
463
+ `manage pageMetadata`. These notes describe the page even when `frame` selects an iframe document. They are local to the
464
+ current Server process; unknown creation provenance stays `unknown`, and another Server does not inherit the notes. They
465
+ are not cross-session ownership or permission evidence. Inline and file outputs include the same fields. `managed`
466
+ describes Extension page management; CDP returns false without restricting normal operations through the CDP connection.
467
+ `targetId` (or `tabId`) selects a page in either backend; `frame` is Extension-only.
242
468
 
243
469
  **`attribute` special prefix**: `computed:<property>` returns the computed CSS style value (e.g. `computed:color`,
244
470
  `computed:font-size`). Use `computed:*` to return all computed style properties as JSON (returns 300+ properties — use
@@ -251,35 +477,39 @@ browser. If another debugger blocks the precise screenshot path, viewport fallba
251
477
  ### wait - Wait for Conditions
252
478
 
253
479
  | For | Description |
254
- |--------------|-----------------------------------------------------|
480
+ | ------------ | --------------------------------------------------- |
255
481
  | `element` | Wait for element (visible/hidden/attached/detached) |
256
482
  | `navigation` | Wait for navigation complete |
257
483
  | `time` | Fixed delay |
258
- | `idle` | Wait for page load + DOM mutation quiet period |
484
+ | `idle` | Wait for DOM or network quiet period |
485
+
486
+ Parameters: `targetId` (or `tabId`) selects a page in either backend; `frame` selects an iframe in Extension mode.
259
487
 
260
- Parameters: `tabId` targets a specific tab. `frame` targets an iframe. Both Extension mode only.
488
+ In CDP mode, `visible` requires a nonzero DOM rectangle and CSS that does not hide the element (`display:none` or
489
+ `visibility:hidden/collapse`). `hidden` accepts these hidden states or a missing element; `attached` and `detached` only
490
+ check whether the element exists.
261
491
 
262
- **`idle`-specific**: After `readyState === 'complete'`, injects a `MutationObserver` and waits for a quiet period with
263
- no DOM changes. The `ms` parameter controls the quiet period duration (default 500ms). Returns `domStable: true` when
264
- the DOM settled, `domStable: false` if still mutating when the budget ran out.
492
+ **`idle`-specific**: In Extension mode, after `readyState === 'complete'`, it injects a `MutationObserver` and waits for
493
+ a quiet period with no DOM changes. In CDP mode, it waits for network quiet instead. `ms` controls the relevant quiet
494
+ period (default 500ms). The response returns `idleKind` and `idlePeriodMs`; Extension responses also return `domStable`.
265
495
 
266
496
  ### evaluate - JavaScript Execution
267
497
 
268
498
  Execute JavaScript in page context.
269
499
 
270
- | Parameter | Description |
271
- |-----------------|-----------------------------------------------------------------------------------------------------------------------------------|
272
- | `script` | JavaScript code. Bare `return` statements auto-wrapped in IIFE |
273
- | `scriptFile` | Read script from a local file (alternative to `script`, relative paths default to controlled temp dir, use `cwd:` for repo files) |
274
- | `args` | Arguments passed to script (script must be a function expression) |
275
- | `mode` | `precise` (default, debugger API) or `stealth` (JS injection) |
276
- | `staleContextRetry` | iframe stale-context policy: `never` (default) or `readOnly` |
277
- | `output` | Save result to file (relative paths default to controlled temp dir, use `cwd:` to persist in repo) |
278
- | `tabId` | Target a specific tab (Extension mode) |
279
- | `frame` | Target an iframe by CSS selector or index (Extension mode) |
280
- | `timeout` | End-to-end budget (ms) |
281
- | `diagnostics` | Return new console warnings/errors and failed network requests after execution |
282
- | `postCondition` | Wait for text, selector, URL fragment, or script result after execution |
500
+ | Parameter | Description |
501
+ | -------------------- | --------------------------------------------------------------------------------------------------- |
502
+ | `script` | JavaScript code. Bare `return` statements are wrapped in IIFE |
503
+ | `scriptFile` | Read code from a local file instead of `script` |
504
+ | `args` | Function arguments; `[]` invokes a zero-argument function, omission evaluates the script as written |
505
+ | `mode` | `precise` (default, debugger API) or `stealth` (JS injection) |
506
+ | `staleContextRetry` | iframe stale-context policy: `never` (default) or `readOnly` |
507
+ | `output` | Save the result to a file |
508
+ | `targetId` / `tabId` | Select a page in either backend (`tabId` is an alias) |
509
+ | `frame` | Target an iframe by CSS selector or index (Extension mode) |
510
+ | `timeout` | End-to-end budget (ms) |
511
+ | `diagnostics` | Return new console warnings/errors and failed requests after execution |
512
+ | `postCondition` | Wait for text, selector, URL fragment, or script result after execution |
283
513
 
284
514
  `script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
285
515
  paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
@@ -290,42 +520,103 @@ Results >100KB are auto-saved to the controlled OS temp directory with a structu
290
520
  `NodeList`, and `HTMLCollection` results return `NON_SERIALIZABLE_EVALUATE_RESULT` with a hint to return simple fields
291
521
  such as `textContent` or `outerHTML`. Result materialization and serialization failures report `actionExecuted=true`,
292
522
  `actionStatus="completed"`, and `failureStage="output"` because the page script has already finished. Evaluate defaults
293
- to `precise` even when global `inputMode` is `stealth`, and its
294
- `postCondition` checks use the same evaluate mode as the action. `postCondition` is optional; when it is not provided,
295
- `success=true` only means the script executed and returned. When it is provided and does not match before timeout, the
296
- tool returns `POST_CONDITION_FAILED` with the last observed checks. Precise iframe evaluation does not replay a script
297
- after a stale execution context by default. Set `staleContextRetry="readOnly"` only when the script has no side effects;
298
- the Extension may then resolve a new context and replay it once within the remaining timeout budget. A stale-context error after `Runtime.evaluate` reports `actionExecuted=true` and `actionStatus="unknown"`, because earlier side effects may already have happened even though the final result is unavailable.
523
+ to `precise` even when global `inputMode` is `stealth`, and its `postCondition` checks use the same evaluate mode as the
524
+ action. `postCondition` is optional; when it is not provided, `success=true` only means the script executed and
525
+ returned. When it is provided and does not match before timeout, the tool returns `POST_CONDITION_FAILED` with the last
526
+ observed checks. Precise iframe evaluation does not replay a script after a stale execution context by default. Set
527
+ `staleContextRetry="readOnly"` only when the script has no side effects; the Extension may then resolve a new context
528
+ and replay it once within the remaining timeout budget. A stale-context error after `Runtime.evaluate` reports
529
+ `actionExecuted=true` and `actionStatus="unknown"`, because earlier side effects may already have happened even though
530
+ the final result is unavailable.
531
+
532
+ For object results in the main frame with Extension precise mode, an explicit `output` uses a 16 Mi (16777216) character
533
+ budget. Without `output`, the 1000000-character budget still applies, including automatic saving. Both paths retain the
534
+ depth limit of 8, the 2000-node budget, and non-serializable result rejection. The character budget counts UTF-16 code
535
+ units, not the output file's UTF-8 bytes; `tmp:` files also remain subject to the temporary output quota. Exceeding a
536
+ result limit reports the current limit and the completed script's output failure without replaying it.
299
537
 
300
538
  ### manage - Page & Environment Management
301
539
 
302
- | Action | Description |
303
- |----------------|------------------------------------------------------------|
304
- | `newPage` | Create new controlled page/tab |
305
- | `closePage` | Close controlled page and return `affected.before/after` |
306
- | `adoptPage` | Mark an existing tab as controlled without focusing it |
307
- | `releasePage` | Remove a controlled tab from management without closing it |
308
- | `movePage` | Move a controlled tab to another window or index |
309
- | `reorderPage` | Reorder a controlled tab inside its window |
310
- | `pinPage` | Pin a controlled tab |
311
- | `unpinPage` | Unpin a controlled tab |
312
- | `activatePage` | Activate a controlled tab and focus its window |
313
- | `focusWindow` | Focus an explicit window |
314
- | `resizeWindow` | Resize or change state for an explicit window |
315
- | `newWindow` | Create a new controlled window |
316
- | `closeWindow` | Close a window only when all tabs are managed |
317
- | `clearCache` | Clear cache/storage (use `cookies` tool to clear cookies) |
318
- | `viewport` | Set viewport size |
319
- | `userAgent` | Set User-Agent |
320
- | `emulate` | Device emulation (iPhone, iPad, etc.) |
321
- | `inputMode` | Query or set input mode (`precise` / `stealth`) |
322
- | `stealth` | Inject anti-detection scripts |
323
- | `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
324
-
325
- Tab/window management actions are Extension-mode only. Actions that change visible browser state require explicit
326
- `targetId` or `windowId` and return `affected.before/after`. `focusWindow` only returns success after the target window
327
- is observed as focused; otherwise it returns `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with
328
- unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`.
540
+ | Action | Description |
541
+ | ------------------ | ----------------------------------------------------------------- |
542
+ | `newPage` | Create new controlled page/tab |
543
+ | `pageMetadata` | Read or update per-page `taskHint` and `note` |
544
+ | `closePage` | Close controlled page and return `affected.before/after` |
545
+ | `adoptPage` | Grant full controlled-page access without focusing it |
546
+ | `releasePage` | Remove a controlled tab from management without closing it |
547
+ | `grantReadAccess` | Grant ordinary reads for an explicit page to the calling instance |
548
+ | `revokeReadAccess` | Revoke that instance's ordinary read grant |
549
+ | `updatePage` | Update native tab properties and return actual state |
550
+ | `movePage` | Move a controlled tab to another window or index |
551
+ | `reorderPage` | Reorder a controlled tab inside its window |
552
+ | `pinPage` | Pin a controlled tab |
553
+ | `unpinPage` | Unpin a controlled tab |
554
+ | `activatePage` | Activate a controlled tab and focus its window |
555
+ | `focusWindow` | Focus an explicit window |
556
+ | `resizeWindow` | Resize or change state for an explicit window |
557
+ | `newWindow` | Create a new controlled window |
558
+ | `closeWindow` | Close a window only when all tabs are managed |
559
+ | `updateWindow` | Update native window position, state, focus or attention |
560
+ | `groupPages` | Create a group or add controlled tabs to an existing group |
561
+ | `ungroupPages` | Remove controlled tabs from groups without releasing them |
562
+ | `updateGroup` | Update group title, color and collapsed state |
563
+ | `moveGroup` | Move a group and its tabs to a window or index |
564
+ | `clearCache` | Clear cache/storage (use `cookies` tool to clear cookies) |
565
+ | `viewport` | Set viewport size |
566
+ | `userAgent` | Set User-Agent |
567
+ | `emulate` | Device emulation (iPhone, iPad, etc.) |
568
+ | `inputMode` | Query or set input mode (`precise` / `stealth`) |
569
+ | `stealth` | Inject anti-detection scripts |
570
+ | `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
571
+
572
+ Native tab/window/group configuration is Extension-mode only. Mutations identify their existing targets with `targetId`,
573
+ `targetIds`, `windowId`, or `groupId` and return `affected.before/after`. Group results also include
574
+ `tabsBefore/tabsAfter`; `ungroupPages` removes an empty group through Chrome without revoking the tabs' managed state.
575
+ Group title/color/collapse updates and group moves require all group members to be managed. Window updates, resizing,
576
+ and focusing require all window tabs to be managed; a cached MCP window ID does not override that check. `clearCache` is
577
+ unavailable in Extension mode and returns `UNSUPPORTED_MODE` without clearing anything. Use scoped
578
+ `cookies(action="clear")` for cookies or CDP mode for storage and cache. `focusWindow` only returns success after the
579
+ target window is observed as focused; otherwise it returns `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed
580
+ windows with unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`. Persistent `adoptPage` and `releasePage` target
581
+ changes are serialized with scoped tab operations, so a concurrent multi-event input remains on its requested tab and
582
+ the persistent target is applied afterward.
583
+
584
+ | Action | Native parameters | Behavior |
585
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
586
+ | `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 |
587
+ | `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 |
588
+ | `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` |
589
+ | `ungroupPages` | `targetIds` | Removes group membership and retains controlled-page access |
590
+ | `updateGroup` | `groupId`, `title`, `color`, `collapsed` | An empty title and false collapsed value are applied as supplied |
591
+ | `moveGroup` | `groupId`, `windowId`, `index` | Moves all members; `index=-1` means the end of the window |
592
+ | `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 |
593
+ | `updateWindow` / `resizeWindow` | `windowId`, `left`, `top`, `width`, `height`, `windowState`, `focused`, `drawAttention` | Applies supported Chrome window properties and returns observed state |
594
+
595
+ `updateWindow` and `resizeWindow` wait for a stable browser observation when changing state or geometry. Restoring a
596
+ non-normal window with `windowState="normal"` and bounds completes the state transition before applying bounds once.
597
+ OS-adjusted geometry is returned as observed. If observation does not stabilize within the bounded wait,
598
+ `WINDOW_UPDATE_NOT_OBSERVED` reports partial execution and the last observed window state; inspect `browse list` before
599
+ another update.
600
+
601
+ `browse list` defaults to `details="summary"`, returning target identity, URL/title, placement, managed/revision and
602
+ metadata. Set `details="full"` for highlighted/muted/discardable state, opener IDs and available native readonly
603
+ properties. False values are preserved. `targetIds` and `managedOnly=true` filter pages and their window/group
604
+ relations; `totalTargetCount`, `totalWindowCount` and `totalTabCount` distinguish inventory totals from selected counts.
605
+ Window objects reference pages through `targetIds` rather than repeating full targets. Inline favicon data URLs are
606
+ omitted; full details use `favIconInline=true` to indicate one exists. Groups retain title, color, collapsed/shared
607
+ state, window, first-member index and member IDs. Color belongs to a group, not a tab. Readonly properties are returned
608
+ when Chrome supplies them, not accepted as configuration writes. Listing does not read page content, navigate or focus.
609
+
610
+ Moving tabs/groups accepts `index=-1`; page creation requires a nonnegative index. Opener and explicit group/window
611
+ options must identify the same window. Pinned tabs cannot be created inside a group. Window state/bounds conflicts and
612
+ action-inappropriate fields are rejected before mutation. CDP rejects unsupported Chrome UI options rather than ignoring
613
+ them. `url` and `urls` are alternative inputs for `newWindow`; either can accompany `targetId` in a `normal` window. A
614
+ `popup` accepts a single URL or one existing tab, without additional URLs. Known preflight rejections retain
615
+ `actionExecuted=false`, `actionStatus="not_started"`, and `failureStage="preflight"`; rejected updates preserve the page
616
+ revision. Once a native update has been dispatched, a failure still invalidates that revision.
617
+
618
+ `emulate` applies the device viewport, pixel density, touch support, and User-Agent in both backends. `viewport`
619
+ restores desktop metrics, page scale, and disabled touch emulation; restore the User-Agent separately with `userAgent`.
329
620
 
330
621
  **Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
331
622
 
@@ -336,30 +627,41 @@ unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`.
336
627
  ### logs - Browser Logs
337
628
 
338
629
  | Type | Description |
339
- |-----------|----------------------------------------|
630
+ | --------- | -------------------------------------- |
340
631
  | `console` | Console logs (with level filter) |
341
632
  | `network` | Network request logs (with URL filter) |
342
633
 
343
- Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and `debug`;
344
- raw browser levels such as `warn` and `log` are normalized before filtering and return. Network logs include completed
345
- requests, HTTP 4xx/5xx responses, and failed loads with `errorText`, `method`, `url`, `status`, `timestamp`, and `duration`
346
- when available. URL query parameters commonly used for credentials, signatures, passwords, and tokens are replaced with
347
- `[REDACTED]` in inline responses, diagnostics, and explicit `output` files. Redacted entries include `urlRedacted`,
348
- `urlOriginalLength`, and `redactedQueryParameters`. Inline network results limit each sanitized URL to 2048 characters and
349
- add `urlLength` plus `urlTruncated: true` when shortened. `urlPattern` supports `*` for any number of characters and `?`
350
- for one character. `tabId` targets a specific tab (Extension mode). `frame` is not applicable for logs.
634
+ Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and
635
+ `debug`; raw browser levels such as `warn` and `log` are normalized before filtering and return. Clearing fallback
636
+ console logs keeps the hook active. When debugger collection becomes available, fallback capture is disabled. Console
637
+ methods still pointing to the MCP wrapper are restored, while wrappers installed later by the page are preserved.
638
+ Network logs are finalized on `loadingFinished` or `loadingFailed`, not when headers arrive, so body failures retain
639
+ both the HTTP status and `errorText`, and in-flight bodies continue to count against `networkidle`. Entries include
640
+ `method`, `url`, `status`, `timestamp`, and `duration` when available. URL query parameters commonly used for
641
+ credentials, signatures, passwords, and tokens are replaced with `[REDACTED]` in inline responses, diagnostics, and
642
+ explicit `output` files. Redacted entries include `urlRedacted`, `urlOriginalLength`, and `redactedQueryParameters`.
643
+ Inline network results limit each sanitized URL to 2048 characters and add `urlLength` plus `urlTruncated: true` when
644
+ shortened. `urlPattern` supports `*` for any number of characters and `?` for one character. `tabId` targets a specific
645
+ tab (Extension mode). `frame` is not applicable for logs.
646
+
647
+ When the Extension debugger is unavailable, network reads refresh performance entries and mark them with
648
+ `source="performance"`. Status uses the browser's `responseStatus` when available, or `0` otherwise; unknown request
649
+ methods remain empty. Repeated reads preserve record sequences. `clear` clears MCP records and advances the current
650
+ document's read boundary without clearing the page's shared performance timeline. A new document starts a new boundary.
651
+ Read failures return an error rather than an empty log.
351
652
 
352
653
  ### cookies - Cookie Management
353
654
 
354
- | Action | Description |
355
- |----------|---------------------------------------------------------------|
356
- | `get` | Get cookies |
357
- | `set` | Set cookie |
358
- | `delete` | Delete cookie |
359
- | `clear` | Delete cookies by filter (`name`/`domain`/`url`, ≥1 required) |
655
+ | Action | Description |
656
+ | -------- | ---------------------------------------------------------------------- |
657
+ | `get` | Get cookies |
658
+ | `set` | Set cookie |
659
+ | `delete` | Delete cookie |
660
+ | `clear` | Delete cookies in a URL or domain scope, optionally narrowed by `name` |
360
661
 
361
- **Note**: `clear` requires at least one of `name`, `domain`, or `url` to filter — calling without any filter is rejected
362
- to avoid wiping the user's login cookies.
662
+ **Note**: `clear` requires `url` or `domain`. `name` can only further narrow that scope, so a same-named cookie on
663
+ another site cannot be removed accidentally. The returned `count` includes only cookies for which Chrome confirms a
664
+ removal; cookies that disappear between listing and removal are not counted.
363
665
 
364
666
  ## Target: Unified Element Locator
365
667
 
@@ -367,57 +669,43 @@ All tools use a unified `Target` type for element location:
367
669
 
368
670
  ```typescript
369
671
  // By accessibility (recommended - most stable)
370
- { role: "button", name: "Submit" }
672
+ const byRole = { role: 'button', name: 'Submit' }
371
673
 
372
674
  // By accessibility with exact accessible name
373
- { role: "button", name: "Submit", exact: true }
675
+ const byExactRole = { role: 'button', name: 'Submit', exact: true }
374
676
 
375
677
  // By text content
376
- { text: "Click here", exact: true }
678
+ const byText = { text: 'Click here', exact: true }
377
679
 
378
680
  // By form label
379
- {
380
- label: "Email"
381
- }
681
+ const byLabel = { label: 'Email' }
382
682
 
383
683
  // By placeholder
384
- {
385
- placeholder: "Enter your name"
386
- }
684
+ const byPlaceholder = { placeholder: 'Enter your name' }
387
685
 
388
686
  // By title attribute
389
- {
390
- title: "Close dialog"
391
- }
687
+ const byTitle = { title: 'Close dialog' }
392
688
 
393
689
  // By alt text (images)
394
- {
395
- alt: "Profile picture"
396
- }
690
+ const byAlt = { alt: 'Profile picture' }
397
691
 
398
692
  // By test ID
399
- {
400
- testId: "submit-button"
401
- }
693
+ const byTestId = { testId: 'submit-button' }
402
694
 
403
695
  // By CSS selector
404
- {
405
- css: "#login-form .submit-btn"
406
- }
696
+ const byCss = { css: '#login-form .submit-btn' }
407
697
 
408
698
  // Disambiguate multiple matches (0-based)
409
- { css: ".ant-select-input", nth: 1 }
699
+ const secondMatch = { css: '.ant-select-input', nth: 1 }
410
700
 
411
701
  // By CSS + text (filter by text content)
412
- { css: "button", text: "Submit", exact: true }
702
+ const byCssText = { css: 'button', text: 'Submit', exact: true }
413
703
 
414
704
  // By XPath
415
- {
416
- xpath: "//button[@type='submit']"
417
- }
705
+ const byXPath = { xpath: "//button[@type='submit']" }
418
706
 
419
707
  // By coordinates
420
- { x: 100, y: 200 }
708
+ const byCoordinates = { x: 100, y: 200 }
421
709
  ```
422
710
 
423
711
  ## Usage Examples
@@ -481,12 +769,30 @@ extract(type="html", target={ css: ".article" }, images="info")
481
769
 
482
770
  // Get HTML + image data, save to directory
483
771
  extract(type="html", images="data", output="tmp:page")
484
- // Creates: <system-temp>/claude-tools/mcp-chrome/page/content.html, images/*, index.json
772
+ // Creates: <system-temp>/claude-tools/mcp-chrome/session-<id>/page/content.html, images/*, index.json
485
773
 
486
774
  // Get HTML + image data inline (max 20 images)
487
775
  extract(type="html", target={ css: ".card" }, images="data")
488
776
  ```
489
777
 
778
+ `tmp:` paths belong to the current server session. Temporary output has a 256-entry and 128 MiB session limit; on
779
+ startup, marked sessions older than 24 hours are removed only after their process exits. Use `cwd:` for files that must
780
+ remain accessible after restarting the server. Successful responses that save a `tmp:` file or directory include a
781
+ `retention` field describing the cleanup condition; `cwd:` responses omit it. Output paths reject Windows reserved
782
+ device names, alternate data streams, invalid characters, and trailing spaces or dots. On Windows, private file
783
+ permissions must be verified before writing sensitive content.
784
+
785
+ Invalid path syntax returns `INVALID_ARGUMENT`; `.` components are accepted and `..` components remain rejected. Paths
786
+ outside an allowed root, including symlink escapes, return `PATH_NOT_ALLOWED`. Both errors include the server's actual
787
+ working directory as `error.context.cwd`; scope rejections also include `allowedRoots`. Use `cwd:` with a path relative
788
+ to that directory, or `tmp:` for session output. These checks also apply to `scriptFile` and `compareWith`.
789
+
790
+ Quota rejection returns `TEMP_OUTPUT_QUOTA_EXCEEDED` with `limits`, `usage`, `remaining`, `requested`, and `projected`
791
+ in `error.context`. If `usage.complete` is false, usage is an observed lower bound and `remaining`/`projected` are null.
792
+ Existing output is preserved. An evaluate output failure retains `actionExecuted=true`, `actionStatus=completed`,
793
+ `failureStage=output`, and `retryable=false`; the script is not replayed. Use a repository-relative `cwd:` path for
794
+ subsequent output.
795
+
490
796
  ### Page Metadata
491
797
 
492
798
  ```
@@ -511,7 +817,21 @@ input(events=[
511
817
  ], frame="iframe.login-frame")
512
818
  ```
513
819
 
514
- Selectors and numeric indices follow the parent document's DOM iframe order. Subframes absent from that DOM, including frames added by other extensions, cannot shift the index or become fallback targets. If the selected element cannot be tied to exactly one Chrome frame, the operation returns `FRAME_IDENTITY_UNAVAILABLE` instead of choosing another frame.
820
+ Selectors and numeric indices follow the parent document's DOM iframe order. Subframes absent from that DOM, including
821
+ frames added by other extensions, cannot shift the index or become fallback targets. If the selected element cannot be
822
+ tied to exactly one Chrome frame, the operation returns `FRAME_IDENTITY_UNAVAILABLE` instead of choosing another frame.
823
+ Precise evaluation matches the complete iframe URL, including query strings and fragments, and uses the selected DOM
824
+ iframe to distinguish frames with the same URL, including `about:srcdoc`. It rejects the operation when that identity
825
+ cannot be confirmed.
826
+
827
+ Frame selection failures return `INVALID_FRAME_SELECTOR`, `FRAME_NOT_IFRAME`, or `FRAME_NOT_FOUND`. Read injections
828
+ report `INVALID_SELECTOR`, `FRAME_STALE_CONTEXT`, `FRAME_INJECTION_DENIED`, `FRAME_SCRIPT_FAILED`,
829
+ `FRAME_INJECTION_FAILED`, or `FRAME_SCRIPT_NO_RESULT`, with the injection or script-result phase. A missing result does
830
+ not establish that the selector is invalid. Empty text, empty element arrays, null attribute values, and void script
831
+ calls keep their existing meaning; errors do not replay the script. When a read fails after resolving a frame,
832
+ `pageContext.frameContext` retains its selected DOM index, Chrome frame ID, and available document identity. Frame URL
833
+ diagnostics remove credentials, query strings, and fragments and are limited to 500 characters. `data:` and
834
+ `javascript:` URLs expose only the protocol; an unparseable URL reports `url=null` and `urlStatus="unavailable"`.
515
835
 
516
836
  ### Wait for Element
517
837
 
@@ -601,8 +921,8 @@ mcp-chrome/
601
921
 
602
922
  ## Security Notes
603
923
 
604
- - **Trust boundary**: Extension mode auto-connects to local MCP servers by default. Use `MCP_CHROME_PAIRING_TOKEN`, or set
605
- `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`, on multi-user systems, CI runners, or containers with `--net=host` where
924
+ - **Trust boundary**: Extension mode auto-connects to local MCP servers by default. Use `MCP_CHROME_PAIRING_TOKEN`, or
925
+ set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`, on multi-user systems, CI runners, or containers with `--net=host` where
606
926
  untrusted code can reach `127.0.0.1:19222-19299`. WebSocket upgrades require a `chrome-extension://` Origin header,
607
927
  which blocks browser pages and curl, but does not stop a malicious local process running as the same user.
608
928
  - Extension mode: shares your browser sessions — only use on trusted machines
@@ -610,7 +930,8 @@ mcp-chrome/
610
930
  - Default ports bind to 127.0.0.1 only (localhost)
611
931
  - The `evaluate` tool can execute arbitrary JavaScript
612
932
  - The `manage cdp` action can send arbitrary CDP commands
613
- - Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still contain sensitive information
933
+ - Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still
934
+ contain sensitive information
614
935
 
615
936
  ### Anti-detection (stealth) — what it actually does
616
937
 
@@ -618,10 +939,11 @@ The `stealth` mode (`safe` / `aggressive`) only patches a small set of fingerpri
618
939
 
619
940
  - **Covers**: `navigator.webdriver`, `cdc_*` properties, User-Agent string, a few WebGL vendor/renderer values, Chrome
620
941
  runtime properties
621
- - **Does NOT cover**: Canvas fingerprinting, AudioContext fingerprinting, Font enumeration, TLS-level fingerprints (
622
- JA3/JA4), CDP attach banner ("Chrome is being controlled by automated software"), Extension presence detection
623
- - **Warning**: Do NOT rely on this to bypass commercial anti-bot services (Cloudflare Turnstile, Akamai, DataDome,
624
- PerimeterX). Real bot detection happens at multiple layers we cannot patch from inside the page
942
+ - **Does NOT cover**: Canvas fingerprinting, AudioContext fingerprinting, Font enumeration, TLS-level fingerprints
943
+ (JA3/JA4), CDP attach banner ("Chrome is being controlled by automated software"), Extension presence detection
944
+ - **Warning**: These patches do not pass Cloudflare. JS Challenge and Turnstile checkbox handling is a separate wait in
945
+ the real browser after navigation, input, or evaluate. It does not cover Akamai, DataDome, PerimeterX, interactive
946
+ CAPTCHAs, or IP reputation
625
947
 
626
948
  ## Known Limitations
627
949
 
@@ -639,9 +961,41 @@ MIT License - see [LICENSE](LICENSE) for details.
639
961
  - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
640
962
  - [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP documentation
641
963
 
642
-
643
964
  ## Operation status and diagnostics
644
965
 
645
- Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and `retryable`. Verification uses `matched`, `not_matched`, `unavailable`, or `error`; debugger timeouts report the action as `unknown` when completion cannot be proven. Page-thrown exceptions report `actionExecuted=true` with `actionStatus="failed"`; result materialization or serialization errors report `actionStatus="completed"` and `failureStage="output"`. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action result. Browse and wait errors also retain any diagnostics collected before the action failed. Target diagnostics query the current tab state instead of relying on cached attach metadata.
646
-
647
- `replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other input types use a native full-value update and return the requested and actual browser-normalized values. A standalone `select` on unsupported types returns `UNSUPPORTED_SELECTION`. CDP locator targets for `select` and `replace` are focused through the CDP locator instead of Extension-only ref IDs. Password values are omitted from input failure context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text` values. Target timeouts include bounded locator, tab, frame, match, and candidate context. Explicit `tabId` and `frame` scopes resolve the active backend before input, wait, logs, or extract work begins, so actions and verification use the same target backend. Precise iframe evaluation defaults to `staleContextRetry="never"` and does not replay stale scripts. `readOnly` permits one replay after the Extension verifies the frame identity and resolves a new execution context. Responses include the policy, `retryAttempted`, bounded `retryReason`, and the final `frameContext` with the Extension frame, parent frame, URL, CDP frame, and execution context IDs. Ambiguous same-URL frames are rejected. Port scanning aggregates ordinary pre-open failures at debug level; authentication and protocol rejections from identified MCP servers produce one bounded warning when the rejection summary changes.
966
+ Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and
967
+ `retryable`. Verification uses `matched`, `not_matched`, `unavailable`, or `error`; debugger timeouts report the action
968
+ as `unknown` when completion cannot be proven. Page-thrown exceptions report `actionExecuted=true` with
969
+ `actionStatus="failed"`; result materialization or serialization errors report `actionStatus="completed"` and
970
+ `failureStage="output"`. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action
971
+ result. On a page precondition mismatch, input and evaluate report `actionExecuted=false` and
972
+ `actionStatus="not_started"`. Browse and wait errors also retain any diagnostics collected before the action failed.
973
+ Target diagnostics query the current tab state instead of relying on cached attach metadata.
974
+
975
+ Native script termination and `Internal error` responses from CDP `Runtime` script commands preserve the original error
976
+ code. evaluate and `manage cdp` return `actionExecuted=true`, `actionStatus="unknown"`, and `retryable=false` without
977
+ replaying the command. evaluate also returns `retryable=false` when an in-flight RPC timeout or stale execution context
978
+ leaves the result unknown; timeouts before execution starts remain retryable. Page-thrown exceptions with the same text
979
+ remain action failures.
980
+
981
+ Extension accessibility state does not read password values to generate element names. Labels, placeholders, titles, and
982
+ ordinary input values remain available. Explicit script, HTML, and attribute reads retain their existing behavior.
983
+
984
+ `replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other
985
+ input types use a native full-value update and return the requested and actual browser-normalized values. A standalone
986
+ `select` on unsupported types returns `UNSUPPORTED_SELECTION`. CDP locator targets for `select` and `replace` are
987
+ focused through the CDP locator instead of Extension-only ref IDs. Password values are omitted from input failure
988
+ context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text`
989
+ values. Password `select`/`replace` responses hide console and network diagnostic bodies on success and failure,
990
+ returning `diagnostics.redacted=true` with `reason="sensitive_input_or_unresolved_target"`. This also applies when a
991
+ selection target cannot be identified safely. Ordinary input retains its diagnostics; password protection lasts for the
992
+ current input request. Target timeouts include bounded locator, tab, frame, match, and candidate context. Explicit
993
+ `tabId` and `frame` scopes resolve the active backend before input, wait, logs, or extract work begins, so actions and
994
+ verification use the same target backend. Precise iframe evaluation defaults to `staleContextRetry="never"` and does not
995
+ replay stale scripts. `readOnly` permits one replay after the Extension verifies the frame identity and resolves a new
996
+ execution context. Responses include the policy, `retryAttempted`, bounded `retryReason`, and the final `frameContext`
997
+ with the Extension frame, parent frame, URL, CDP frame, and execution context IDs. Same-URL frames are rejected only
998
+ when the selected DOM iframe cannot identify one target. Existing iframe targets remain usable after an Extension reload
999
+ without refreshing or navigating the page. Port scanning aggregates ordinary pre-open failures at debug level;
1000
+ authentication and protocol rejections from identified MCP servers produce one bounded warning when the rejection
1001
+ summary changes.