@pyrokine/mcp-chrome 3.0.1 → 3.1.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 (150) hide show
  1. package/README.md +1060 -432
  2. package/README_zh.md +936 -349
  3. package/dist/cdp/client.d.ts +8 -3
  4. package/dist/cdp/client.d.ts.map +1 -1
  5. package/dist/cdp/client.js +260 -63
  6. package/dist/cdp/client.js.map +1 -1
  7. package/dist/cdp/launcher.d.ts +1 -1
  8. package/dist/cdp/launcher.d.ts.map +1 -1
  9. package/dist/cdp/launcher.js +33 -12
  10. package/dist/cdp/launcher.js.map +1 -1
  11. package/dist/core/auto-wait.d.ts.map +1 -1
  12. package/dist/core/auto-wait.js +88 -52
  13. package/dist/core/auto-wait.js.map +1 -1
  14. package/dist/core/browser-driver.d.ts +73 -15
  15. package/dist/core/browser-driver.d.ts.map +1 -1
  16. package/dist/core/browser-driver.js.map +1 -1
  17. package/dist/core/browser-event-schema.d.ts +287 -0
  18. package/dist/core/browser-event-schema.d.ts.map +1 -0
  19. package/dist/core/browser-event-schema.js +104 -0
  20. package/dist/core/browser-event-schema.js.map +1 -0
  21. package/dist/core/browser-events.d.ts +105 -0
  22. package/dist/core/browser-events.d.ts.map +1 -0
  23. package/dist/core/browser-events.js +1482 -0
  24. package/dist/core/browser-events.js.map +1 -0
  25. package/dist/core/challenge-page.d.ts +39 -0
  26. package/dist/core/challenge-page.d.ts.map +1 -0
  27. package/dist/core/challenge-page.js +231 -0
  28. package/dist/core/challenge-page.js.map +1 -0
  29. package/dist/core/dom-helpers.d.ts +28 -0
  30. package/dist/core/dom-helpers.d.ts.map +1 -0
  31. package/dist/core/dom-helpers.js +311 -0
  32. package/dist/core/dom-helpers.js.map +1 -0
  33. package/dist/core/error-sanitizer.d.ts.map +1 -1
  34. package/dist/core/error-sanitizer.js +2 -1
  35. package/dist/core/error-sanitizer.js.map +1 -1
  36. package/dist/core/errors.d.ts +4 -0
  37. package/dist/core/errors.d.ts.map +1 -1
  38. package/dist/core/errors.js +57 -9
  39. package/dist/core/errors.js.map +1 -1
  40. package/dist/core/file-upload.d.ts +22 -0
  41. package/dist/core/file-upload.d.ts.map +1 -0
  42. package/dist/core/file-upload.js +194 -0
  43. package/dist/core/file-upload.js.map +1 -0
  44. package/dist/core/locator.d.ts +11 -2
  45. package/dist/core/locator.d.ts.map +1 -1
  46. package/dist/core/locator.js +135 -206
  47. package/dist/core/locator.js.map +1 -1
  48. package/dist/core/os-mouse.d.ts +11 -0
  49. package/dist/core/os-mouse.d.ts.map +1 -1
  50. package/dist/core/os-mouse.js +104 -29
  51. package/dist/core/os-mouse.js.map +1 -1
  52. package/dist/core/retry.d.ts.map +1 -1
  53. package/dist/core/retry.js +4 -1
  54. package/dist/core/retry.js.map +1 -1
  55. package/dist/core/session.d.ts +62 -12
  56. package/dist/core/session.d.ts.map +1 -1
  57. package/dist/core/session.js +1174 -304
  58. package/dist/core/session.js.map +1 -1
  59. package/dist/core/types.d.ts +5 -1
  60. package/dist/core/types.d.ts.map +1 -1
  61. package/dist/core/types.js +16 -1
  62. package/dist/core/types.js.map +1 -1
  63. package/dist/core/unified-session.d.ts +48 -37
  64. package/dist/core/unified-session.d.ts.map +1 -1
  65. package/dist/core/unified-session.js +982 -294
  66. package/dist/core/unified-session.js.map +1 -1
  67. package/dist/core/utils.d.ts +8 -4
  68. package/dist/core/utils.d.ts.map +1 -1
  69. package/dist/core/utils.js +76 -18
  70. package/dist/core/utils.js.map +1 -1
  71. package/dist/extension/bridge.d.ts +48 -17
  72. package/dist/extension/bridge.d.ts.map +1 -1
  73. package/dist/extension/bridge.js +288 -46
  74. package/dist/extension/bridge.js.map +1 -1
  75. package/dist/extension/http-server.d.ts +8 -2
  76. package/dist/extension/http-server.d.ts.map +1 -1
  77. package/dist/extension/http-server.js +211 -49
  78. package/dist/extension/http-server.js.map +1 -1
  79. package/dist/index.js +15 -1
  80. package/dist/index.js.map +1 -1
  81. package/dist/tools/browse.d.ts.map +1 -1
  82. package/dist/tools/browse.js +56 -28
  83. package/dist/tools/browse.js.map +1 -1
  84. package/dist/tools/browser-event-output.d.ts +7 -0
  85. package/dist/tools/browser-event-output.d.ts.map +1 -0
  86. package/dist/tools/browser-event-output.js +19 -0
  87. package/dist/tools/browser-event-output.js.map +1 -0
  88. package/dist/tools/challenge.d.ts +18 -5
  89. package/dist/tools/challenge.d.ts.map +1 -1
  90. package/dist/tools/challenge.js +217 -200
  91. package/dist/tools/challenge.js.map +1 -1
  92. package/dist/tools/cookies.d.ts.map +1 -1
  93. package/dist/tools/cookies.js +34 -8
  94. package/dist/tools/cookies.js.map +1 -1
  95. package/dist/tools/diagnostics.d.ts.map +1 -1
  96. package/dist/tools/diagnostics.js +15 -0
  97. package/dist/tools/diagnostics.js.map +1 -1
  98. package/dist/tools/evaluate.d.ts +6 -5
  99. package/dist/tools/evaluate.d.ts.map +1 -1
  100. package/dist/tools/evaluate.js +94 -52
  101. package/dist/tools/evaluate.js.map +1 -1
  102. package/dist/tools/extract.d.ts.map +1 -1
  103. package/dist/tools/extract.js +293 -153
  104. package/dist/tools/extract.js.map +1 -1
  105. package/dist/tools/input.d.ts.map +1 -1
  106. package/dist/tools/input.js +747 -282
  107. package/dist/tools/input.js.map +1 -1
  108. package/dist/tools/logs.d.ts.map +1 -1
  109. package/dist/tools/logs.js +50 -11
  110. package/dist/tools/logs.js.map +1 -1
  111. package/dist/tools/manage.d.ts.map +1 -1
  112. package/dist/tools/manage.js +123 -18
  113. package/dist/tools/manage.js.map +1 -1
  114. package/dist/tools/network-sanitizer.d.ts +2 -0
  115. package/dist/tools/network-sanitizer.d.ts.map +1 -1
  116. package/dist/tools/network-sanitizer.js +53 -10
  117. package/dist/tools/network-sanitizer.js.map +1 -1
  118. package/dist/tools/page-context.d.ts +4 -3
  119. package/dist/tools/page-context.d.ts.map +1 -1
  120. package/dist/tools/page-context.js +57 -14
  121. package/dist/tools/page-context.js.map +1 -1
  122. package/dist/tools/png.d.ts.map +1 -1
  123. package/dist/tools/png.js +12 -3
  124. package/dist/tools/png.js.map +1 -1
  125. package/dist/tools/post-condition.d.ts +1 -1
  126. package/dist/tools/post-condition.d.ts.map +1 -1
  127. package/dist/tools/post-condition.js +163 -47
  128. package/dist/tools/post-condition.js.map +1 -1
  129. package/dist/tools/schema.d.ts +7 -4
  130. package/dist/tools/schema.d.ts.map +1 -1
  131. package/dist/tools/schema.js +32 -122
  132. package/dist/tools/schema.js.map +1 -1
  133. package/dist/tools/target-diagnostics.d.ts +3 -3
  134. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  135. package/dist/tools/target-diagnostics.js +64 -34
  136. package/dist/tools/target-diagnostics.js.map +1 -1
  137. package/dist/tools/wait.d.ts.map +1 -1
  138. package/dist/tools/wait.js +94 -40
  139. package/dist/tools/wait.js.map +1 -1
  140. package/extension/dist/assets/{content.ts-qe6IB5DK.js → content.ts-C9QgtUYe.js} +1 -1
  141. package/extension/dist/assets/{content.ts-loader-DUWbDHRS.js → content.ts-loader-yqB_P8vu.js} +1 -1
  142. package/extension/dist/assets/index.ts-DBFNh8mZ.js +20275 -0
  143. package/extension/dist/assets/{page-scripts-D508WLkW.js → page-scripts-BjqQ0zXt.js} +258 -367
  144. package/extension/dist/assets/{popup.html-B-eVq48O.js → popup.html-DwwHo00N.js} +2 -2
  145. package/extension/dist/manifest.json +4 -4
  146. package/extension/dist/service-worker-loader.js +1 -1
  147. package/extension/dist/src/popup/popup.html +3 -3
  148. package/package.json +9 -7
  149. package/scripts/start-chrome.ps1 +9 -1
  150. package/extension/dist/assets/index.ts-D7_LCUoV.js +0 -9319
package/README.md CHANGED
@@ -15,7 +15,8 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
15
15
  - **8 Unified Tools**: Action-based design covering browse, input, extract, wait, evaluate, manage, cookies, logs
16
16
  - **Multi-Page Targeting**: `targetId` selects a page in either backend without changing browser focus; `tabId` remains
17
17
  an alias
18
- - **iframe Penetration**: `frame` parameter targets elements inside iframes (CSS selector or index, Extension mode)
18
+ - **Frames and Shadow DOM**: `frame` selects a child frame or a nested selector/index path in either backend; CSS, text
19
+ and semantic queries enter open shadow roots
19
20
  - **Semantic Targeting**: 11 ways to locate elements (role, text, label, CSS, CSS+text combo, XPath, coordinates, etc.)
20
21
  - **Auto-Wait**: Built-in clickability and input-ready detection with deadline-based timeout budget
21
22
  - **Dual Input Mode**: `precise` (debugger API, bypasses CSP) or `stealth` (JS injection, no debug banner)
@@ -38,37 +39,6 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
38
39
  Local zero-config auto-connect is unchanged. Reloading the Extension or restarting the MCP client does not require a
39
40
  manual Connect click.
40
41
 
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
-
62
- ## Compatible Clients
63
-
64
- | Client | Status |
65
- | ------------------------- | ------ |
66
- | Claude Code | ✅ |
67
- | Claude Desktop | ✅ |
68
- | Cursor | ✅ |
69
- | Windsurf | ✅ |
70
- | Any MCP-compatible client | ✅ |
71
-
72
42
  ## Installation
73
43
 
74
44
  Requires Node.js 20.19 or newer.
@@ -98,6 +68,21 @@ claude mcp add chrome -- node "$PWD/dist/index.js"
98
68
 
99
69
  For Extension mode, load `extension/dist` in Chrome.
100
70
 
71
+ ### Other MCP clients
72
+
73
+ For Claude Desktop and other clients, use this configuration with the actual Server entry path:
74
+
75
+ ```json
76
+ {
77
+ "mcpServers": {
78
+ "chrome": {
79
+ "command": "node",
80
+ "args": ["/path/to/mcp-chrome/dist/index.js"]
81
+ }
82
+ }
83
+ }
84
+ ```
85
+
101
86
  ### Windows CDP launch
102
87
 
103
88
  Chrome discovery checks Windows App Paths, `PATH`, installed Chrome channels, Chromium, Chrome for Testing, and
@@ -106,7 +91,8 @@ Chrome discovery checks Windows App Paths, `PATH`, installed Chrome channels, Ch
106
91
  ```powershell
107
92
  & '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
108
93
  # 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'
94
+ & '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222 `
95
+ -ExecutablePath 'C:\Browsers\chrome.exe' -ProfileDir 'C:\Temp\mcp-chrome-profile'
110
96
  ```
111
97
 
112
98
  Then call `browse(action="connect", port=9222)`. The script keeps its Chrome process in the foreground; Chrome exit
@@ -117,66 +103,22 @@ launch.
117
103
 
118
104
  ### Mode 1: Extension Mode (Recommended)
119
105
 
120
- Extension mode controls your existing Chrome — shares login sessions, cookies, and browsing context.
121
-
122
- **Step 1: Install Chrome Extension**
123
-
124
- 1. Open `chrome://extensions/` in Chrome
125
- 2. Enable "Developer mode" (top-right toggle)
126
- 3. Click "Load unpacked" → select `mcp-chrome/extension/dist/` directory
127
- 4. The MCP Chrome icon appears in the toolbar
128
-
129
- **Step 2: Configure MCP Client**
130
-
131
- ```bash
132
- # npm installation
133
- claude mcp add chrome -- mcp-chrome
134
-
135
- # source build
136
- claude mcp add chrome -- node /path/to/mcp-chrome/dist/index.js
137
- ```
138
-
139
- Claude Desktop / Other Clients:
140
-
141
- ```json
142
- {
143
- "mcpServers": {
144
- "chrome": {
145
- "command": "node",
146
- "args": ["/path/to/mcp-chrome/dist/index.js"]
147
- }
148
- }
149
- }
150
- ```
151
-
152
- **Step 3: Connect**
153
-
154
- The Extension auto-connects to the MCP Server via HTTP/WebSocket (port 19222-19299). Click the toolbar icon to verify
155
- connection status. `browse(action="connect")` and the local `/api/info` endpoint report the active Extension background
156
- bundle hash and compare it with the bundle shipped beside the server. `bundleStatus="stale"` means Chrome is still
157
- running an older unpacked Extension bundle; reload the Extension in `chrome://extensions/`. A legacy Extension that
158
- lacks `network_challenge_state` falls back to tab-title and DOM challenge detection. Bundle identity never disables
159
- zero-config auto-connect.
160
-
161
- ```
162
- browse(action="list") // List all tabs
163
- browse(action="open", url="https://example.com")
164
- extract(type="screenshot")
165
- ```
166
-
167
- **Pairing token**
106
+ After [installation](#installation), the Extension connects to local MCP servers automatically over HTTP/WebSocket on
107
+ ports 19222-19299. It uses your existing Chrome sessions and cookies; ordinary local use needs no manual pairing or
108
+ Connect click.
168
109
 
169
- Extension mode keeps zero-config local auto-connect by default. On shared machines, CI runners, or containers where
170
- untrusted local processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the MCP server and enter
171
- the same token in the Extension popup:
110
+ List pages first and reuse a suitable managed page by its task name and notes. If none exists, create a temporary
111
+ example page in an existing window. Use its returned `targetId` for the read and close only that created page:
172
112
 
173
- ```bash
174
- MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
113
+ ```text
114
+ browse(action="list")
115
+ manage(action="newPage", url="https://example.com", taskHint="Read example", note="Temporary example page")
116
+ extract(type="text", targetId="CREATED_TARGET_ID")
117
+ manage(action="closePage", targetId="CREATED_TARGET_ID")
175
118
  ```
176
119
 
177
- To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server
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.
120
+ See [Connection status and recovery](#connection-status-and-recovery) for build identity and reconnection, and
121
+ [Pairing and local access](#pairing-and-local-access) for token-enforced environments.
180
122
 
181
123
  ### Mode 2: CDP Mode (Fallback)
182
124
 
@@ -198,65 +140,73 @@ browse(action="open", url="https://example.com")
198
140
  > return to Extension mode. A CDP connection created only as fallback yields to Extension after the Extension
199
141
  > reconnects.
200
142
 
201
- ## Available Tools (8 Tools)
143
+ ## Target: Unified Element Locator
202
144
 
203
- ### browse - Browser Management & Navigation
145
+ All tools use a unified `Target` type for element location. CSS, text, role and label queries traverse open shadow roots
146
+ in stable order; XPath retains native document-tree semantics. `aria-labelledby` uses IDs from the element's own tree,
147
+ preserves multiple-reference order and takes precedence over `aria-label`. Content-named roles such as `tab`, `checkbox`
148
+ and `menuitem` include visible descendant text, including nested spans. State names use the same rules; ordinary inputs
149
+ retain their current values in `value` and `pageContent`, separately from their names. Password, hidden and file input
150
+ values are not read by state extraction. Closed shadow roots remain outside Extension DOM queries.
204
151
 
205
- | Action | Description |
206
- | --------- | --------------------------------------------------------------------------- |
207
- | `launch` | Create a managed Extension tab, or launch CDP when Extension is unavailable |
208
- | `connect` | Confirm Extension by default; `port` explicitly selects CDP |
209
- | `list` | List all pages/tabs |
210
- | `attach` | Attach to a specific page/tab |
211
- | `open` | Navigate to URL |
212
- | `back` | Go back in history |
213
- | `forward` | Go forward in history |
214
- | `refresh` | Reload page |
215
- | `close` | Close the page specified by `targetId` |
152
+ Examples:
216
153
 
217
- Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
218
- (whether the tab is controlled by MCP Chrome), `isActive` (Chrome's active tab within its window), `windowId`, `index`,
219
- `pinned`, `incognito`, and `status` (`loading`/`complete`). The tree includes `windowCount`, `focusedWindowId`,
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`,
222
- `forward`, and `refresh` accept `diagnostics=true` to return new console warnings/errors and failed network requests
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.
154
+ ```typescript
155
+ // By accessibility (recommended - most stable)
156
+ const byRole = { role: 'button', name: 'Submit' }
236
157
 
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.
158
+ // By accessibility with exact accessible name
159
+ const byExactRole = { role: 'button', name: 'Submit', exact: true }
242
160
 
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.
161
+ // By text content
162
+ const byText = { text: 'Click here', exact: true }
249
163
 
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.
164
+ // By form label
165
+ const byLabel = { label: 'Email' }
256
166
 
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.
167
+ // By placeholder
168
+ const byPlaceholder = { placeholder: 'Enter your name' }
169
+
170
+ // By title attribute
171
+ const byTitle = { title: 'Close dialog' }
172
+
173
+ // By alt text (images)
174
+ const byAlt = { alt: 'Profile picture' }
175
+
176
+ // By test ID
177
+ const byTestId = { testId: 'submit-button' }
178
+
179
+ // By CSS selector
180
+ const byCss = { css: '#login-form .submit-btn' }
181
+
182
+ // Disambiguate multiple matches (0-based)
183
+ const secondMatch = { css: '.ant-select-input', nth: 1 }
184
+
185
+ // By CSS + text (filter by text content)
186
+ const byCssText = { css: 'button', text: 'Submit', exact: true }
187
+
188
+ // By XPath
189
+ const byXPath = { xpath: "//button[@type='submit']" }
190
+
191
+ // By coordinates
192
+ const byCoordinates = { x: 100, y: 200 }
193
+ ```
194
+
195
+ Text-only targets choose the innermost complete-text match, including nested text nodes. Explicit XPath preserves
196
+ document order. Both backends use display, visibility and nonzero dimensions for visibility; an initially absent
197
+ hidden/detached target succeeds on its first query.
198
+
199
+ In both backends, target lookup failures from `input`, `extract`, and `wait` report the failed locator, zero-based
200
+ `nth`, URL, tab/frame scope, managed state, last locator state, and at most 10 candidate summaries within the request
201
+ budget. `matchCount` is the observed total, not the candidate limit; an out-of-range `nth` does not turn 15 matches into
202
+ zero. Unknown counts or managed state are `null`, and unavailable diagnostics include `diagnosticError`. CDP retains
203
+ `ELEMENT_NOT_FOUND` for lookup failures and `TIMEOUT` for element waits, together with existing URL and log fields.
204
+ Diagnostics read the failed target before its scope is restored and never replay input.
205
+
206
+ Targeted operations resolve `target.nth` directly in both backends, including indices beyond the default 50-result
207
+ candidate list and pure-text indices beyond 200. A single-target result does not report a total; its diagnostic
208
+ `matchCount` is `null` unless a separate lookup measured the total. Element waits check that selected target, so an
209
+ existing high-index element cannot satisfy `hidden` or `detached` merely because candidate output is bounded.
260
210
 
261
211
  Page tools accept `targetId` in either backend; the older `tabId` alias is still accepted. If both are supplied, they
262
212
  must match. An explicit target changes only the operation scope and restores the previous default afterward.
@@ -266,6 +216,13 @@ before/after URL and revision, default target before/after, and Chrome's active
266
216
  `unconfirmed` means a page-creation action failed without returning a created target ID. CDP reports browser activity as
267
217
  unavailable rather than treating the selected operation target as foreground.
268
218
 
219
+ Page URL fields in these snapshots, browse results, page/window management, state, metadata, and diagnostic bundles
220
+ redact credential query parameters, including `ticket`, and report `urlRedacted`, `urlOriginalLength`, and
221
+ `redactedQueryParameters`. Native `pendingUrl` and `favIconUrl` fields use equivalent field-prefixed markers. Navigation
222
+ waits and navigation error messages use the same display redaction. Navigation and `expectedUrl` comparisons use the
223
+ original URL; page content and user-script results retain their requested content. Use `expectedRevision` or an original
224
+ URL you hold for conditions; a redacted display URL cannot serve as `expectedUrl`.
225
+
269
226
  When an older Extension lacks `page_snapshot`, unconditional page actions can still use a fresh page-list URL. Their
270
227
  `pageContext.before` and `after` snapshots report `revision=null` with a `warning` about the unavailable revision and
271
228
  atomic conditions. Requests with `expectedUrl` or `expectedRevision` return `DRIVER_CAPABILITY_ERROR`,
@@ -300,6 +257,185 @@ and eligible `manage` page actions accept `expectedUrl` and `expectedRevision`.
300
257
  modifying command, not before every event. A failed or timed-out action can still change the revision when it may have
301
258
  had partial effects.
302
259
 
260
+ ## Request scope and failure handling
261
+
262
+ An input sequence keeps its backend and page through execution and target restoration. CDP binds frame execution to its
263
+ context and OOPIF session; Extension checks the document and native iframe owner, so same-URL iframe reordering
264
+ preserves the selected identity. Concurrent `browse(action="connect")` waits for that request scope.
265
+
266
+ Input and evaluate share one budget across queueing, page selection, preparation, dispatch and verification.
267
+ Cancellation or budget settlement stops queued scripts, remaining events and later context or diagnostic reads. Keys
268
+ newly held by that request are released with a separate bounded cleanup budget. Confirmed final events retain
269
+ `actionStatus="completed"` if later response handling exceeds the deadline; dispatched actions without confirmation
270
+ retain `unknown` and `retryable=false`. Read the current page before deciding on another action.
271
+
272
+ Coordinate input waits for synchronous scroll cascades, including open Shadow roots created during preparation, then
273
+ reads the current frame-local rectangle. Unrelated requestAnimationFrame scrolling does not keep a stable target
274
+ waiting. Continuous synchronous self-scrolling is bounded by the request deadline, even when the target stays still.
275
+
276
+ MCP cancellation also stops queued window and group changes. The Extension checks the request after asynchronous
277
+ preflight and before native changes or uncommitted ownership, read-grant and metadata updates. A successful storage
278
+ commit is synchronized to memory; required registration after creation and cleanup after closing still finish. Event-ref
279
+ controls remain available while another page action is waiting.
280
+
281
+ Extract uses the same signal for queueing, page reads and exports. Cookie, log, event, evaluate and extract outputs
282
+ check the signal and deadline during preparation and before publication. Cancellation stops later reads, unpublished
283
+ files and later log manifests; published files remain available and temporary-file cleanup finishes. A completed script
284
+ retains its execution state if its output is stopped.
285
+
286
+ ## Operation status and diagnostics
287
+
288
+ Input and evaluate expose execution and verification separately:
289
+
290
+ - `actionExecuted`
291
+ - Values: `false`, `true`, `"unknown"`
292
+ - Meaning: Known principal-action execution fact
293
+
294
+ - `actionStatus`
295
+ - Values: `not_started`, `completed`, `failed`, `unknown`
296
+ - Meaning: Principal-action outcome
297
+
298
+ - `verificationStatus`
299
+ - Values: `matched`, `not_matched`, `unavailable`, `error`
300
+ - Meaning: Post-condition observation
301
+
302
+ - `failureStage`
303
+ - Values: Context, precondition, queue, action, verification or output
304
+ - Meaning: Stage that failed
305
+
306
+ - `retryable`
307
+ - Values: Boolean
308
+ - Meaning: Whether the principal action can be retried
309
+
310
+ - `diagnosticsStatus`
311
+ - Values: Status of supplemental diagnostics
312
+ - Meaning: Diagnostics keep the primary result and observations collected before failure
313
+
314
+ Page-thrown exceptions retain their message text, including empty strings, JSON-shaped text and primitive values, with
315
+ `actionExecuted=true` and `actionStatus="failed"`. Existing exception descriptions and stacks are preserved. Once the
316
+ script's result has resolved, failures during type inspection, diagnostic summaries, or JSON encoding and decoding of
317
+ results and error details report `actionExecuted=true`, `actionStatus="completed"`, `failureStage="output"` and
318
+ `retryable=false`, including in stealth mode. Promise rejection while adopting the return value remains an action
319
+ failure. If an encoded error summary cannot be decoded, `error.context.originalOutputError` retains the first output
320
+ diagnostic.
321
+
322
+ An initial snapshot failure reports `false/not_started`, `failureStage="context"` and
323
+ `pageContext.contextPhase="before"`. A snapshot checking `expectedUrl` or `expectedRevision` uses `precondition` for
324
+ both stage fields. If a target, frame, Challenge, argument or per-event preparation RPC has an unknown receipt or an
325
+ internal evaluate output failure before the principal action is dispatched, the top-level action remains
326
+ `false/not_started/context`; the auxiliary operation keeps its own facts in the error context. Confirmed earlier input
327
+ events remain counted. Late replies do not dispatch or replay the principal action.
328
+
329
+ A page precondition mismatch reports `false/not_started/precondition`. Target diagnostics read the current tab instead
330
+ of cached attach metadata.
331
+
332
+ ### Native failures and diagnostics
333
+
334
+ Native browser script termination, `Internal error`, `Object couldn't be returned by value`, and
335
+ `Object reference chain is too long` responses from CDP `Runtime` script commands preserve the original error code.
336
+ evaluate and `manage cdp` return `actionExecuted=true`, `actionStatus="unknown"`, and `retryable=false` without
337
+ replaying the command. evaluate also returns `retryable=false` when an in-flight RPC timeout or stale execution context
338
+ leaves the result unknown; failures before dispatch use their reported `retryable` field. Page-thrown exceptions with
339
+ the same text remain non-retryable action failures.
340
+
341
+ Recognized Extension CDP rejections return `CDP_ERROR` with the method, target, native message and available protocol
342
+ code. The context distinguishes a disabled Debugger domain, stale script ID, browser-level command restriction, missing
343
+ method, command permission refusal (`Not allowed`), and native result serialization failure. A resource or method lookup
344
+ failure does not imply that the entire domain is unsupported. These remain failed calls with warning diagnostics;
345
+ unknown errors retain error-level reporting. A closed tab found during a native snapshot or permission check remains a
346
+ target failure, separate from page-thrown exceptions with matching text.
347
+
348
+ The Extension logs known refusals for restricted-page diagnostics, closed dialogs, expired or mismatched event refs,
349
+ conflicting Cookie partitions, and removed frames as warnings. Each call keeps its original failed response. Page-script
350
+ exceptions and unknown failures stay at error level.
351
+
352
+ ## Available Tools (8 Tools)
353
+
354
+ ### browse - Browser Management & Navigation
355
+
356
+ | Action | Description |
357
+ | --------- | --------------------------------------------------------------------------- |
358
+ | `launch` | Create a managed Extension tab, or launch CDP when Extension is unavailable |
359
+ | `connect` | Confirm Extension by default; `port` explicitly selects CDP |
360
+ | `list` | List all pages/tabs |
361
+ | `attach` | Attach to a specific page/tab |
362
+ | `open` | Navigate to URL |
363
+ | `back` | Go back in history |
364
+ | `forward` | Go forward in history |
365
+ | `refresh` | Reload page |
366
+ | `close` | Close the page specified by `targetId` |
367
+
368
+ A default `launch` uses a connected Extension. Explicit `headless`, `incognito`, `userDataDir`, `executablePath`, or
369
+ `port` selects a new CDP browser and returns `mode="cdp"`. An existing CDP connection is reported as a conflict before
370
+ creating or closing a browser; supplied launch settings are applied or rejected.
371
+
372
+ Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
373
+ (whether the tab is controlled by MCP Chrome), `isActive` (Chrome's active tab within its window), `windowId`, `index`,
374
+ `pinned`, `incognito`, and `status` (`loading`/`complete`). Summary mode returns `windowCount` and each window's ordered
375
+ `targetIds`; `details="full"` includes the full native target and window properties. When Chrome has a focused window,
376
+ `focusedWindowId` identifies it and `activeTargetId` identifies its active tab. With no focused Chrome window, both
377
+ fields are omitted; each window still reports its own `activeTabId`. `defaultTargetId` identifies the selected operation
378
+ target; CDP does not infer Chrome's foreground tab from this selection. When `open` creates a page, it reuses this
379
+ connection's trusted work group. A new group gets a bounded purpose name, cyan color and an expanded state so its pages can run. Independent active connections use separate groups.
380
+ `open`, `back`, `forward`, and `refresh` accept `diagnostics=true` to return new console warnings/errors and failed
381
+ network requests observed during the action, including the first `open` that creates a page automatically. `open` and
382
+ `refresh` honor `wait="load"`, `wait="domcontentloaded"`, and `wait="networkidle"` in both drivers. The wait is
383
+ registered before the command and bound to the new main document, so late lifecycle events from an earlier navigation
384
+ are ignored. CDP `networkidle` waits for the current main-frame loader's `networkIdle` event. Extension `networkidle`
385
+ waits for the current document to complete, all tracked response bodies to finish, and a 500 ms quiet period. Lost
386
+ request tracking causes a timeout instead of a false idle result. `close` requires `targetId` and closes only that page.
387
+ It never closes the entire CDP connection.
388
+
389
+ In Extension mode, `back` and `forward` visit the adjacent history entry in an accessible main document, including
390
+ entries created by earlier `open` calls without user interaction. Traversal uses the browser History API in an isolated
391
+ world and keeps the tab in the background without attaching a debugger. A known direction boundary returns
392
+ `navigated=false` immediately; the Navigation API's direction flags establish a boundary only when its entries cover the
393
+ full browser history. Uncommitted navigations, restricted URLs, browser error pages, and missing main frames retain
394
+ native browser UI history selection without script injection. Native failures and injection failures are preserved, and
395
+ navigation is dispatched at most once. A dispatched traversal with no observed navigation signal returns a timeout with
396
+ an unknown action status. A destroyed execution context or a browser refusing injection into an error page returns an operation
397
+ failure, recorded as a warning in the Extension. Arbitrary debugger commands are never automatically replayed.
398
+
399
+ If a CDP history-navigation command is rejected, the original error is returned and that navigation wait ends
400
+ immediately, keeping later requests available.
401
+
402
+ For `open`, `back`, `forward`, and `refresh`, `timeout` starts at request entry. Target preparation, queueing, protocol
403
+ calls, page loading, Challenge inspection and clicks, diagnostics, and target restoration share the remaining budget;
404
+ navigation RPCs do not add transport time. An expired queued action is not dispatched, and later requests still wait for
405
+ an earlier in-flight action to settle. Explicit `timeout=0` rejects before navigation dispatch. Page creation retains
406
+ its separate load-wait and transport-time contract. When the navigation wait exhausts the request deadline, later
407
+ metadata and diagnostic reads stop. A shorter wait timeout leaves the enclosing request's remaining budget available.
408
+
409
+ MCP cancellation stops queued browse actions before dispatch and ends active navigation or Challenge waits. The same
410
+ signal stops later OS mouse commands and CDP launch steps after an interrupted wait; launch cleanup terminates only a
411
+ process created by that request and not yet delivered.
412
+
413
+ If a mouse button was already pressed, the request retains the tab lock until its necessary release completes or the
414
+ independent 5000 ms cleanup budget ends. Subsequent navigation and input remain queued during release. A failed or
415
+ timed-out release reports `releaseStatus="unknown"` with an explicit error; check and release the mouse button before
416
+ continuing.
417
+
418
+ A confirmed navigation keeps `actionExecuted=true` and `actionStatus="completed"` when its later state read fails, with
419
+ `failureStage="metadata"` and `retryable=false`; page verification retains its own result.
420
+
421
+ A timeout does not undo a Chrome operation already dispatched. When its result is unknown, the response reports
422
+ `TIMEOUT`, `actionExecuted="unknown"`, `actionStatus="unknown"`, and `retryable=false`; read the actual page state
423
+ instead of replaying navigation. `pageContext.after` uses a fresh snapshot when available; otherwise it is null with
424
+ `contextError`. Exhausted restoration is reported separately without replacing the primary action result. CDP history
425
+ waits accept a main-frame BFCache restore or same-document event from the current session, not an ordinary frame commit,
426
+ a child-frame event, or an event from another session.
427
+
428
+ Challenge click, detach, and inspection RPCs carry the remaining deadline and reject dispatch after queueing or page
429
+ validation exhausts it. OS mouse movement and fallback processes use the same deadline. A CDP press that has started
430
+ always attempts release on the original connection and session; release cleanup waits at most one second and never uses
431
+ a newly selected target. Read-only Challenge checks that expire return `CHALLENGE_TIMEOUT` with the known primary action
432
+ status. An uncertain click returns `TIMEOUT` with that primary status, `verificationStatus="unknown"`,
433
+ `verificationActionExecuted`, and `retryable=false`; neither navigation nor the click is automatically replayed.
434
+
435
+ Evaluate retains Challenge result fields on success, action failure, verification mismatch, and output failure.
436
+ `originResponsePending=true` means verification succeeded but the origin server has not responded; it does not mean the
437
+ destination content has loaded.
438
+
303
439
  For `browse`, only `open`, `back`, `forward`, `refresh`, and `close` accept these conditions. Other actions, including
304
440
  `attach`, reject them with `INVALID_ARGUMENT` before changing any target.
305
441
 
@@ -309,12 +445,12 @@ page. `releasePage` revokes full managed access without closing the tab or chang
309
445
  log state and removes debugging and console capture resources. If Chrome prevents resource cleanup, the response
310
446
  includes `warnings` while managed access is still revoked.
311
447
 
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`.
448
+ Managed access survives a Service Worker restart. Reloading the Extension also restores access to surviving managed tabs
449
+ whose original document identity still matches, without refreshing or adopting them again. Tabs with unavailable
450
+ document identity require explicit `adoptPage` after an Extension reload; ordinary navigation keeps managed access, and
451
+ `releasePage` remains revoked after a restart or reload. A reused tab ID does not authorize a different document. A
452
+ managed tab can keep using this Extension's existing debugger session after a Service Worker restart. Sessions owned by
453
+ other debuggers still return `DEBUGGER_BLOCKED`.
318
454
 
319
455
  Use `manage(action="grantReadAccess", targetId=...)` to grant ordinary reads and `revokeReadAccess` to revoke them; no
320
456
  popup click is required. Both require an explicit target and accept `expectedUrl`/`expectedRevision`. Grants belong to
@@ -325,57 +461,112 @@ target ID alone does not authorize reading. The grant covers ordinary content re
325
461
  attributes, computed styles, and page state. Scripts, debugger operations, screenshots, input, and cookie access do not
326
462
  inherit it; existing cookie operations have separate URL/name filter rules. When page management or navigation is
327
463
  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.
464
+ `manage(action="pageMetadata", targetId=...)` reads or updates `taskHint` and `note`, with
465
+ `expectedUrl`/`expectedRevision` conditions. A mismatch returns `ACTION_PRECONDITION_FAILED` before reading or updating
466
+ notes. Extension persists `origin=created/adopted/unknown`, creation time and task notes. Existing v1 pages migrate to
467
+ unknown and remain managed. Extension metadata is authoritative after Server restart; storage failures return errors.
468
+ CDP metadata remains local to the Server process. Origin, document identity and trusted native relationships are
469
+ maintained by Extension; notes never grant content access.
470
+
471
+ Start each task with `browse list`, select a suitable page by task name and notes, and attach in the background to reuse
472
+ it. Call `newPage` only when no suitable page exists, supplying `taskHint` and a `note` that identifies temporary,
473
+ output or reusable use. `newPage` always creates a new page.
474
+
475
+ Name the specific object and action or goal in `taskHint`, such as `Fix lane lookup`, `Debug build` or `Test login`.
476
+ Keep the complete meaning: this name identifies pages for reuse and is stored in page metadata, independently of the
477
+ native group title. Keep the same name across pages, sites and stages of one task, and distinguish different tasks by
478
+ purpose. Put HIL/simulation, task IDs, versions, progress and page-specific use in `note`.
479
+
480
+ By default, `newPage` uses an existing normal window and keeps continuous work in the same trusted group across steps.
481
+ Independent active connections use separate groups. After a restart, list and attach a previous work page before
482
+ creating another; its trusted records, native membership and active connection ownership determine group recovery.
483
+ User-created and mixed user groups stay in place.
484
+
485
+ Choose a short purpose name for the work group with the existing `updateGroup` action, such as `MCP · Release`, and
486
+ reuse it for internal subtasks. Keep complete task details in page metadata. A new group initially uses `MCP` plus a
487
+ bounded task hint, URL hostname or `浏览` (Browse); duplicate initial names receive a number. New groups start
488
+ expanded. Page work expands a frozen trusted tool group without selecting a tab; user, mixed and other active connection
489
+ groups stay unchanged. Later creation and metadata changes preserve existing titles, colors and collapsed state. Native moves,
490
+ closure and membership changes clear invalid relationships. With no normal window, creation returns an error; lost
491
+ caches never create a window.
492
+
493
+ At task completion, use the existing close/release actions on an explicit page set. Default cleanup closes only pages
494
+ created for this task whose notes explicitly identify temporary use. Preserve adopted/unknown pages, outputs, reusable
495
+ test pages and mixed user groups; release unused temporary permissions through existing actions. Explicitly authorized
496
+ closure retains the existing managed-page contract. Disconnects and idle periods never close pages. Native groups
497
+ require Extension; CDP accepts metadata-only `taskHint/note` options.
498
+
499
+ Explicit `networkidle` starts Network observation before navigation, including URL loading for a new page, and requires
500
+ 500 ms of quiet after tracked requests finish. Missing or interrupted observation returns an error. The default `load`
501
+ path does not attach a debugger for network-idle tracking.
332
502
 
333
503
  ### Access challenges
334
504
 
505
+ An incomplete read-only inspection keeps `challengeState="unverified"`. Ordinary titles and headers still wait for the
506
+ visible-content check, with read-only retries within the original request deadline. Expiry without challenge evidence
507
+ returns `TIMEOUT`, `verificationStatus="unavailable"` and `autoRetry=false`; an unknown native inspection
508
+ acknowledgement remains unknown in `verificationActionExecuted` and `verificationActionStatus`. An observed challenge
509
+ retains `CHALLENGE_TIMEOUT` and its observed kind. Completed navigation stays completed; inspection retries do not
510
+ replay navigation or the business action.
511
+
335
512
  After `open`, `back`, `forward`, `refresh`, `input`, and `evaluate`, MCP Chrome waits for a Cloudflare JS Challenge or
336
513
  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
341
- fixture buttons use the existing page click. If a Cloudflare Turnstile iframe is present, inspect CSS coordinates are
342
- converted to screen coordinates and the OS mouse moves along a path, hovers, then presses and releases: `xdotool` on
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
346
- `mouse_event` on Windows. Widget clicks target the checkbox on the left of the compact Turnstile card, including when
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
348
- used even when that iframe reports a zero-size rect, including the later host `Verify you are human` / `请验证您是真人`
349
- button. The OS click runs only when the managed test tab is already the active tab in an already-focused window; mixed
350
- windows are not focused. Debugger is detached and the viewport is read again before the OS click. Missing OS mouse tools
351
- or an unfocused window return a visible error instead of a silent CDP click. A Turnstile widget is clicked only after
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.
514
+ persists, MCP Chrome reads the live tab title passively for the first eight seconds. If the interstitial persists, it
515
+ checks for a visible Turnstile control and clicks it only when it finds one. Extension inspect uses an isolated world.
516
+ Challenge titles detach the debugger before inspection; ordinary-page checks retain an existing connection unless a
517
+ visible verification control or unresolved challenge content is found. Same-page fixture buttons use the existing page
518
+ click. If a Cloudflare Turnstile iframe is present, inspect CSS coordinates are converted to screen coordinates and the
519
+ OS mouse moves along a path, hovers, then presses and releases: `xdotool` on Linux uses the focused Chrome client-window
520
+ geometry and `xprop` GTK frame extents only when that window title matches the test page. Missing tools, invalid
521
+ geometry, or a viewport mismatch stop the click instead of guessing the content origin from Chrome `screenX` or
522
+ `outerHeight - innerHeight`; `cliclick` or System Events on macOS; and PowerShell `mouse_event` on Windows. Widget
523
+ clicks target the checkbox on the left of the compact Turnstile card, including when the host wrapper is wider than the
524
+ card, not the label. If a Cloudflare iframe is already in the DOM, the OS mouse is used even when that iframe reports a
525
+ zero-size rect, including the later host `Verify you are human` / `请验证您是真人` button. The OS click runs only when
526
+ the managed test tab is already the active tab in an already-focused window; mixed windows are not focused. Debugger is
527
+ detached before the OS click. After movement and hover, the control position, viewport and active window are checked
528
+ again before pressing. On Linux, a 1 px native round trip calibrates the current content origin while the debugger
529
+ banner animates. If the pointer crosses elements during the animation, calibration samples again within the original
530
+ timeout and accepts an origin only after both trusted events target the same element. If the control moves, the mouse
531
+ repeats the path, hover and calibration before pressing. A changed page, control stage or focus stops the click. Missing OS mouse tools or an unfocused window return a visible
532
+ error instead of a silent CDP click. A Turnstile widget is clicked only after two inspections report the same click
533
+ point; unrelated elements do not become widgets just because their sizes match. Distant OS-mouse paths start near the
534
+ control instead of flying across the screen. The same checkbox or compact widget is clicked at most once; if Cloudflare
535
+ then shows a visible `Verify you are human` or `请验证您是真人` button, that button is inspected as `verify` and clicked
536
+ at most once in the same wait. Use the default `diagnostics=false` for challenge-protected pages because diagnostics
537
+ starts debugger console and network collection.
357
538
 
358
539
  Detection covers titles such as `Just a moment...` and `请稍候…`, visible challenge DOM or body-text markers, and
359
540
  `Verify you are human` / `请验证您是真人` controls, including visible `button` elements with that exact text. A normal
360
541
  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.
542
+ markers do not. Pages without challenge evidence continue without a fixed eight-second wait. Same-page buttons use page
543
+ input when no Cloudflare iframe is present. CDP reads live titles with `Target.getTargetInfo`. A leftover Cloudflare
544
+ iframe or an old pending header alone does not keep a recovered page pending or trigger scrolling or a click. Cached
545
+ titles do not decide the result. MCP Chrome does not call a CAPTCHA solver, retry navigation, or export `cf_clearance`
546
+ values. A CDP timeout does not prove that the site fails in a user Chrome session; check the returned `mode` before
547
+ diagnosing the site.
548
+
549
+ A completed embedded widget can retain its container. An associated nonempty response marks that widget complete; reset
550
+ or expiry returns it to pending. Each widget is checked separately, and a response in another form cannot complete it.
551
+ Detection returns completion state without returning the response value.
552
+
553
+ Input and evaluate check for a new challenge after the action returns, using the remaining budget. A verification
554
+ failure retains the action's completed state and never replays it. If the confirmed final event exhausts the budget,
555
+ `challengeVerificationStatus="unavailable"` explains that no post-action challenge check could run. A post-action
556
+ timeout returns `retryable=false` and `nextAction="wait_and_verify"`; wait for verification and inspect the business
557
+ result.
367
558
 
368
559
  A resolved challenge returns `challengeResolved=true`, `challengeKind`, `waitedMs`, `clickedTurnstile`, and
369
560
  `clearanceCookiePresent` (name presence only). If the visible page text says verification succeeded and Cloudflare is
370
561
  waiting for the origin, the result also has `originResponsePending=true`; verification passed, but the destination page
371
562
  is not loaded yet. Hidden template text such as a `display:none` success heading does not count, and a visible Turnstile
372
- checkbox still counts as pending. Challenge results and errors include `mode`. Timeout returns `CHALLENGE_TIMEOUT` with
373
- `retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is not reported as `js`).
374
- Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP reputation checks
375
- cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears the header flag;
376
- ordinary iframe document responses and clearing network logs do not.
563
+ checkbox still counts as pending. Challenge results and errors include `mode`. Before-action timeout returns
564
+ `CHALLENGE_TIMEOUT` with `retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is
565
+ not reported as `js`). Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP
566
+ reputation checks cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears
567
+ the header flag; ordinary iframe document responses and clearing network logs do not.
377
568
 
378
- ### input - Keyboard & Mouse Input
569
+ ### input - Keyboard, Mouse & File Input
379
570
 
380
571
  Event sequence model supporting arbitrary combinations:
381
572
 
@@ -388,6 +579,7 @@ Event sequence model supporting arbitrary combinations:
388
579
  | `wheel` | Mouse wheel scroll |
389
580
  | `touchstart` / `touchmove` / `touchend` | Touch events |
390
581
  | `type` | Type text (with optional `delay`, `dispatch` for React/Vue) |
582
+ | `upload` | Select local files in a file input; `files:[]` clears the selection |
391
583
  | `wait` | Pause between events |
392
584
  | `select` | Select text by content (mouse sim) |
393
585
  | `replace` | Find and replace text |
@@ -396,6 +588,12 @@ Event sequence model supporting arbitrary combinations:
396
588
  | `editorInsert` | Insert text at the current editor selection |
397
589
  | `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList` |
398
590
 
591
+ On background Extension and CDP tabs, a default unmodified click with the left mouse button on an element uses checked
592
+ synthetic events and returns a `warnings` entry with `isTrusted=false`, without selecting the tab. On a rendered active
593
+ tab, precise mode uses native input. Humanized clicks retain their mouse movement. Background Extension coordinate
594
+ clicks, movement, or modified/multiple clicks require explicit `manage(action="inputMode",inputMode="stealth")`;
595
+ mouse-button cleanup remains available.
596
+
399
597
  Special-case parameters:
400
598
 
401
599
  - `keydown` accepts `commands` (e.g. `["selectAll"]`, `["copy"]`, `["paste"]`, `["cut"]`, `["undo"]`, `["redo"]`) to
@@ -413,26 +611,103 @@ waits for a page state after the events so callers can distinguish dispatched in
413
611
  `postCondition.timeout` defaults to 3000 ms and is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and
414
612
  accepts 50-5000 ms. A `postCondition.script` may be an expression, function, async function, or Promise expression;
415
613
  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.
614
+ check. `targetId` (or legacy `tabId`) selects a page in either backend; `frame` selects an iframe (CSS selector or index
615
+ or a nested path) in either backend. When either scope is provided, the action, diagnostics, and post-condition use the
616
+ backend selected for that target scope.
617
+
618
+ Text, selector and URL checks recover a transient lost context within the remaining input and verification deadlines. A
619
+ context that stays unavailable, a closed native connection, or an exhausted read budget returns
620
+ `verificationStatus="unavailable"`. Script checks report native context failures immediately. Native execution
621
+ termination and engine execution timeouts during verification return `unavailable` in both Extension and CDP. Selector
622
+ syntax errors and page-thrown or rejected errors return `error`, including when an exception's string conversion also
623
+ throws. Error text mentioning a frame or timeout does not change the source. A completed input keeps
624
+ `actionStatus="completed"`, `failureStage="verification"` and top-level `retryable=false`. Use `postCondition.retryable`
625
+ to retry the check on its own. Verification shares the action's total deadline; an exhausted total budget starts no new
626
+ check.
627
+
628
+ Cancellation interrupts verification reads and polling waits. Input then attempts a bounded release of keys newly
629
+ pressed by that request before the next queued action starts. Keys held before the request remain held; release failures
630
+ retain a diagnostic.
631
+
632
+ Text checks match rendered page text and visible, non-password form values. The bounded `actual` excerpt includes the
633
+ matched text. Clicks on a Shadow host accept its own shadow descendants; synthetic click, key and input events reach
634
+ host and document listeners, while mouseenter and change retain their local event semantics.
635
+
636
+ Coordinate targets use the selected frame's viewport coordinates. Native precise input accounts for the frame's content
637
+ boundary, scaling, rotation, skew and nested placement; input whose coordinates cannot be mapped reliably fails before
638
+ the affected event. Earlier completed events retain their progress. Stealth events keep frame-local coordinates.
639
+
640
+ Target-based coordinate preparation follows assigned slots and Shadow hosts to the actual scroll container. On visible
641
+ pages, it checks the target rectangle and ancestor scroll positions across consecutive renders, including cascades
642
+ triggered by page listeners that stop event propagation. A stable target remains actionable beside a looping, unrelated
643
+ scroller. A page hidden during this wait uses its current layout without waiting for paused animation frames; a page
644
+ that becomes visible resumes render checks. Continuous target motion or ancestor scrolling can exhaust the shared
645
+ request deadline, leaving that event undispatched.
646
+
647
+ An omitted wheel target keeps the current mouse position. Extension wheel helper setup and input target the same
648
+ resolved documentId; replacement or removal before input returns not_started without selecting the new document.
649
+
650
+ Wheel and mouse events carry the currently held Ctrl, Shift, Alt and Meta fields, including combined modifiers and
651
+ precise right-click events that use synthetic dispatch. Synthetic events retain `isTrusted=false`; application listeners
652
+ can inspect the modifier fields and cancel their default scroll.
653
+
654
+ Extension coordinate wheel follows each axis's effective scroll range, including reverse Flex layouts and vertical
655
+ writing modes. Fractional deltas accumulate across consecutive inputs to the same scroll container, including changes to
656
+ the hit descendant and scrolling performed by that wheel listener. Position changes between inputs reset that
657
+ container's pending fraction; another container or document starts its own sequence. Native scroll progress identifies
658
+ fractional endpoints under CSS zoom. When native progress is unavailable, a console warning identifies the CSSOM-bounds
659
+ compatibility path. Element scroll distances account for effective CSS zoom; ordinary transform scale keeps its existing
660
+ wheel-distance semantics. Viewport scrolling uses its own units.
661
+
662
+ Scroll-container eligibility accounts for the namespace, principal box and text-editing controls. MathML math layouts,
663
+ flow-root and inline flow-root list items, block ruby and Chrome-supported `-webkit-box`/`-webkit-inline-box` layouts
664
+ retain their scrolling and boundary behavior. A text input can scroll its internal text even when Chrome reports
665
+ computed overflow as clip. A block SVG viewport does not become a CSS scroll boundary from hidden/contain declarations;
666
+ a foreignObject with a scrolling box retains its own auto scrolling and hidden contain/none boundary, and embedded HTML
667
+ retains its own scrolling behavior. At a real container boundary, `overscroll-behavior-x/y: contain` or `none` stops
668
+ that axis, including zero-range containers; `auto` lets an unconsumed axis continue along the original chain. A nested
669
+ `overflow:hidden` container keeps its boundary policy without scrolling itself; ordinary clip/visible, non-atomic inline
670
+ and display:contents nodes do not add that boundary.
671
+
672
+ The viewport follows root/body overflow propagation. A body with no principal box, including display:contents, does not
673
+ supply its overflow. Effective containment on html/body, including content-visibility or container-type, keeps the body
674
+ independent. A body supplying viewport overflow is not a separate boundary, and hidden/clip viewport axes do not scroll.
675
+ A scrollable target consumes its own input first. Absolute/fixed targets then follow the nearest applicable positioning
676
+ containing block through the composed tree, including slots and foreignObject content. Transform, filter, containment,
677
+ 3D/motion conditions and applicable will-change names keep their own box-eligibility rules.
678
+
679
+ The composed, cancelable wheel event reaches Shadow host and document listeners. Effective `preventDefault()` suppresses
680
+ the simulated default scroll; the event still reports `actionStatus="completed"` and counts as one executed input. Each
681
+ axis selects its scroll route from the boundary at input start. A listener that resizes or repositions a scroll
682
+ container retains its own changes; the default action uses the resulting position on the selected route. A container
683
+ that loses its scroll range lets unconsumed input continue along the original chain under its overscroll policy.
684
+ Removing or moving the hit element does not redirect that wheel to a newly inserted ancestor or an unrelated viewport.
685
+
686
+ Extension wheel uses programmatic scrolling for its default action. Scroll snapping follows that programmatic endpoint,
687
+ which can differ from native wheel intent. Mandatory and proximity snap layouts retain their declared snapping; native
688
+ wheel endpoint differences are an accepted compatibility behavior.
424
689
 
425
690
  For keyboard `type`, `timeout` includes Challenge waiting, focus preparation, character input, and `delay`/`humanize`
426
691
  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.
692
+ valid input to take longer than the default 30,000 milliseconds. When the budget expires, subsequent characters and
693
+ events stop. Already dispatched input cannot be undone, so a timeout may leave partial input. A response with
694
+ `actionExecuted=true`, `actionStatus="unknown"`, and `retryable=false` requires an independent page read to check the
695
+ actual value; do not replay the whole event sequence.
431
696
 
432
697
  Mouse target lookup, stepped movement, and `humanize` delays also share the remaining input budget. Each movement and
433
698
  the subsequent click check the deadline; expiry stops further movement and clicking. Already dispatched native events
434
699
  cannot be undone. Read the page independently after an unknown result instead of replaying the action.
435
700
 
701
+ Extension precise `type` in keyboard mode and `keydown`/`keyup` events use native keyboard input. Focus preparation
702
+ shares the remaining request budget. When focus emulation is needed, response `warnings` explains that the document temporarily reports
703
+ `visible`; the actual tab and window focus stay unchanged. The original setting is restored before `postCondition` runs.
704
+
705
+ A recovered debugger session with an unknown original focus setting on a background tab returns
706
+ `KEYBOARD_FOCUS_STATE_UNKNOWN` and `not_started`, preserving that setting. Explicit stealth or an independent CDP
707
+ session remain available. Restoration failures return `keyboardFocusCleanup`; completed events retain `completed`, and
708
+ unconfirmed dispatch retains `unknown`. Failure, cancellation or expiry attempts to release keys newly pressed by this
709
+ request. Successful requests preserve intentionally held keys.
710
+
436
711
  Command focus, text selection, and replacement share the remaining event budget. Expiry stops subsequent actions; Shift
437
712
  release is still attempted without hiding an earlier action error. Stepped CDP touch movement also stops at the
438
713
  deadline.
@@ -444,36 +719,122 @@ events follow the same button mapping.
444
719
  In stealth mode, `delay` separates characters; the first character has no initial wait. Background page timer throttling
445
720
  can lengthen subsequent intervals, but the same deadline still stops further input.
446
721
 
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.
722
+ Default precise keyboard `type` in Extension and CDP mode dispatches Enter for each newline (CRLF is normalized). An
723
+ editor that submits on Enter can therefore submit part of a multiline input. For multiline replacement in Extension
724
+ mode, use `mode="controlled"` (or `dispatch=true`) with a `target`: it replaces the complete value or contenteditable
725
+ text and dispatches input/change without Enter. Form controls keep their native value setters.
726
+
727
+ Keyboard input and `editorInsert` use the current caret and selection. Keyboard `type` with a `target` clicks it first
728
+ and can change the insertion point; `editorInsert` focuses its target without clicking and inserts through the browser
729
+ editing API without Enter. To append multiline text, place the caret at the end and send `editorInsert` without a
730
+ `target`. A nonempty selection is replaced, not appended. Read the resulting value to verify the editor accepted it.
450
731
 
451
732
  CDP clicks and keyboard input also wait for stable element position and size in background pages without activating
452
733
  them. Visibility, enabled-state, viewport, and click coverage checks still apply. Target lookup, actionability checks,
453
734
  and the final coordinate read share the remaining event budget. If any of these stages exhausts it, no mouse or keyboard
454
735
  event is dispatched.
455
736
 
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.
737
+ **`click`-specific**: `force: true` requires `forceReason` and a non-coordinate element `target`. It skips actionability
738
+ checks while dispatching standard DOM mouse events. Middle/right and multiple clicks use the same rules; a coordinate or
739
+ omitted target cannot use force. Failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering elements,
740
+ candidate blockers and suggestions.
741
+
742
+ **`type`-specific**: `mode="controlled"` or `dispatch:true` replaces the value or contenteditable text and sends
743
+ `input`/`change` without Enter. It requires a non-coordinate `target` and Extension mode. Targets must be HTML `input`,
744
+ `textarea`, `select` or contenteditable; effectively disabled controls, readonly controls, unsupported containers and
745
+ file inputs are rejected before focus or input events. Disabled fieldsets follow HTML rules, including the first-legend
746
+ exception. Use `upload` for a file input. Ordinary controls, customized built-ins and same-origin controls adopted from
747
+ another document use the native value setter for their actual form interface; an unavailable setter returns an error
748
+ before focus.
749
+
750
+ Controlled input and target-lookup failures return `locator`, `matchCount`, `nth`, bounded `candidates` and an
751
+ `activeElement` summary without input values. Unavailable focus is `null`; a failed DOM query adds `diagnosticError`.
752
+
753
+ Cancellation or expiry after a confirmed Extension precise character or Enter event preserves executed progress and
754
+ invalidates the old page revision. Cancellation before the first dispatch keeps the not-started state. Read the current
755
+ value and revision before another action.
756
+
757
+ For a tag field that commits on Enter, send the text and explicit Enter events, then check the created tag. This `input`
758
+ example uses `#tag-entry` for the field and `#tags` for its tag list; use the selectors from the page:
759
+
760
+ ```json
761
+ {
762
+ "events": [
763
+ { "type": "type", "target": { "css": "#tag-entry" }, "text": "12345" },
764
+ { "type": "keydown", "key": "Enter" },
765
+ { "type": "keyup", "key": "Enter" }
766
+ ],
767
+ "postCondition": { "selector": "#tags [data-value=\"12345\"]" }
768
+ }
769
+ ```
770
+
771
+ #### Text selection and sensitive input
772
+
773
+ `replace` uses text selection for `textarea` and input types `text`, `search`, `tel`, `url` and `password`. Other input
774
+ types use a native full-value update and return requested and actual browser-normalized values. Standalone `select` on
775
+ an unsupported type returns `UNSUPPORTED_SELECTION`. CDP locator targets are focused through CDP rather than Extension
776
+ ref IDs.
777
+
778
+ Event-level `nth` selects a text occurrence; nested `target.nth` selects a matching element. Both are zero-based and can
779
+ be combined. Selection errors include editor and selection state.
780
+
781
+ Coordinate `select`/`replace` uses the control or text scope hit at that point, independently of the previous focus.
782
+ Replacement rechecks the selected element and selection ownership immediately before writing. Removal, focus moving to
783
+ another control or a selection leaving the target stops the write. A changed full-value target returns
784
+ `TARGET_FOCUS_FAILED`; a changed text selection returns `TEXT_SELECTION_CHANGED`. Readonly, disabled and unsupported
785
+ selection controls retain their rejection rules; matching text and selections in other controls stay unchanged.
786
+
787
+ Password values are omitted from failure context and text post-condition observations; failed input responses also
788
+ redact supplied `find` and replacement `text`, including locator details in `error.logs`. Password `select`/`replace`
789
+ hides console and network diagnostic bodies on success and failure, returning `diagnostics.redacted=true` and
790
+ `reason="sensitive_input_or_unresolved_target"`. An unresolved selection target receives the same protection. Ordinary
791
+ input keeps its diagnostics, and password protection ends with the current input request.
792
+
793
+ #### Upload local files
794
+
795
+ Prefer mcp-chrome for browsing, page interaction, and file uploads. Uploads reuse the current page and Extension/CDP
796
+ connection. Use Chrome DevTools for browser or extension diagnostics and specific tasks that mcp-chrome does not cover.
797
+
798
+ Select a file at its original path, including files in Downloads, through the `input` tool's `upload` event:
799
+
800
+ ```json
801
+ {
802
+ "events": [
803
+ {
804
+ "type": "upload",
805
+ "target": { "css": "input[type=file]" },
806
+ "files": ["./review.zip"]
807
+ }
808
+ ]
809
+ }
810
+ ```
811
+
812
+ `files` is required. Paths refer to readable regular files on the MCP Server machine. Relative paths use the Server's
813
+ working directory; absolute paths and `~/` paths are supported. The Server transfers file bytes, so the browser may run
814
+ on another machine. The selected files' combined size must be below 50 MiB; a total at or above that limit fails before
815
+ changing the file input.
816
+
817
+ Use multiple paths for an input with the `multiple` attribute. Use `files:[]` to clear it:
818
+
819
+ ```json
820
+ {"events":[{"type":"upload","target":{"css":"#attachments"},"files":[]}]}
821
+ ```
822
+
823
+ The target must be an `input[type=file]`. Hidden file inputs work without clicking or opening a system file chooser.
824
+ Existing element locators and `target.nth` select the input; `frame` selects a child or nested iframe in either backend.
825
+ Uploads use the current Extension or CDP connection and the selected input mode. Default precise mode supports strict
826
+ CSP pages; stealth keeps the page's CSP restrictions. Extension upload requires managed-page access, checked before any
827
+ local file read.
828
+
829
+ The result summarizes the selected file names, sizes, MIME types, and dispatched events. The input receives `input`
830
+ followed by `change`, using synthetic events. Sites requiring trusted events need site-specific verification. A page
831
+ that clears the input in its `change` handler still receives the file selection; the result describes the assignment
832
+ before those handlers run.
833
+
834
+ Use `postCondition` for the site's attachment-ready or upload-complete state, and submit separately when the site
835
+ requires it. A failed post-condition preserves the completed input action. File reads, transfer, and assignment share
836
+ the input timeout and cancellation. A failure before assignment leaves the selection unchanged. An unconfirmed
837
+ assignment returns `actionStatus="unknown"` and `retryable=false`; inspect the page before deciding what to do next.
477
838
 
478
839
  ### extract - Content Extraction
479
840
 
@@ -491,40 +852,91 @@ Text extraction uses the browser's `innerText` for HTML pages and selected eleme
491
852
  `style`/`script` source and hidden descendants. Explicitly selected non-rendered HTML follows the browser's `innerText`
492
853
  rules; SVG/XML nodes use `textContent`. Use `html` for source markup.
493
854
 
494
- Parameters: `output` saves result to file (or directory for `images=data`). `images` (`info`/`data`) extracts image
495
- metadata or data alongside HTML. `frameHtml` extracts the current iframe document after `frame` routing. Screenshot
496
- accepts `clip` for coordinate-region capture, `compareWith` for PNG baseline comparison, and `diffOutput` for a PNG diff
497
- image. `diffOutput` requires `compareWith`. A `target` screenshot that has no match, whose `nth` is out of range, or
498
- whose box has zero size returns a target error rather than silently returning a viewport screenshot. Screenshot
499
- responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`, `scale`, `clip`, and
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.
855
+ #### Text windows
856
+
857
+ `extract(type="text", maxChars=12000, offset=0)` returns that UTF-16 text window with `totalLength`, `nextOffset` and
858
+ `truncated`. Use `nextOffset` for the next read. Each request reads the current page; changing page text can change
859
+ subsequent offsets. With `output`, the file contains the requested window. Omitting both parameters retains the
860
+ full-text response and full-text file behavior.
861
+
862
+ #### HTML and images
863
+
864
+ `output` saves to a file, or a directory for `images=data`. `images=info|data` includes image metadata or bytes with
865
+ HTML. Image data is limited to 2 MiB per image and 8 MiB per request. Directory export reads and writes one image at a
866
+ time; each index entry records an `omitted` reason for unavailable or over-budget data. Inline output keeps the first 20
867
+ images with the same reasons and byte budgets. `frameHtml` reads the current document after `frame` routing. HTML with
868
+ images applies the full semantic locator, exact match and nth index to its final element selection.
869
+
870
+ #### Screenshots
871
+
872
+ Use `clip` for a coordinate region, `compareWith` for a PNG baseline and `diffOutput` for a PNG difference image.
873
+ `diffOutput` requires `compareWith`. An unmatched, out-of-range or zero-sized target returns a target error. Responses
874
+ contain `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`, `scale`, `clip` and
875
+ `capabilities`.
876
+
877
+ Capture limits are 16,384 pixels per side, 12,000,000 pixels total, 48 MiB estimated RGBA memory and 25 MiB encoded
878
+ data. Oversized captures return `SCREENSHOT_BUDGET_EXCEEDED` with the applicable limits. PNG baselines are checked
879
+ before reading. Comparison limits each PNG to 25 MiB and 12,000,000 pixels; inflate output and scanline lengths must
880
+ match the validated dimensions. Malformed or expansion-heavy PNGs are rejected. Use `clip` or `scale` for larger
881
+ captures.
882
+
883
+ Screenshot and diagnostic-bundle capabilities report `hiddenTabScreenshot=false` in both backends. A hidden Extension
884
+ tab returns `HIDDEN_TAB_SCREENSHOT`. Full-page capture preserves viewport and device emulation. If another debugger
885
+ blocks precise capture, viewport fallback reports `metadata.degraded`, `metadata.fallback` and `metadata.limitations` in
886
+ inline and file output. A window-level capture is discarded when the active tab changes, including A-to-B-to-A.
887
+ Unsupported fallback options return `SCREENSHOT_FALLBACK_UNSUPPORTED`.
888
+
889
+ Element screenshots use the painted intersection with overflow ancestors according to the actual positioning containing
890
+ block, including direct absolute targets and normal-flow descendants inside absolute/fixed ancestors. Scroll positions
891
+ and viewport size stay unchanged. Cropped captures report `clippedToVisibleArea=true`; an entirely clipped target
892
+ returns `ELEMENT_NOT_VISIBLE`. Unmappable transformed overflow geometry returns `FRAME_GEOMETRY_UNAVAILABLE`.
893
+
894
+ Extension automatic iframe crops require an available translation-only offset. Motion-path rotation on the iframe or
895
+ its composed ancestors returns `FRAME_GEOMETRY_UNAVAILABLE`; a motion path with explicit zero rotation keeps the
896
+ translation mapping. CDP maps all target corners through native frame geometry; unavailable or non-affine mappings
897
+ return `FRAME_GEOMETRY_UNAVAILABLE`. Both backends add
898
+ root-page scrolling to the root-viewport rectangle to obtain the page-coordinate clip, then restore the previous frame;
899
+ Extension also restores its documentId. Explicit `clip` uses root-page coordinates.
900
+
901
+ #### State and metadata
902
+
903
+ `state` returns `interactiveElements`. Both backends return metadata `frames` and the actual document `url`; Extension
904
+ `frame` routing returns the selected document's URL. Unavailable declared CDP frame fields remain `null`, including DOM
905
+ selectors and owner rectangles. Frame-tree order and IDs are preserved.
906
+
907
+ Metadata includes current `managed` state and `createdBy`, `createdAt`, `lastUsedAt`, `taskHint` and `note`, matching
908
+ `browse list` and `manage pageMetadata` in both inline and file output. Notes belong to the page even when `frame`
909
+ selects an iframe document. Extension preserves creation records, notes and trusted group relationships across Server
910
+ and Extension reloads, checking live identity during restoration. Another Extension Server reads the same saved
911
+ metadata. CDP notes belong to the current Server process; a new CDP Server starts with unknown provenance and no task
912
+ notes. Unknown provenance stays `unknown`; notes grant no access or cross-session ownership. CDP returns `managed=false` while
913
+ retaining normal operations through its connection.
914
+
915
+ Page selection uses `targetId` or legacy `tabId`; `frame` selects a child or nested document in either backend.
517
916
 
518
917
  **`attribute` special prefix**: `computed:<property>` returns the computed CSS style value (e.g. `computed:color`,
519
918
  `computed:font-size`). Use `computed:*` to return all computed style properties as JSON (returns 300+ properties — use
520
919
  `output` to save to file).
521
920
 
921
+ `extract.timeout` is the overall browser-operation budget in milliseconds (default 30000), including queueing,
922
+ page/frame preparation, target waiting, content reads, and page-context metadata. Each RPC uses the remaining budget;
923
+ `state` does not start a separate 30-second wait. An unconfirmed dispatched request returns unknown and is not replayed.
924
+
522
925
  **`state`-specific**: `depth` controls accessibility-tree traversal depth (default 15). Reduce it to limit response size
523
926
  on large pages. `mode` selects `accessibility` (default, derived from the a11y tree) or `domsnapshot` (raw
524
927
  `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.
928
+ and rejects `target`, `frame`, and `depth`. Ordinary read grants cover accessibility state; Extension DOMSnapshot
929
+ requires full managed access to use the debugger. Unavailable sibling iframe probes are listed in metadata as
930
+ `unavailableFrames` and per-frame `unavailableReason`; a uniquely verified selected iframe remains usable.
931
+
932
+ `target` restricts accessibility state to the selected element and its descendants in both backends. `depth` is relative
933
+ to that subtree. On background CDP documents, role/name lookup uses the browser's accessibility snapshot for the selected
934
+ frame and preserves substring, exact-name and `nth` matching without selecting the tab.
935
+
936
+ Accessibility state does not read hidden/password/file input value getters for element names or state text, including
937
+ default `all`, subtrees and file output. Hidden controls retain their labels and `visible=false`. Labels, placeholders
938
+ and titles provide names; ordinary inputs retain current values separately in `value` and `pageContent`, including named
939
+ inputs. Submit labels retain their full text. Explicit script, HTML and attribute reads keep their existing behavior.
528
940
 
529
941
  ### wait - Wait for Conditions
530
942
 
@@ -535,7 +947,8 @@ access. Unavailable sibling iframe probes are listed in metadata as `unavailable
535
947
  | `time` | Fixed delay |
536
948
  | `idle` | Wait for DOM or network quiet period |
537
949
 
538
- Parameters: `targetId` (or `tabId`) selects a page in either backend; `frame` selects an iframe in Extension mode.
950
+ Parameters: `targetId` (or `tabId`) selects a page in either backend; `frame` selects a child document or nested path in
951
+ either backend.
539
952
 
540
953
  In CDP mode, `visible` requires a nonzero DOM rectangle and CSS that does not hide the element (`display:none` or
541
954
  `visibility:hidden/collapse`). `hidden` accepts these hidden states or a missing element; `attached` and `detached` only
@@ -545,23 +958,25 @@ check whether the element exists.
545
958
  a quiet period with no DOM changes. In CDP mode, it waits for network quiet instead. `ms` controls the relevant quiet
546
959
  period (default 500ms). The response returns `idleKind` and `idlePeriodMs`; Extension responses also return `domStable`.
547
960
 
961
+ CDP idle includes requests already in flight. Independent idle and same-document `networkidle` exclude Worker requests
962
+ with an empty `loaderId`, whose terminal events can be absent from the page session; page Fetch and Script requests
963
+ remain pending until completion.
964
+
548
965
  ### evaluate - JavaScript Execution
549
966
 
550
967
  Execute JavaScript in page context.
551
968
 
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 |
969
+ - `script`: JavaScript code. Bare `return` statements are wrapped in IIFE
970
+ - `scriptFile`: Read code from a local file instead of `script`
971
+ - `args`: Function arguments; `[]` invokes a zero-argument function, omission evaluates the script as written
972
+ - `mode`: `precise` (default, debugger API) or `stealth` (JS injection)
973
+ - `staleContextRetry`: iframe stale-context policy: `never` (default) or `readOnly`
974
+ - `output`: Save the result to a file
975
+ - `targetId` / `tabId`: Select a page in either backend (`tabId` is an alias)
976
+ - `frame`: Target a child iframe by CSS selector/index, or use a nested path such as `["#outer", 0]` in either backend
977
+ - `timeout`: End-to-end budget (ms)
978
+ - `diagnostics`: Return new console warnings/errors and failed requests after execution
979
+ - `postCondition`: Wait for text, selector, URL fragment, or script result after execution
565
980
 
566
981
  `script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
567
982
  paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
@@ -574,54 +989,88 @@ such as `textContent` or `outerHTML`. Result materialization and serialization f
574
989
  `actionStatus="completed"`, and `failureStage="output"` because the page script has already finished. Evaluate defaults
575
990
  to `precise` even when global `inputMode` is `stealth`, and its `postCondition` checks use the same evaluate mode as the
576
991
  action. `postCondition` is optional; when it is not provided, `success=true` only means the script executed and
577
- returned. When it is provided and does not match before timeout, the tool returns `POST_CONDITION_FAILED` with the last
578
- observed checks. Precise iframe evaluation does not replay a script after a stale execution context by default. Set
579
- `staleContextRetry="readOnly"` only when the script has no side effects; the Extension may then resolve a new context
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.
992
+ returned. With a post-condition, `verificationStatus` distinguishes `matched`, `not_matched`, `unavailable` and `error`,
993
+ with the last observed checks. A completed script keeps `actionStatus="completed"` and top-level `retryable=false`;
994
+ `postCondition.retryable` applies only to an independent verification read. Precise iframe evaluation does not replay a
995
+ script after a stale execution context by default. Set `staleContextRetry="readOnly"` only when the script has no side
996
+ effects; the Extension may then resolve a new context and replay it once within the remaining timeout budget. If Chrome
997
+ still reports the removed document while resolving that retry, the Extension waits for the current document within the
998
+ same budget; this does not add script executions. Permission failures stop immediately. CDP iframe execution supports
999
+ `never`; requesting `readOnly` returns `DRIVER_CAPABILITY_ERROR` with `actionExecuted=false` and
1000
+ `actionStatus="not_started"` before script dispatch. A stale-context error after `Runtime.evaluate` reports
1001
+ `actionExecuted=true`, `actionStatus="unknown"` and `retryable=false` in both backends, because earlier side effects may
1002
+ already have happened even though the final result is unavailable. CDP preserves its native `CDP_ERROR`. Built-in
1003
+ post-condition reads use `never` on CDP and `readOnly` on Extension; the verifier polls stale read contexts
1004
+ independently of the completed action.
1005
+
1006
+ The total evaluate timeout also limits post-condition checks. If it expires after the action completes, the action stays
1007
+ completed and verification returns unavailable. A queue timeout before script dispatch preserves `actionExecuted=false`
1008
+ and the queue stage; a dispatched script with an unknown acknowledgement stays unknown. Read the page independently to
1009
+ determine its effects.
585
1010
 
586
1011
  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.
1012
+ budget, a depth limit of 64 and a 100000-node budget. Without `output`, the 1000000-character, depth-8 and 2000-node
1013
+ budgets still apply, including automatic saving. Both paths reject non-serializable results. The character budget counts
1014
+ UTF-16 code units, not the output file's UTF-8 bytes; `tmp:` files also remain subject to the temporary output quota.
1015
+ Exceeding a result limit reports the current limit and the completed script's output failure without replaying it.
1016
+
1017
+ Request summaries retain in-flight completion and failure records across temporary target selection.
1018
+
1019
+ Absolute `scriptFile` and `output` paths must resolve inside the Server working directory or this Server session's
1020
+ controlled temporary directory. The operating system's whole temp directory and Downloads are not automatic allowed
1021
+ roots. `PATH_NOT_ALLOWED` reports the actual `error.context.allowedRoots`; use `cwd:` or `tmp:` paths within them.
1022
+
1023
+ Responses include the stale-context policy, `retryAttempted`, bounded `retryReason` and the final `frameContext`:
1024
+ Extension frame, parent frame, URL, CDP frame and execution-context IDs. Same-URL frames are rejected only when the
1025
+ selected DOM iframe cannot identify one target. Existing iframe targets remain usable after an Extension reload without
1026
+ refreshing or navigating the page. Invalidated probe contexts report a warning and stop listening.
1027
+
1028
+ Sibling frames still loading do not delay selection of an available iframe. Background-page timer throttling does not
1029
+ extend the frame-probe wait. Cancellation or timeout before script dispatch releases the probes and leaves that script
1030
+ unexecuted.
1031
+
1032
+ A trusted Function-compilation policy rejection reports `CSP_BLOCKED` with the script not executed. Page `throw` or
1033
+ Promise rejection keeps its original error and executed state even when the text contains `CSP`,
1034
+ `Content Security Policy` or `unsafe-eval`.
591
1035
 
592
1036
  ### manage - Page & Environment Management
593
1037
 
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`) |
1038
+ | Action | Description |
1039
+ | ------------------ | ------------------------------------------------------------------------ |
1040
+ | `newPage` | Create new controlled page/tab |
1041
+ | `pageMetadata` | Read or update per-page `taskHint` and `note` |
1042
+ | `closePage` | Close page and return `affected.before/after` in Extension and CDP modes |
1043
+ | `adoptPage` | Grant full controlled-page access without focusing it |
1044
+ | `releasePage` | Remove a controlled tab from management without closing it |
1045
+ | `grantReadAccess` | Grant ordinary reads for an explicit page to the calling instance |
1046
+ | `revokeReadAccess` | Revoke that instance's ordinary read grant |
1047
+ | `updatePage` | Update native tab properties and return actual state |
1048
+ | `movePage` | Move a controlled tab to another window or index |
1049
+ | `reorderPage` | Reorder a controlled tab inside its window |
1050
+ | `pinPage` | Pin a controlled tab |
1051
+ | `unpinPage` | Unpin a controlled tab |
1052
+ | `activatePage` | Activate an explicit page; Extension requires a controlled tab |
1053
+ | `focusWindow` | Focus an explicit window |
1054
+ | `resizeWindow` | Resize or change state for an explicit window |
1055
+ | `newWindow` | Create a new controlled window |
1056
+ | `closeWindow` | Close a window only when all tabs are managed |
1057
+ | `updateWindow` | Update native window position, state, focus or attention |
1058
+ | `groupPages` | Create a group or add controlled tabs to an existing group |
1059
+ | `ungroupPages` | Remove controlled tabs from groups without releasing them |
1060
+ | `updateGroup` | Update group title, color and collapsed state |
1061
+ | `moveGroup` | Move a group and its tabs to a window or index |
1062
+ | `clearCache` | Clear cache/storage (use `cookies` tool to clear cookies) |
1063
+ | `viewport` | Set viewport size |
1064
+ | `userAgent` | Set User-Agent |
1065
+ | `emulate` | Device emulation (iPhone, iPad, etc.) |
1066
+ | `inputMode` | Query or set input mode (`precise` / `stealth`) |
1067
+ | `stealth` | Inject anti-detection scripts |
1068
+ | `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
1069
+ | `dialog` | Observe or handle dialogs |
1070
+ | `networkCapture` | Start or stop original request/body/stream collection |
1071
+ | `route` | Match and resolve paused requests |
1072
+ | `httpAuth` | Set or clear scoped HTTP challenge credentials |
1073
+ | `download` | Observe, wait for, and save an original download |
625
1074
 
626
1075
  Native tab/window/group configuration uses Extension mode; `activatePage` also supports CDP. Mutations identify their
627
1076
  existing targets with `targetId`, `targetIds`, `windowId`, or `groupId` and return `affected.before/after`. Group
@@ -629,10 +1078,10 @@ results also include `tabsBefore/tabsAfter`; `ungroupPages` removes an empty gro
629
1078
  tabs' managed state. Window display changes and group title/color/collapse updates use the explicit `windowId` or
630
1079
  `groupId`, including containers with unmanaged members. They do not grant page permissions. Group moves and window
631
1080
  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
1081
+ unrelated sibling changes do not invalidate a valid selection. Default page creation uses an existing normal window in
1082
+ the background, including windows with unmanaged tabs. `clearCache` is unavailable in Extension mode and returns
1083
+ `UNSUPPORTED_MODE` without clearing anything. Use scoped `cookies(action="clear")` for cookies or CDP mode for storage
1084
+ and cache. `focusWindow` only returns success after the target window is observed as focused; otherwise it returns
636
1085
  `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with unmanaged tabs and returns
637
1086
  `WINDOW_HAS_UNMANAGED_TABS`. Persistent `adoptPage` and `releasePage` target changes are serialized with scoped tab
638
1087
  operations, so a concurrent multi-event input remains on its requested tab and the persistent target is applied
@@ -645,22 +1094,65 @@ restrictions. Querying `manage(action="emulate")` without `device` returns the l
645
1094
  page; page conditions are rejected for this query. Setting a device continues to validate the selected page and
646
1095
  conditions.
647
1096
 
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 |
1097
+ #### `newPage`
1098
+
1099
+ Parameters: `url`, `windowId`, `index`, `active`, `pinned`, `openerTabId`, `groupId`, `timeout`, `taskHint`, `note`
1100
+
1101
+ `active` defaults to false; `groupId=-1` disables grouping; explicit placement is not changed by the default visual
1102
+ group
1103
+
1104
+ #### `updatePage`
1105
+
1106
+ Parameters: `url`, `active`, `pinned`, `highlighted`, `muted`, `autoDiscardable`, `openerTabId`
1107
+
1108
+ Requires `targetId`; only `active=true` is supported and does not focus the window; `active=false` is rejected before
1109
+ any update
1110
+
1111
+ #### `groupPages`
1112
+
1113
+ Parameters: `targetIds`, `groupId`, `windowId`, `title`, `color`, `collapsed`
1114
+
1115
+ Omit `groupId` to create a group in the members' window; mixed-window members require `windowId`; joining an existing
1116
+ group accepts only `targetIds/groupId`
1117
+
1118
+ #### `ungroupPages`
1119
+
1120
+ Parameters: `targetIds`
1121
+
1122
+ Removes group membership and retains controlled-page access
1123
+
1124
+ #### `updateGroup`
1125
+
1126
+ Parameters: `groupId`, `title`, `color`, `collapsed`
1127
+
1128
+ An empty title and false collapsed value are applied as supplied
1129
+
1130
+ #### `moveGroup`
1131
+
1132
+ Parameters: `groupId`, `windowId`, `index`
1133
+
1134
+ Moves all members; `index=-1` means the end of the window
1135
+
1136
+ #### `newWindow`
1137
+
1138
+ Parameters: `url` or `urls`, `targetId`, `windowType`, `focused`, `incognito`, `left`, `top`, `width`, `height`,
1139
+ `windowState`, `setSelfAsOpener`
1140
+
1141
+ `normal` supports multiple URL tabs and an existing controlled tab; `popup` accepts only one page; created tabs are
1142
+ managed with distinct provenance
1143
+
1144
+ #### `updateWindow` / `resizeWindow`
1145
+
1146
+ Parameters: `windowId`, `left`, `top`, `width`, `height`, `windowState`, `focused`, `drawAttention`
1147
+
1148
+ Applies supported Chrome window properties and returns observed state
658
1149
 
659
1150
  `updateWindow` and `resizeWindow` wait for a stable browser observation when changing state or geometry. Restoring a
660
1151
  non-normal window with `windowState="normal"` and bounds completes the state transition before applying bounds once.
661
1152
  OS-adjusted geometry is returned as observed. If observation does not stabilize within the bounded wait,
662
1153
  `WINDOW_UPDATE_NOT_OBSERVED` reports partial execution and the last observed window state; inspect `browse list` before
663
- another update.
1154
+ another update. If Chrome rejects bounds outside visible screen space, use coordinates and dimensions within the
1155
+ screen's available area; the response preserves the bounds error without page-activation guidance.
664
1156
 
665
1157
  `browse list` defaults to `details="summary"`, returning target identity, URL/title, placement, managed/revision and
666
1158
  metadata. Set `details="full"` for highlighted/muted/discardable state, opener IDs and available native readonly
@@ -672,9 +1164,9 @@ state, window, first-member index and member IDs. Color belongs to a group, not
672
1164
  when Chrome supplies them, not accepted as configuration writes. Listing does not read page content, navigate or focus.
673
1165
 
674
1166
  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.
1167
+ populate group members and first-member index. Summary/full details and filters remain available without another RPC. If
1168
+ group information is absent entirely, `groups` is omitted with a warning that it is unavailable. A supplied `groups: []`
1169
+ means no groups. Malformed group data, including only one member array, returns an error.
678
1170
 
679
1171
  Moving tabs/groups accepts `index=-1`; page creation requires a nonnegative index. Opener and explicit group/window
680
1172
  options must identify the same window. Pinned tabs cannot be created inside a group. Window state/bounds conflicts and
@@ -686,6 +1178,7 @@ revision. Once a native update has been dispatched, a failure still invalidates
686
1178
 
687
1179
  `emulate` applies the device viewport, pixel density, touch support, and User-Agent in both backends. `viewport`
688
1180
  restores desktop metrics, page scale, and disabled touch emulation; restore the User-Agent separately with `userAgent`.
1181
+ `manage(action="userAgent", userAgent="")` clears the page override.
689
1182
 
690
1183
  **Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
691
1184
 
@@ -693,25 +1186,158 @@ restores desktop metrics, page scale, and disabled touch emulation; restore the
693
1186
  - `safe` (default) — minimal patches (remove `navigator.webdriver`, clean CDP traces)
694
1187
  - `aggressive` — adds a few WebGL/plugin/language fingerprint patches (does NOT equal full masking)
695
1188
 
1189
+ Management operations share a 30000 ms request deadline; `newPage` uses a supplied `timeout`. An expired queued change
1190
+ is rejected before dispatch. Unconditional `pageMetadata` reads, updates and clears use the explicit target
1191
+ independently of a long page action, including on the same page. Each request keeps its own URL/revision conditions.
1192
+ URL/revision-conditioned metadata keeps serialized condition checking.
1193
+
1194
+ Moving an existing page into a new window and group operations serialize with page release and recheck native membership
1195
+ and managed authority under the affected page locks. Page creation uses `active`; `activate` is accepted only by
1196
+ `movePage`.
1197
+
1198
+ ### Browser events and original files
1199
+
1200
+ Prepare observation before clicking a download link, opening a dialog, or making a request. Use the returned `ref` to
1201
+ read or handle that exact event. These actions use the controlled page selected by `targetId` or the current default. A
1202
+ reference retains its original page even after the default target changes. Default-target event configuration waits for
1203
+ temporary page actions to restore the selected page; ref-directed dialog and Fetch handling remain independent.
1204
+ Reconnecting the same server instance waits for its previous event resources to finish cleanup.
1205
+
1206
+ | `manage` action | Nested command |
1207
+ | ---------------- | --------------------------------------------------------------- |
1208
+ | `dialog` | `dialog:{op:"watch"\|"stop"\|"accept"\|"dismiss",ref?,text?}` |
1209
+ | `networkCapture` | `capture:{op:"start"\|"stop",include?:["body","stream"]}` |
1210
+ | `route` | `route:{op:"add"\|"remove"\|"continue"\|"fulfill"\|"fail",...}` |
1211
+ | `httpAuth` | `auth:{op:"set"\|"clear",...}` |
1212
+ | `download` | `download:{op:"watch"\|"stop"\|"wait"\|"save",...}` |
1213
+
1214
+ - `dialog`: Observe dialogs or handle one observed dialog; `text` supplies a prompt answer
1215
+ - `networkCapture`: Record original requests, optional bodies, and WebSocket/SSE messages
1216
+ - `route`: Match page requests or handle an observed paused request
1217
+ - `httpAuth`: Configure credentials for an explicit Server/Proxy challenge scope
1218
+ - `download`: Identify a download, wait for its native state, and save available original bytes
1219
+
1220
+ #### Handle a dialog
1221
+
1222
+ ```text
1223
+ manage(action="dialog", targetId="PAGE_ID", dialog={op:"watch"})
1224
+ input(targetId="PAGE_ID", events=[{type:"click", target:{css:"#show-prompt"}}])
1225
+ logs(type="dialog", targetId="PAGE_ID")
1226
+ manage(action="dialog", dialog={op:"accept", ref:"DIALOG_REF", text:"Answer"})
1227
+ ```
1228
+
1229
+ A blocking dialog returns `DIALOG_OPEN` and its reference. Handle it, then check the original action's result. Dialog
1230
+ reads and handling remain available while that original request is blocked. `dismiss` omits `text`; `stop` ends
1231
+ observation. Log reads leave the dialog unchanged.
1232
+
1233
+ #### Read the original response
1234
+
1235
+ ```text
1236
+ manage(action="networkCapture", targetId="PAGE_ID", capture={op:"start", include:["body","stream"]})
1237
+ logs(type="network", targetId="PAGE_ID", view="details")
1238
+ logs(type="network", view="responseBody", ref="REQUEST_REF", output="tmp:response.bin")
1239
+ ```
1240
+
1241
+ `details` retains request identity, redirect hop, base headers, ExtraInfo headers, and their completeness. `requestBody`
1242
+ reads original POST data; `responseBody` reads the protocol-provided entity body. An explicit `output` saves decoded
1243
+ bytes. Inline bodies use `{encoding:"utf8"|"base64",data}`. Unavailable or evicted bodies return an error; multipart
1244
+ file parts and redirect bodies depend on native protocol availability. A body must be below 16 MiB. Headers, Cookie
1245
+ metadata copies such as `cookieLine`, and credential URL fields are redacted. URL-bearing headers such as `Location`,
1246
+ `Content-Location` and `Referer` also redact user information and sensitive query values in structured metadata and raw
1247
+ handshake header text; explicitly requested body content retains its bytes.
1248
+
1249
+ `view="stream"` returns WebSocket directions/opcodes and SSE messages in observed order. Inspect truncation, `dropped`
1250
+ and `evicted` fields when consuming bounded buffers. Use `capture:{op:"stop"}` to end collection.
1251
+
1252
+ #### Continue or mock a matched request
1253
+
1254
+ Add a route with `urlPattern` and optional `stage:"Request"|"Response"`. Read `logs(type="network",view="paused")`, then
1255
+ handle the returned paused-request reference:
1256
+
1257
+ ```text
1258
+ manage(action="route", targetId="PAGE_ID", route={op:"add", urlPattern:"https://example.com/api/*"})
1259
+ logs(type="network", targetId="PAGE_ID", view="paused")
1260
+ manage(action="route", route={
1261
+ op:"fulfill", ref:"PAUSED_REF", response:{status:200, body:{encoding:"utf8",data:"mock"}}
1262
+ })
1263
+ ```
1264
+
1265
+ `continue` accepts optional `request:{url?,method?,headers?,body?}`; headers are `{name,value}` arrays. `fulfill`
1266
+ requires `response:{status,statusText?,headers?,body?}`. `fail` accepts a native `errorReason`, defaulting to `Aborted`.
1267
+ Remove a rule with `op:"remove"` and its rule reference. Unmatched requests continue immediately. Matched pauses expire
1268
+ after 30 seconds; cancellation, navigation, release or owner disconnection aborts unresolved requests. A native
1269
+ acknowledgement loss retains an unknown result and is not automatically resent. `clear` clears readable records while
1270
+ active pauses and dialogs keep their handling references. Raw `manage cdp` Fetch commands share this ownership and
1271
+ cleanup.
1272
+
1273
+ For HTTP authentication, set `auth:{op:"set",scope:{source:"Server"|"Proxy",origin,realm?},username,password}`.
1274
+ Credentials stay in memory for that page and exact challenge scope. Failed repeat challenges are canceled. Read
1275
+ `logs(type="network",view="auth")` for redacted status, and use `auth:{op:"clear"}` to remove credentials.
1276
+
1277
+ #### Save a download
1278
+
1279
+ ```text
1280
+ manage(action="download", targetId="PAGE_ID", download={op:"watch",urlPattern:"https://example.com/files/*"})
1281
+ input(targetId="PAGE_ID", events=[{type:"click",target:{css:"a.download"}}])
1282
+ logs(type="download", targetId="PAGE_ID")
1283
+ manage(action="download", download={op:"wait",ref:"DOWNLOAD_REF",timeout:30000})
1284
+ manage(action="download", download={op:"save",ref:"DOWNLOAD_REF",output:"tmp:attachment.bin"})
1285
+ ```
1286
+
1287
+ The native download GUID and state distinguish completion from file availability. `save` requires a completed download
1288
+ with `artifact="available"`; it writes the captured original response without making another HTTP request. Native Save
1289
+ As, blob downloads or browser security restrictions can leave the file unavailable, with the reason reported.
1290
+ Shared-browser download policy remains unchanged. This capture path uses the same below-16-MiB body budget.
1291
+ `download:{op:"stop"}` ends observation and releases its interception.
1292
+
1293
+ After stopping, suspension or a document change, late body replies retain their original observation identity; a later
1294
+ same-URL download GUID cannot inherit those bytes. A body binds to a GUID only for one matching candidate with the same
1295
+ frame, URL, native session, observation generation and document revision. Reliably bound historical downloads remain
1296
+ readable through their original refs until eviction or controller disposal.
1297
+
1298
+ References are bound to the server instance, page and connection generation. Stale or foreign references are rejected.
1299
+ Cloudflare handling ends current Fetch control and suspends these observations before detaching the debugger; inspect
1300
+ the returned `browserEvents` status and explicitly start observation again after verification. New event actions require
1301
+ matching Server and Extension builds; missing native capabilities are reported before enabling interception. CDP
1302
+ authentication and response capture remain active after the connection request finishes. Each later tool call uses its
1303
+ own timeout and cancellation signal.
1304
+
1305
+ Cleanup failure retains the original controller, owner and unresolved resources. A later event action from the same
1306
+ Server first retries cleanup under that owner's control; new observation starts after cleanup succeeds. Unknown paused
1307
+ requests continue to block new configuration and debugger detach, returning the cleanup error and actual state while
1308
+ their handling refs remain valid. Confirmed native session or page termination releases the corresponding barrier.
1309
+
1310
+ `cleanupFailures` retains the existing string array. The parallel `cleanupFailureDetails` records timestamp, phase,
1311
+ observed ref or request ID, target, owner and session generation. Each controller retains at most 20 failures and clears
1312
+ them when disposed. A new controller starts empty; details already returned retain their original ownership. Console
1313
+ metadata and error messages redact sensitive URL query values; requested page text and body files retain their content.
1314
+
696
1315
  ### logs - Browser Logs
697
1316
 
698
- | Type | Description |
699
- | --------- | -------------------------------------- |
700
- | `console` | Console logs (with level filter) |
701
- | `network` | Network request logs (with URL filter) |
1317
+ | Type | Description |
1318
+ | ---------- | -------------------------------------------------------------------------- |
1319
+ | `console` | Console logs (with level filter) |
1320
+ | `network` | Request summary, details, bodies, paused requests, auth or stream messages |
1321
+ | `dialog` | Observed dialog references and pending/closed state |
1322
+ | `download` | Native download state and original-file availability |
702
1323
 
703
1324
  Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and
704
1325
  `debug`; raw browser levels such as `warn` and `log` are normalized before filtering and return. Clearing fallback
705
1326
  console logs keeps the hook active. When debugger collection becomes available, fallback capture is disabled. Console
706
1327
  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`.
1328
+ Independent fallback console calls retain their levels and frequency even when their timestamp and text are identical;
1329
+ reading the same drained batch again does not append it again. Switching to debugger collection preserves pending calls
1330
+ once, without adding their Runtime history replay a second time or restoring cleared fallback calls. The buffer retains
1331
+ the latest 1000 entries. Network logs are finalized on `loadingFinished` or `loadingFailed`, not when headers arrive, so
1332
+ body failures retain both the HTTP status and `errorText`, and in-flight bodies continue to count against `networkidle`.
1333
+ Entries include `method`, `url`, `status`, `timestamp`, and `duration` when available. URL query parameters commonly
1334
+ used for credentials, signatures, passwords, and tokens are replaced with `[REDACTED]` in inline responses, diagnostics,
1335
+ and explicit `output` files. Redacted entries include `urlRedacted`, `urlOriginalLength`, and `redactedQueryParameters`.
712
1336
  Inline network results limit each sanitized URL to 2048 characters and add `urlLength` plus `urlTruncated: true` when
713
1337
  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.
1338
+ tab (Extension mode). `frame` is not applicable for logs. In network views, `urlPattern` filters each request's URL,
1339
+ including paused requests and authentication events, before applying `limit`. `clear` preserves requests that still need
1340
+ handling.
715
1341
 
716
1342
  When the Extension debugger is unavailable, network reads refresh performance entries and mark them with
717
1343
  `source="performance"`. Status uses the browser's `responseStatus` when available, or `0` otherwise; unknown request
@@ -719,6 +1345,10 @@ methods remain empty. Repeated reads preserve record sequences. `clear` clears M
719
1345
  document's read boundary without clearing the page's shared performance timeline. A new document starts a new boundary.
720
1346
  Read failures return an error rather than an empty log.
721
1347
 
1348
+ CDP network logs keep the HTTP status when a response body fails and record one terminal entry per request. Temporary
1349
+ page selection preserves each target's log buffer. Clearing logs removes buffered entries while keeping in-flight
1350
+ requests until their final event, so a request completed after clearing appears in the new log.
1351
+
722
1352
  ### cookies - Cookie Management
723
1353
 
724
1354
  | Action | Description |
@@ -728,54 +1358,41 @@ Read failures return an error rather than an empty log.
728
1358
  | `delete` | Delete cookie |
729
1359
  | `clear` | Delete cookies in a URL or domain scope, optionally narrowed by `name` |
730
1360
 
731
- **Note**: `clear` requires `url` or `domain`. `name` can only further narrow that scope, so a same-named cookie on
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.
734
-
735
- ## Target: Unified Element Locator
736
-
737
- All tools use a unified `Target` type for element location:
738
-
739
- ```typescript
740
- // By accessibility (recommended - most stable)
741
- const byRole = { role: 'button', name: 'Submit' }
742
-
743
- // By accessibility with exact accessible name
744
- const byExactRole = { role: 'button', name: 'Submit', exact: true }
745
-
746
- // By text content
747
- const byText = { text: 'Click here', exact: true }
748
-
749
- // By form label
750
- const byLabel = { label: 'Email' }
751
-
752
- // By placeholder
753
- const byPlaceholder = { placeholder: 'Enter your name' }
754
-
755
- // By title attribute
756
- const byTitle = { title: 'Close dialog' }
757
-
758
- // By alt text (images)
759
- const byAlt = { alt: 'Profile picture' }
760
-
761
- // By test ID
762
- const byTestId = { testId: 'submit-button' }
763
-
764
- // By CSS selector
765
- const byCss = { css: '#login-form .submit-btn' }
766
-
767
- // Disambiguate multiple matches (0-based)
768
- const secondMatch = { css: '.ant-select-input', nth: 1 }
769
-
770
- // By CSS + text (filter by text content)
771
- const byCssText = { css: 'button', text: 'Submit', exact: true }
772
-
773
- // By XPath
774
- const byXPath = { xpath: "//button[@type='submit']" }
775
-
776
- // By coordinates
777
- const byCoordinates = { x: 100, y: 200 }
778
- ```
1361
+ All actions accept `targetId`, `partitionKey:{topLevelSite?,hasCrossSiteAncestor?}`, and a backend-specific store scope:
1362
+ `storeId` for Extension or `browserContextId` for CDP. Extension resolves a supplied target to its native CookieStore
1363
+ and rejects a conflicting store. Unsupported backend scope fields return an error. Without these fields, existing
1364
+ URL/domain behavior remains unchanged. `get` requires at least one nonblank `name`, `domain`, or `url`; storage scopes
1365
+ and flags only narrow that explicit filter, including when exporting to a file.
1366
+
1367
+ URL path matching uses Cookie path boundaries in target and browser-context scopes too: a Cookie at `/app` matches
1368
+ `/app/info` and is excluded for `/apple/info`.
1369
+
1370
+ `clear` requires `url` or `domain`, with optional `name` to narrow the range. CDP preserves each selected Cookie's exact
1371
+ name, raw domain, path, partition and browser context for deletion. An omitted target is fixed to the current page's
1372
+ storage context when clear starts. An unserializable partition identity is rejected before deletion.
1373
+
1374
+ For CDP clear, `count` records identities present at the immediate precheck and absent after an acknowledged deletion
1375
+ request; `countSemantics="observed_present_then_absent"` identifies this state comparison. `acknowledged` counts native
1376
+ ACKs, `alreadyAbsent` counts identities missing at the initial check, and `matched` and `attempted` describe the
1377
+ selected candidates and started deletion steps. Concurrent page changes can occur between observations. Extension
1378
+ retains its native removal-confirmation count.
1379
+
1380
+ CDP stops at the first deletion, verification or cleanup failure and returns `COOKIE_CLEAR_PARTIAL` with the known
1381
+ count, ACKs, failed or unknown steps, unprocessed candidates, phase and original cause. Its action state preserves
1382
+ earlier changes and `retryable=false`; a session-detach failure retains the preceding ACK and any verified
1383
+ disappearance.
1384
+
1385
+ A deletion request sent without an ACK counts as `unknown` when the connection closes, is explicitly closed, times out
1386
+ or is canceled. The first unknown step reports `actionStatus="unknown"`; earlier ACKs keep the action `partial`.
1387
+ `failed` counts explicitly rejected or undispatched deletion steps and identities still present after an ACK.
1388
+ Unclassified errors after attempting deletion remain unknown, and later deletions stop.
1389
+
1390
+ MCP cancellation stops queued Cookie actions, connection waits and later deletions in both backends. CDP retains prior
1391
+ confirmed progress and an unacknowledged deletion's unknown result. A canceled or timed-out temporary attach retains
1392
+ responsibility for its native response: a late successful session is detached with an independent 1000 ms budget.
1393
+ Cleanup failure is logged with the command and session identity and remains tracked until the connection closes; no
1394
+ deletion is replayed. An Extension RPC canceled before its reply reports an unknown RPC result; the Extension stops its
1395
+ remaining native removals once the in-flight call settles.
779
1396
 
780
1397
  ## Usage Examples
781
1398
 
@@ -869,7 +1486,11 @@ subsequent output.
869
1486
  extract(type="metadata")
870
1487
  ```
871
1488
 
872
- ### iframe Operations (Extension Mode)
1489
+ ### Nested frame operations
1490
+
1491
+ Both backends resolve iframe selectors and indices through open ShadowRoots. Cross-origin and OOPIF frame preparation
1492
+ uses the original request deadline; a timeout before script dispatch reports `actionExecuted=false` and
1493
+ `actionStatus="not_started"` and attempts to restore the previous target.
873
1494
 
874
1495
  ```
875
1496
  // Target iframe by CSS selector
@@ -878,6 +1499,9 @@ evaluate(script="document.title", frame="iframe#main")
878
1499
  // Target iframe by index
879
1500
  extract(type="text", frame=0)
880
1501
 
1502
+ // Resolve each step relative to the selected parent, including OOPIFs in CDP
1503
+ evaluate(script="document.title", frame=["iframe#outer", "iframe#inner"])
1504
+
881
1505
  // Input inside iframe
882
1506
  input(events=[
883
1507
  { type: "mousedown", target: { label: "Username" } },
@@ -902,6 +1526,12 @@ calls keep their existing meaning; errors do not replay the script. When a read
902
1526
  diagnostics remove credentials, query strings, and fragments and are limited to 500 characters. `data:` and
903
1527
  `javascript:` URLs expose only the protocol; an unparseable URL reports `url=null` and `urlStatus="unavailable"`.
904
1528
 
1529
+ Extension text, attribute and accessibility-state queries use frame-local element identity and rectangles. Read-only
1530
+ queries in scaled, rotated and nested transformed frames need no debugger attachment for root-coordinate calibration.
1531
+ Input target lookup uses the same frame-local references, including touch, selection, editing commands, upload and drag.
1532
+ Native pointer calibration still accepts translation-only frame offsets; scaled or rotated owners return
1533
+ `FRAME_GEOMETRY_UNAVAILABLE` before an inferred origin is used.
1534
+
905
1535
  ### Wait for Element
906
1536
 
907
1537
  ```
@@ -939,6 +1569,25 @@ wait(for="element", target={ text: "Loading complete" }, state="visible")
939
1569
  └──────────┘
940
1570
  ```
941
1571
 
1572
+ ### Connection status and recovery
1573
+
1574
+ `browse(action="connect")` and the local `/api/info` endpoint report the active Extension background bundle hash and
1575
+ compare it with the bundle shipped beside the Server. `bundleStatus="stale"` means Chrome still runs an older bundle;
1576
+ reload that Extension in `chrome://extensions/`. A legacy Extension lacking `network_challenge_state` uses tab-title and
1577
+ DOM detection. Bundle identity does not block auto-connect.
1578
+
1579
+ Popup Disconnect immediately pauses local connections for the current Extension session, including Service Worker
1580
+ recovery. Connect resumes discovery; an Extension reload or Chrome restart restores auto-connect. When one Server
1581
+ restarts, the Extension retries it with the existing backoff while keeping other connections active; explicit Disconnect
1582
+ cancels those retries. Popup storage failures stay visible, and delayed old values cannot overwrite a newer choice. A
1583
+ temporary saved-pause read failure can recover on a later connection attempt in the same Worker; a pause-write failure
1584
+ remains visible.
1585
+
1586
+ Discovery reports the initial server-port set and changes, including an empty set. Every scan checks the full port
1587
+ range; unchanged scans and automatic reconnects do not repeat the summary. Explicit disconnect starts a new reporting
1588
+ cycle. Ordinary pre-open failures stay debug-level; authentication or protocol rejections from identified MCP servers
1589
+ produce one bounded warning when their summary changes.
1590
+
942
1591
  ## Project Structure
943
1592
 
944
1593
  ```
@@ -1002,7 +1651,27 @@ mcp-chrome/
1002
1651
  - Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still
1003
1652
  contain sensitive information
1004
1653
 
1005
- ### Anti-detection (stealth) — what it actually does
1654
+ ### Pairing and local access
1655
+
1656
+ Ordinary local use auto-discovers servers by default. On shared machines, CI runners or containers where untrusted
1657
+ processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the Server and enter the same token in
1658
+ the Extension popup:
1659
+
1660
+ ```bash
1661
+ MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
1662
+ ```
1663
+
1664
+ To enforce token use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` and disable "Allow no-token local connection" in the
1665
+ popup. This immediately cancels pending health checks, WebSocket handshakes and reconnects, ending older no-token
1666
+ attempts.
1667
+
1668
+ Token peers require authentication protocol v2. Commands, responses, cancellations and heartbeats use
1669
+ direction-separated session keys and increasing sequence numbers; health proofs bind both nonces, the Server instance
1670
+ and port. Extension becomes available after authenticated ready, and Server accepts requests after authenticated hello.
1671
+ Older strict-token peers return a protocol diagnostic; default no-token discovery and automatic reconnection stay
1672
+ available.
1673
+
1674
+ ### Anti-detection (stealth) capabilities
1006
1675
 
1007
1676
  The `stealth` mode (`safe` / `aggressive`) only patches a small set of fingerprinting surfaces:
1008
1677
 
@@ -1019,7 +1688,17 @@ The `stealth` mode (`safe` / `aggressive`) only patches a small set of fingerpri
1019
1688
  - **Chrome only**: Only supports Chrome/Chromium browsers (no Firefox/Safari)
1020
1689
  - **Single CDP session**: CDP mode supports one browser session at a time
1021
1690
  - **Extension mode requires Chrome**: Extension is Manifest V3, Chrome-specific
1022
- - **iframe**: Only single-level iframe targeting (no nested `>>` syntax); Extension mode only
1691
+ - **iframe**: Nested selection uses a selector/index array; XPath keeps its native document scope
1692
+
1693
+ ## Compatible Clients
1694
+
1695
+ | Client | Status |
1696
+ | ------------------------- | ------ |
1697
+ | Claude Code | ✅ |
1698
+ | Claude Desktop | ✅ |
1699
+ | Cursor | ✅ |
1700
+ | Windsurf | ✅ |
1701
+ | Any MCP-compatible client | ✅ |
1023
1702
 
1024
1703
  ## License
1025
1704
 
@@ -1029,54 +1708,3 @@ MIT License - see [LICENSE](LICENSE) for details.
1029
1708
 
1030
1709
  - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
1031
1710
  - [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP documentation
1032
-
1033
- ## Operation status and diagnostics
1034
-
1035
- Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and
1036
- `retryable`. Verification uses `matched`, `not_matched`, `unavailable`, or `error`; debugger timeouts report the action
1037
- as `unknown` when completion cannot be proven. Page-thrown exceptions report `actionExecuted=true` with
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.
1061
-
1062
- `replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other
1063
- input types use a native full-value update and return the requested and actual browser-normalized values. A standalone
1064
- `select` on unsupported types returns `UNSUPPORTED_SELECTION`. CDP locator targets for `select` and `replace` are
1065
- focused through the CDP locator instead of Extension-only ref IDs. Password values are omitted from input failure
1066
- context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text`
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.