@pyrokine/mcp-chrome 2.4.0 → 2.4.4

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 (116) hide show
  1. package/README.md +220 -149
  2. package/README_zh.md +245 -179
  3. package/dist/anti-detection/behavior.js +1 -1
  4. package/dist/anti-detection/behavior.js.map +1 -1
  5. package/dist/anti-detection/injection.d.ts.map +1 -1
  6. package/dist/anti-detection/injection.js +2 -1
  7. package/dist/anti-detection/injection.js.map +1 -1
  8. package/dist/cdp/client.d.ts +2 -2
  9. package/dist/cdp/client.d.ts.map +1 -1
  10. package/dist/cdp/client.js +7 -4
  11. package/dist/cdp/client.js.map +1 -1
  12. package/dist/core/browser-driver.d.ts +9 -3
  13. package/dist/core/browser-driver.d.ts.map +1 -1
  14. package/dist/core/browser-driver.js +1 -0
  15. package/dist/core/browser-driver.js.map +1 -1
  16. package/dist/core/errors.d.ts +9 -0
  17. package/dist/core/errors.d.ts.map +1 -1
  18. package/dist/core/errors.js +16 -1
  19. package/dist/core/errors.js.map +1 -1
  20. package/dist/core/os-mouse.d.ts +65 -0
  21. package/dist/core/os-mouse.d.ts.map +1 -0
  22. package/dist/core/os-mouse.js +334 -0
  23. package/dist/core/os-mouse.js.map +1 -0
  24. package/dist/core/session.d.ts +16 -6
  25. package/dist/core/session.d.ts.map +1 -1
  26. package/dist/core/session.js +160 -55
  27. package/dist/core/session.js.map +1 -1
  28. package/dist/core/types.d.ts +10 -0
  29. package/dist/core/types.d.ts.map +1 -1
  30. package/dist/core/types.js +2 -0
  31. package/dist/core/types.js.map +1 -1
  32. package/dist/core/unified-session.d.ts +34 -5
  33. package/dist/core/unified-session.d.ts.map +1 -1
  34. package/dist/core/unified-session.js +172 -30
  35. package/dist/core/unified-session.js.map +1 -1
  36. package/dist/extension/bridge.d.ts +24 -2
  37. package/dist/extension/bridge.d.ts.map +1 -1
  38. package/dist/extension/bridge.js +32 -1
  39. package/dist/extension/bridge.js.map +1 -1
  40. package/dist/extension/http-server.d.ts +17 -0
  41. package/dist/extension/http-server.d.ts.map +1 -1
  42. package/dist/extension/http-server.js +69 -9
  43. package/dist/extension/http-server.js.map +1 -1
  44. package/dist/extension/index.d.ts +1 -0
  45. package/dist/extension/index.d.ts.map +1 -1
  46. package/dist/extension/index.js.map +1 -1
  47. package/dist/tools/browse.d.ts +1 -1
  48. package/dist/tools/browse.d.ts.map +1 -1
  49. package/dist/tools/browse.js +73 -26
  50. package/dist/tools/browse.js.map +1 -1
  51. package/dist/tools/challenge.d.ts +153 -0
  52. package/dist/tools/challenge.d.ts.map +1 -0
  53. package/dist/tools/challenge.js +573 -0
  54. package/dist/tools/challenge.js.map +1 -0
  55. package/dist/tools/cookies.d.ts.map +1 -1
  56. package/dist/tools/cookies.js +8 -4
  57. package/dist/tools/cookies.js.map +1 -1
  58. package/dist/tools/diagnostics.d.ts +2 -2
  59. package/dist/tools/diagnostics.d.ts.map +1 -1
  60. package/dist/tools/diagnostics.js +28 -9
  61. package/dist/tools/diagnostics.js.map +1 -1
  62. package/dist/tools/evaluate.d.ts +8 -0
  63. package/dist/tools/evaluate.d.ts.map +1 -1
  64. package/dist/tools/evaluate.js +92 -14
  65. package/dist/tools/evaluate.js.map +1 -1
  66. package/dist/tools/extract.d.ts.map +1 -1
  67. package/dist/tools/extract.js +119 -59
  68. package/dist/tools/extract.js.map +1 -1
  69. package/dist/tools/input.d.ts +4 -0
  70. package/dist/tools/input.d.ts.map +1 -1
  71. package/dist/tools/input.js +248 -94
  72. package/dist/tools/input.js.map +1 -1
  73. package/dist/tools/logs.d.ts +7 -4
  74. package/dist/tools/logs.d.ts.map +1 -1
  75. package/dist/tools/logs.js +11 -8
  76. package/dist/tools/logs.js.map +1 -1
  77. package/dist/tools/manage.d.ts.map +1 -1
  78. package/dist/tools/manage.js +20 -7
  79. package/dist/tools/manage.js.map +1 -1
  80. package/dist/tools/network-sanitizer.d.ts +15 -0
  81. package/dist/tools/network-sanitizer.d.ts.map +1 -0
  82. package/dist/tools/network-sanitizer.js +62 -0
  83. package/dist/tools/network-sanitizer.js.map +1 -0
  84. package/dist/tools/png.js +5 -3
  85. package/dist/tools/png.js.map +1 -1
  86. package/dist/tools/post-condition.d.ts.map +1 -1
  87. package/dist/tools/post-condition.js +17 -4
  88. package/dist/tools/post-condition.js.map +1 -1
  89. package/dist/tools/target-diagnostics.d.ts +7 -0
  90. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  91. package/dist/tools/target-diagnostics.js +25 -2
  92. package/dist/tools/target-diagnostics.js.map +1 -1
  93. package/dist/tools/wait.d.ts.map +1 -1
  94. package/dist/tools/wait.js +42 -40
  95. package/dist/tools/wait.js.map +1 -1
  96. package/extension/dist/assets/content.ts-Cj_iiU2s.js +25 -0
  97. package/extension/dist/assets/{index.ts-BMmrcSQ6.js → index.ts-Bqcu2qiN.js} +620 -290
  98. package/extension/dist/manifest.json +3 -3
  99. package/extension/dist/service-worker-loader.js +1 -1
  100. package/extension/dist/src/popup/popup.html +44 -44
  101. package/package.json +8 -7
  102. package/dist/extension/native-host-installer.d.ts +0 -21
  103. package/dist/extension/native-host-installer.d.ts.map +0 -1
  104. package/dist/extension/native-host-installer.js +0 -147
  105. package/dist/extension/native-host-installer.js.map +0 -1
  106. package/dist/extension/socket-server.d.ts +0 -32
  107. package/dist/extension/socket-server.d.ts.map +0 -1
  108. package/dist/extension/socket-server.js +0 -177
  109. package/dist/extension/socket-server.js.map +0 -1
  110. package/dist/extension/ws-server.d.ts +0 -40
  111. package/dist/extension/ws-server.d.ts.map +0 -1
  112. package/dist/extension/ws-server.js +0 -246
  113. package/dist/extension/ws-server.js.map +0 -1
  114. package/dist/native-host/index.js +0 -280
  115. package/dist/native-host/mcp-chrome-host +0 -2
  116. package/extension/dist/assets/content.ts-pEASbjEL.js +0 -6
package/README.md CHANGED
@@ -15,7 +15,7 @@ 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-Tab Parallel**: `tabId` parameter enables operations on any tab without switching focus
17
17
  - **iframe Penetration**: `frame` parameter targets elements inside iframes (CSS selector or index, Extension mode)
18
- - **Semantic Targeting**: 11 ways to locate elements (role, text, label, css, css+text combo, xpath, coordinates, etc.)
18
+ - **Semantic Targeting**: 11 ways to locate elements (role, text, label, CSS, CSS+text combo, XPath, coordinates, etc.)
19
19
  - **Auto-Wait**: Built-in clickability and input-ready detection with deadline-based timeout budget
20
20
  - **Dual Input Mode**: `precise` (debugger API, bypasses CSP) or `stealth` (JS injection, no debug banner)
21
21
  - **Smart Output**: Bare `return` auto-wrapped in IIFE; large results (>100KB) auto-saved to file; `output` writes raw
@@ -27,12 +27,12 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
27
27
  ## Compatible Clients
28
28
 
29
29
  | Client | Status |
30
- |---------------------------|--------|
31
- | Claude Code | ✅ |
32
- | Claude Desktop | ✅ |
33
- | Cursor | ✅ |
34
- | Windsurf | ✅ |
35
- | Any MCP-compatible client | ✅ |
30
+ | ------------------------- | ------ |
31
+ | Claude Code | ✅ |
32
+ | Claude Desktop | ✅ |
33
+ | Cursor | ✅ |
34
+ | Windsurf | ✅ |
35
+ | Any MCP-compatible client | ✅ |
36
36
 
37
37
  ## Installation
38
38
 
@@ -46,7 +46,8 @@ claude mcp add chrome -- mcp-chrome
46
46
  npm root -g
47
47
  ```
48
48
 
49
- For Extension mode, open `chrome://extensions/`, enable Developer mode, click "Load unpacked", and select `<npm-root>/@pyrokine/mcp-chrome/extension/dist`.
49
+ For Extension mode, open `chrome://extensions/`, enable Developer mode, click "Load unpacked", and select
50
+ `<npm-root>/@pyrokine/mcp-chrome/extension/dist`.
50
51
 
51
52
  ### From source
52
53
 
@@ -89,21 +90,23 @@ Claude Desktop / Other Clients:
89
90
 
90
91
  ```json
91
92
  {
92
- "mcpServers": {
93
- "chrome": {
94
- "command": "node",
95
- "args": [
96
- "/path/to/mcp-chrome/dist/index.js"
97
- ]
93
+ "mcpServers": {
94
+ "chrome": {
95
+ "command": "node",
96
+ "args": ["/path/to/mcp-chrome/dist/index.js"]
97
+ }
98
98
  }
99
- }
100
99
  }
101
100
  ```
102
101
 
103
102
  **Step 3: Connect**
104
103
 
105
104
  The Extension auto-connects to the MCP Server via HTTP/WebSocket (port 19222-19299). Click the toolbar icon to verify
106
- connection status.
105
+ connection status. `browse(action="connect")` and the local `/api/info` endpoint report the active Extension background
106
+ bundle hash and compare it with the bundle shipped beside the server. `bundleStatus="stale"` means Chrome is still
107
+ running an older unpacked Extension bundle; reload the Extension in `chrome://extensions/`. A legacy Extension that
108
+ lacks `network_challenge_state` falls back to tab-title and DOM challenge detection. Bundle identity never disables
109
+ zero-config auto-connect.
107
110
 
108
111
  ```
109
112
  browse(action="list") // List all tabs
@@ -114,15 +117,15 @@ extract(type="screenshot")
114
117
  **Pairing token**
115
118
 
116
119
  Extension mode keeps zero-config local auto-connect by default. On shared machines, CI runners, or containers where
117
- untrusted local processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the MCP server and enter the
118
- same token in the Extension popup:
120
+ untrusted local processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the MCP server and enter
121
+ the same token in the Extension popup:
119
122
 
120
123
  ```bash
121
124
  MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
122
125
  ```
123
126
 
124
- To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server and
125
- disable "Allow no-token local connection" in the Extension popup.
127
+ To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server
128
+ and disable "Allow no-token local connection" in the Extension popup.
126
129
 
127
130
  ### Mode 2: CDP Mode (Fallback)
128
131
 
@@ -139,81 +142,126 @@ browse(action="connect", port=9222)
139
142
  browse(action="open", url="https://example.com")
140
143
  ```
141
144
 
142
- > When the Extension is connected, all tools use Extension mode automatically. CDP mode activates only when the
143
- > Extension is unavailable.
145
+ > A connected Extension is the default for every tool. CDP is used only while the Extension is unavailable. A
146
+ > `browse(action="connect", port=9222)` call explicitly selects CDP for later tools; use `browse(action="connect")` to
147
+ > return to Extension mode. A CDP connection created only as fallback yields to Extension after the Extension
148
+ > reconnects.
144
149
 
145
150
  ## Available Tools (8 Tools)
146
151
 
147
152
  ### browse - Browser Management & Navigation
148
153
 
149
- | Action | Description |
150
- |-----------|---------------------------------------|
151
- | `launch` | Launch new Chrome instance (CDP mode) |
152
- | `connect` | Connect to running Chrome (CDP mode) |
153
- | `list` | List all pages/tabs |
154
- | `attach` | Attach to a specific page/tab |
155
- | `open` | Navigate to URL |
156
- | `back` | Go back in history |
157
- | `forward` | Go forward in history |
158
- | `refresh` | Reload page |
159
- | `close` | Close browser connection |
154
+ | Action | Description |
155
+ | --------- | --------------------------------------------------------------------------- |
156
+ | `launch` | Create a managed Extension tab, or launch CDP when Extension is unavailable |
157
+ | `connect` | Confirm Extension by default; `port` explicitly selects CDP |
158
+ | `list` | List all pages/tabs |
159
+ | `attach` | Attach to a specific page/tab |
160
+ | `open` | Navigate to URL |
161
+ | `back` | Go back in history |
162
+ | `forward` | Go forward in history |
163
+ | `refresh` | Reload page |
164
+ | `close` | Close the page specified by `targetId` |
160
165
 
161
166
  Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
162
167
  (whether tab is controlled by MCP Chrome), `isActive` (whether it's the current operation target), `windowId`, `index`,
163
168
  `pinned`, `incognito`, and `status` (`loading`/`complete`). The tree includes `windowCount`, `focusedWindowId`,
164
169
  `activeTargetId`, and each window's ordered `tabs` list, so callers can distinguish the active tab inside each window
165
- from the page currently visible in the focused window.
166
- `open` auto-creates tab group (cyan color). `open`, `back`, `forward`, and `refresh` accept `diagnostics=true` to return
167
- new console warnings/errors and failed network requests observed during the action, including the first `open` that
168
- creates a page automatically.
170
+ from the page currently visible in the focused window. `open` auto-creates tab group (cyan color). `open`, `back`,
171
+ `forward`, and `refresh` accept `diagnostics=true` to return new console warnings/errors and failed network requests
172
+ observed during the action, including the first `open` that creates a page automatically. `close` requires `targetId`
173
+ and closes only that page. It never closes the entire CDP connection.
174
+
175
+ ### Access challenges
176
+
177
+ After `open`, `back`, `forward`, `refresh`, `input`, and `evaluate`, MCP Chrome waits for a Cloudflare JS Challenge or
178
+ Turnstile checkbox. When Extension mode is active, navigation starts without debugger logging and reads the live tab
179
+ title passively for eight seconds. If the interstitial persists, MCP Chrome checks for a visible Turnstile control and
180
+ clicks it only when it finds one. Extension inspect uses an isolated world and detaches the debugger first. Same-page
181
+ fixture buttons use the existing page click. If a Cloudflare Turnstile iframe is present, inspect CSS coordinates are
182
+ converted to screen coordinates and the OS mouse moves along a path, hovers, then presses and releases: `xdotool` on
183
+ Linux uses the focused Chrome window origin plus window chrome insets only when that window title matches the test page,
184
+ rather than Chrome `screenX` or `outerHeight - innerHeight`; `cliclick` or System Events on macOS; and PowerShell
185
+ `mouse_event` on Windows. Widget clicks target the checkbox on the left of the compact Turnstile card, including when
186
+ the host wrapper is wider than the card, not the label. If a Cloudflare iframe is already in the DOM, the OS mouse is
187
+ used even when that iframe reports a zero-size rect, including the later host `Verify you are human` / `请验证您是真人`
188
+ button. The OS click runs only when the managed test tab is already the active tab in an already-focused window; mixed
189
+ windows are not focused. Debugger is detached and the viewport is read again before the OS click. Missing OS mouse tools
190
+ or an unfocused window return a visible error instead of a silent CDP click. A Turnstile widget is clicked only after
191
+ two inspections report the same click point. Distant OS-mouse paths start near the control instead of flying across the
192
+ screen. The same checkbox or compact widget is clicked at most once; if Cloudflare then shows a visible
193
+ `Verify you are human` or `请验证您是真人` button, that button is inspected as `verify` and clicked at most once in the
194
+ same wait. Use the default `diagnostics=false` for challenge-protected pages because diagnostics starts debugger console
195
+ and network collection.
196
+
197
+ Detection covers titles such as `Just a moment...` and `请稍候…`, challenge DOM or body-text markers, and
198
+ `Verify you are human` / `请验证您是真人` controls. CDP reads live titles with `Target.getTargetInfo`. A leftover
199
+ Cloudflare iframe on a recovered page is not pending. Cached titles do not decide the result. MCP Chrome does not call a
200
+ CAPTCHA solver, retry navigation, or export `cf_clearance` values. A CDP timeout does not prove that the site fails in a
201
+ user Chrome session; check the returned `mode` before diagnosing the site.
202
+
203
+ A resolved challenge returns `challengeResolved=true`, `challengeKind`, `waitedMs`, `clickedTurnstile`, and
204
+ `clearanceCookiePresent` (name presence only). If the visible page text says verification succeeded and Cloudflare is
205
+ waiting for the origin, the result also has `originResponsePending=true`; verification passed, but the destination page
206
+ is not loaded yet. Hidden template text such as a `display:none` success heading does not count, and a visible Turnstile
207
+ checkbox still counts as pending. Challenge results and errors include `mode`. Timeout returns `CHALLENGE_TIMEOUT` with
208
+ `retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is not reported as `js`).
209
+ Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP reputation checks
210
+ cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears the header flag;
211
+ clearing network logs does not.
169
212
 
170
213
  ### input - Keyboard & Mouse Input
171
214
 
172
215
  Event sequence model supporting arbitrary combinations:
173
216
 
174
- | Event Type | Description |
175
- |-----------------------------------------|-----------------------------------------------------------------------------------|
176
- | `keydown` / `keyup` | Key press/release |
177
- | `click` | Click with actionability checks (visible, enabled, not-covered, auto-scroll) |
178
- | `mousedown` / `mouseup` | Mouse button press/release |
179
- | `mousemove` | Mouse movement |
180
- | `wheel` | Mouse wheel scroll |
181
- | `touchstart` / `touchmove` / `touchend` | Touch events |
182
- | `type` | Type text (with optional `delay`, `dispatch` for React/Vue) |
183
- | `wait` | Pause between events |
184
- | `select` | Select text by content (mouse sim) |
185
- | `replace` | Find and replace text |
186
- | `drag` | HTML5 drag-and-drop (DragEvent in MAIN world, with `target` source + `to` target) |
187
- | `editorContext` | Read focused editor and selection context |
188
- | `editorInsert` | Insert text at the current editor selection |
189
- | `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList` |
217
+ | Event Type | Description |
218
+ | --------------------------------------- | ---------------------------------------------------------------------- |
219
+ | `keydown` / `keyup` | Key press/release |
220
+ | `click` | Click after visibility, enabled, coverage, and scroll checks |
221
+ | `mousedown` / `mouseup` | Mouse button press/release |
222
+ | `mousemove` | Mouse movement |
223
+ | `wheel` | Mouse wheel scroll |
224
+ | `touchstart` / `touchmove` / `touchend` | Touch events |
225
+ | `type` | Type text (with optional `delay`, `dispatch` for React/Vue) |
226
+ | `wait` | Pause between events |
227
+ | `select` | Select text by content (mouse sim) |
228
+ | `replace` | Find and replace text |
229
+ | `drag` | HTML5 drag-and-drop (`target` source and `to` destination) |
230
+ | `editorContext` | Read focused editor and selection context |
231
+ | `editorInsert` | Insert text at the current editor selection |
232
+ | `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList` |
190
233
 
191
234
  Special-case parameters:
192
235
 
193
236
  - `keydown` accepts `commands` (e.g. `["selectAll"]`, `["copy"]`, `["paste"]`, `["cut"]`, `["undo"]`, `["redo"]`) to
194
- trigger native browser editing commands. `commands` is precise-mode only — stealth mode will throw because the
195
- CDP commands API has no JS-event equivalent.
237
+ trigger native browser editing commands. A successful response means the browser accepted the command dispatch; use
238
+ `postCondition` or `extract` to verify the page result. `commands` is precise-mode only; stealth mode throws because
239
+ the CDP commands API has no JS-event equivalent.
196
240
  - `keydown` on a key already held emits `rawKeyDown` with `autoRepeat: true` (Puppeteer-compatible long-press).
197
241
 
198
- Parameters: `humanize` enables Bézier curve movement and random delays. `diagnostics=true` returns new console
199
- warnings/errors and failed network requests after the action. `postCondition` waits for a page state after the events so
200
- callers can distinguish dispatched input from completed page behavior. `postCondition.timeout` defaults to 3000 ms and
201
- is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and accepts 50-5000 ms. `tabId` targets a specific
202
- tab. `frame` targets an iframe (CSS selector or index). Both Extension mode only.
242
+ `events` must contain at least one event. Parameters: `humanize` enables Bézier curve movement and random delays.
243
+ `diagnostics=true` returns new console warnings/errors and failed network requests after the action. `postCondition`
244
+ waits for a page state after the events so callers can distinguish dispatched input from completed page behavior.
245
+ `postCondition.timeout` defaults to 3000 ms and is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and
246
+ accepts 50-5000 ms. `tabId` targets a specific tab. `frame` targets an iframe (CSS selector or index). Both are
247
+ Extension-mode only. When either scope is provided, the action, diagnostics, and post-condition use the backend selected
248
+ for that target scope.
203
249
 
204
250
  **`click`-specific**: `force: true` skips actionability checks (useful for testing or hidden elements). Actionability
205
251
  failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering element details, candidate blockers, and
206
- suggestions.
207
- **`type`-specific**: `mode="controlled"` or `dispatch: true` sets `.value` directly and fires `input`/`change` events —
208
- use for React/Vue controlled inputs where keyboard events don't update state. Requires a non-coordinate `target`.
209
- Extension mode only. Controlled input and target lookup failures return structured context with `target`, `matchCount`,
210
- `nth`, `activeElement`, `selection`, and candidate controls. For `select` and `replace`, event-level `nth` selects the Nth
211
- text occurrence while nested `target.nth` selects the Nth matching element; both are zero-based and may be used together.
252
+ suggestions. **`type`-specific**: `mode="controlled"` or `dispatch: true` sets `.value` directly and fires `input`/
253
+ `change` events — use for React/Vue controlled inputs where keyboard events don't update state. Requires a
254
+ non-coordinate `target`. Extension mode only. Controlled input and target lookup failures return structured context with
255
+ `target`, `matchCount`, `nth`, `activeElement`, `selection`, and candidate controls. Password input values are omitted
256
+ from failure diagnostics, and input `find` or replacement `text` values are redacted from failed responses. For `select`
257
+ and `replace`, event-level `nth` selects the Nth text occurrence while nested `target.nth` selects the Nth matching
258
+ element; both are zero-based and may be used together. Locator targets for `select` and `replace` work in CDP mode
259
+ without Extension ref IDs.
212
260
 
213
261
  ### extract - Content Extraction
214
262
 
215
263
  | Type | Description |
216
- |--------------|---------------------------------------------------|
264
+ | ------------ | ------------------------------------------------- |
217
265
  | `text` | Extract text content |
218
266
  | `html` | Extract HTML source |
219
267
  | `frameHtml` | Extract HTML from the selected iframe |
@@ -225,10 +273,12 @@ text occurrence while nested `target.nth` selects the Nth matching element; both
225
273
  Parameters: `output` saves result to file (or directory for `images=data`). `images` (`info`/`data`) extracts image
226
274
  metadata or data alongside HTML. `frameHtml` extracts the current iframe document after `frame` routing. Screenshot
227
275
  accepts `clip` for coordinate-region capture, `compareWith` for PNG baseline comparison, and `diffOutput` for a PNG diff
228
- image. Screenshot responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`,
229
- `scale`, `clip`, and `capabilities`. PNG comparison is capped before decode at 25 MiB per PNG and 12,000,000 pixels; use
230
- `clip` or `scale` for larger captures. Hidden Extension tabs return `HIDDEN_TAB_SCREENSHOT` instead of auto-focusing the
231
- browser. If another debugger blocks the precise screenshot path, viewport fallback reports `degraded`, `fallback`, and
276
+ image. `diffOutput` requires `compareWith`. A `target` screenshot that has no match, whose `nth` is out of range, or
277
+ whose box has zero size returns a target error rather than silently returning a viewport screenshot. Screenshot
278
+ responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`, `scale`, `clip`, and
279
+ `capabilities`. PNG comparison is capped before decode at 25 MiB per PNG and 12,000,000 pixels; use `clip` or `scale`
280
+ for larger captures. Hidden Extension tabs return `HIDDEN_TAB_SCREENSHOT` instead of automatically focusing the browser.
281
+ If another debugger blocks the precise screenshot path, viewport fallback reports `degraded`, `fallback`, and
232
282
  `limitations`; unsupported fallback options return structured `SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns
233
283
  `interactiveElements`; `metadata` returns `frames` in both Extension and CDP modes. `tabId` targets a specific tab.
234
284
  `frame` targets an iframe. Both Extension mode only.
@@ -244,34 +294,35 @@ browser. If another debugger blocks the precise screenshot path, viewport fallba
244
294
  ### wait - Wait for Conditions
245
295
 
246
296
  | For | Description |
247
- |--------------|-----------------------------------------------------|
297
+ | ------------ | --------------------------------------------------- |
248
298
  | `element` | Wait for element (visible/hidden/attached/detached) |
249
299
  | `navigation` | Wait for navigation complete |
250
300
  | `time` | Fixed delay |
251
- | `idle` | Wait for page load + DOM mutation quiet period |
301
+ | `idle` | Wait for DOM or network quiet period |
252
302
 
253
303
  Parameters: `tabId` targets a specific tab. `frame` targets an iframe. Both Extension mode only.
254
304
 
255
- **`idle`-specific**: After `readyState === 'complete'`, injects a `MutationObserver` and waits for a quiet period with
256
- no DOM changes. The `ms` parameter controls the quiet period duration (default 500ms). Returns `domStable: true` when
257
- the DOM settled, `domStable: false` if still mutating when the budget ran out.
305
+ **`idle`-specific**: In Extension mode, after `readyState === 'complete'`, it injects a `MutationObserver` and waits for
306
+ a quiet period with no DOM changes. In CDP mode, it waits for network quiet instead. `ms` controls the relevant quiet
307
+ period (default 500ms). The response returns `idleKind` and `idlePeriodMs`; Extension responses also return `domStable`.
258
308
 
259
309
  ### evaluate - JavaScript Execution
260
310
 
261
311
  Execute JavaScript in page context.
262
312
 
263
- | Parameter | Description |
264
- |-----------------|-----------------------------------------------------------------------------------------------------------------------------------|
265
- | `script` | JavaScript code. Bare `return` statements auto-wrapped in IIFE |
266
- | `scriptFile` | Read script from a local file (alternative to `script`, relative paths default to controlled temp dir, use `cwd:` for repo files) |
267
- | `args` | Arguments passed to script (script must be a function expression) |
268
- | `mode` | `precise` (default, debugger API) or `stealth` (JS injection) |
269
- | `output` | Save result to file (relative paths default to controlled temp dir, use `cwd:` to persist in repo) |
270
- | `tabId` | Target a specific tab (Extension mode) |
271
- | `frame` | Target an iframe by CSS selector or index (Extension mode) |
272
- | `timeout` | End-to-end budget (ms) |
273
- | `diagnostics` | Return new console warnings/errors and failed network requests after execution |
274
- | `postCondition` | Wait for text, selector, URL fragment, or script result after execution |
313
+ | Parameter | Description |
314
+ | ------------------- | ----------------------------------------------------------------------- |
315
+ | `script` | JavaScript code. Bare `return` statements are wrapped in IIFE |
316
+ | `scriptFile` | Read code from a local file instead of `script` |
317
+ | `args` | Arguments passed to a script written as a function expression |
318
+ | `mode` | `precise` (default, debugger API) or `stealth` (JS injection) |
319
+ | `staleContextRetry` | iframe stale-context policy: `never` (default) or `readOnly` |
320
+ | `output` | Save the result to a file |
321
+ | `tabId` | Target a specific tab (Extension mode) |
322
+ | `frame` | Target an iframe by CSS selector or index (Extension mode) |
323
+ | `timeout` | End-to-end budget (ms) |
324
+ | `diagnostics` | Return new console warnings/errors and failed requests after execution |
325
+ | `postCondition` | Wait for text, selector, URL fragment, or script result after execution |
275
326
 
276
327
  `script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
277
328
  paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
@@ -280,15 +331,21 @@ streams.
280
331
 
281
332
  Results >100KB are auto-saved to the controlled OS temp directory with a structured hint returned. DOM nodes,
282
333
  `NodeList`, and `HTMLCollection` results return `NON_SERIALIZABLE_EVALUATE_RESULT` with a hint to return simple fields
283
- such as `textContent` or `outerHTML`. Evaluate defaults to `precise` even when global `inputMode` is `stealth`, and its
284
- `postCondition` checks use the same evaluate mode as the action. `postCondition` is optional; when it is not provided,
285
- `success=true` only means the script executed and returned. When it is provided and does not match before timeout, the
286
- tool returns `POST_CONDITION_FAILED` with the last observed checks.
334
+ such as `textContent` or `outerHTML`. Result materialization and serialization failures report `actionExecuted=true`,
335
+ `actionStatus="completed"`, and `failureStage="output"` because the page script has already finished. Evaluate defaults
336
+ to `precise` even when global `inputMode` is `stealth`, and its `postCondition` checks use the same evaluate mode as the
337
+ action. `postCondition` is optional; when it is not provided, `success=true` only means the script executed and
338
+ returned. When it is provided and does not match before timeout, the tool returns `POST_CONDITION_FAILED` with the last
339
+ observed checks. Precise iframe evaluation does not replay a script after a stale execution context by default. Set
340
+ `staleContextRetry="readOnly"` only when the script has no side effects; the Extension may then resolve a new context
341
+ and replay it once within the remaining timeout budget. A stale-context error after `Runtime.evaluate` reports
342
+ `actionExecuted=true` and `actionStatus="unknown"`, because earlier side effects may already have happened even though
343
+ the final result is unavailable.
287
344
 
288
345
  ### manage - Page & Environment Management
289
346
 
290
347
  | Action | Description |
291
- |----------------|------------------------------------------------------------|
348
+ | -------------- | ---------------------------------------------------------- |
292
349
  | `newPage` | Create new controlled page/tab |
293
350
  | `closePage` | Close controlled page and return `affected.before/after` |
294
351
  | `adoptPage` | Mark an existing tab as controlled without focusing it |
@@ -311,9 +368,11 @@ tool returns `POST_CONDITION_FAILED` with the last observed checks.
311
368
  | `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
312
369
 
313
370
  Tab/window management actions are Extension-mode only. Actions that change visible browser state require explicit
314
- `targetId` or `windowId` and return `affected.before/after`. `focusWindow` only returns success after the target window
315
- is observed as focused; otherwise it returns `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with
316
- unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`.
371
+ `targetId` or `windowId` and return `affected.before/after`. `clearCache` is unavailable in Extension mode and returns
372
+ `UNSUPPORTED_MODE` without clearing anything. Use scoped `cookies(action="clear")` for cookies or CDP mode for storage
373
+ and cache. `focusWindow` only returns success after the target window is observed as focused; otherwise it returns
374
+ `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with unmanaged tabs and returns
375
+ `WINDOW_HAS_UNMANAGED_TABS`.
317
376
 
318
377
  **Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
319
378
 
@@ -324,28 +383,31 @@ unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`.
324
383
  ### logs - Browser Logs
325
384
 
326
385
  | Type | Description |
327
- |-----------|----------------------------------------|
386
+ | --------- | -------------------------------------- |
328
387
  | `console` | Console logs (with level filter) |
329
388
  | `network` | Network request logs (with URL filter) |
330
389
 
331
- Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and `debug`;
332
- raw browser levels such as `warn` and `log` are normalized before filtering and return. Network logs include completed
333
- requests, HTTP 4xx/5xx responses, and failed loads with `errorText`, `method`, `url`, `status`, `timestamp`, and `duration`
334
- when available. Inline network results limit each URL to 2048 characters and add `urlLength` plus `urlTruncated: true`
335
- when shortened; explicit `output` keeps the complete URL. `urlPattern` supports `*` for any number of characters and `?`
336
- for one character. `tabId` targets a specific tab (Extension mode). `frame` is not applicable for logs.
390
+ Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and
391
+ `debug`; raw browser levels such as `warn` and `log` are normalized before filtering and return. Network logs include
392
+ completed requests, HTTP 4xx/5xx responses, and failed loads with `errorText`, `method`, `url`, `status`, `timestamp`,
393
+ and `duration` when available. URL query parameters commonly used for credentials, signatures, passwords, and tokens are
394
+ replaced with `[REDACTED]` in inline responses, diagnostics, and explicit `output` files. Redacted entries include
395
+ `urlRedacted`, `urlOriginalLength`, and `redactedQueryParameters`. Inline network results limit each sanitized URL to
396
+ 2048 characters and add `urlLength` plus `urlTruncated: true` when shortened. `urlPattern` supports `*` for any number
397
+ of characters and `?` for one character. `tabId` targets a specific tab (Extension mode). `frame` is not applicable for
398
+ logs.
337
399
 
338
400
  ### cookies - Cookie Management
339
401
 
340
- | Action | Description |
341
- |----------|---------------------------------------------------------------|
342
- | `get` | Get cookies |
343
- | `set` | Set cookie |
344
- | `delete` | Delete cookie |
345
- | `clear` | Delete cookies by filter (`name`/`domain`/`url`, ≥1 required) |
402
+ | Action | Description |
403
+ | -------- | ---------------------------------------------------------------------- |
404
+ | `get` | Get cookies |
405
+ | `set` | Set cookie |
406
+ | `delete` | Delete cookie |
407
+ | `clear` | Delete cookies in a URL or domain scope, optionally narrowed by `name` |
346
408
 
347
- **Note**: `clear` requires at least one of `name`, `domain`, or `url` to filter — calling without any filter is rejected
348
- to avoid wiping the user's login cookies.
409
+ **Note**: `clear` requires `url` or `domain`. `name` can only further narrow that scope, so a same-named cookie on
410
+ another site cannot be removed accidentally.
349
411
 
350
412
  ## Target: Unified Element Locator
351
413
 
@@ -353,57 +415,43 @@ All tools use a unified `Target` type for element location:
353
415
 
354
416
  ```typescript
355
417
  // By accessibility (recommended - most stable)
356
- { role: "button", name: "Submit" }
418
+ const byRole = { role: 'button', name: 'Submit' }
357
419
 
358
420
  // By accessibility with exact accessible name
359
- { role: "button", name: "Submit", exact: true }
421
+ const byExactRole = { role: 'button', name: 'Submit', exact: true }
360
422
 
361
423
  // By text content
362
- { text: "Click here", exact: true }
424
+ const byText = { text: 'Click here', exact: true }
363
425
 
364
426
  // By form label
365
- {
366
- label: "Email"
367
- }
427
+ const byLabel = { label: 'Email' }
368
428
 
369
429
  // By placeholder
370
- {
371
- placeholder: "Enter your name"
372
- }
430
+ const byPlaceholder = { placeholder: 'Enter your name' }
373
431
 
374
432
  // By title attribute
375
- {
376
- title: "Close dialog"
377
- }
433
+ const byTitle = { title: 'Close dialog' }
378
434
 
379
435
  // By alt text (images)
380
- {
381
- alt: "Profile picture"
382
- }
436
+ const byAlt = { alt: 'Profile picture' }
383
437
 
384
438
  // By test ID
385
- {
386
- testId: "submit-button"
387
- }
439
+ const byTestId = { testId: 'submit-button' }
388
440
 
389
441
  // By CSS selector
390
- {
391
- css: "#login-form .submit-btn"
392
- }
442
+ const byCss = { css: '#login-form .submit-btn' }
393
443
 
394
444
  // Disambiguate multiple matches (0-based)
395
- { css: ".ant-select-input", nth: 1 }
445
+ const secondMatch = { css: '.ant-select-input', nth: 1 }
396
446
 
397
447
  // By CSS + text (filter by text content)
398
- { css: "button", text: "Submit", exact: true }
448
+ const byCssText = { css: 'button', text: 'Submit', exact: true }
399
449
 
400
450
  // By XPath
401
- {
402
- xpath: "//button[@type='submit']"
403
- }
451
+ const byXPath = { xpath: "//button[@type='submit']" }
404
452
 
405
453
  // By coordinates
406
- { x: 100, y: 200 }
454
+ const byCoordinates = { x: 100, y: 200 }
407
455
  ```
408
456
 
409
457
  ## Usage Examples
@@ -497,6 +545,10 @@ input(events=[
497
545
  ], frame="iframe.login-frame")
498
546
  ```
499
547
 
548
+ Selectors and numeric indices follow the parent document's DOM iframe order. Subframes absent from that DOM, including
549
+ frames added by other extensions, cannot shift the index or become fallback targets. If the selected element cannot be
550
+ tied to exactly one Chrome frame, the operation returns `FRAME_IDENTITY_UNAVAILABLE` instead of choosing another frame.
551
+
500
552
  ### Wait for Element
501
553
 
502
554
  ```
@@ -585,8 +637,8 @@ mcp-chrome/
585
637
 
586
638
  ## Security Notes
587
639
 
588
- - **Trust boundary**: Extension mode auto-connects to local MCP servers by default. Use `MCP_CHROME_PAIRING_TOKEN`, or set
589
- `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`, on multi-user systems, CI runners, or containers with `--net=host` where
640
+ - **Trust boundary**: Extension mode auto-connects to local MCP servers by default. Use `MCP_CHROME_PAIRING_TOKEN`, or
641
+ set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`, on multi-user systems, CI runners, or containers with `--net=host` where
590
642
  untrusted code can reach `127.0.0.1:19222-19299`. WebSocket upgrades require a `chrome-extension://` Origin header,
591
643
  which blocks browser pages and curl, but does not stop a malicious local process running as the same user.
592
644
  - Extension mode: shares your browser sessions — only use on trusted machines
@@ -594,7 +646,8 @@ mcp-chrome/
594
646
  - Default ports bind to 127.0.0.1 only (localhost)
595
647
  - The `evaluate` tool can execute arbitrary JavaScript
596
648
  - The `manage cdp` action can send arbitrary CDP commands
597
- - Network logs may contain sensitive information
649
+ - Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still
650
+ contain sensitive information
598
651
 
599
652
  ### Anti-detection (stealth) — what it actually does
600
653
 
@@ -602,10 +655,11 @@ The `stealth` mode (`safe` / `aggressive`) only patches a small set of fingerpri
602
655
 
603
656
  - **Covers**: `navigator.webdriver`, `cdc_*` properties, User-Agent string, a few WebGL vendor/renderer values, Chrome
604
657
  runtime properties
605
- - **Does NOT cover**: Canvas fingerprinting, AudioContext fingerprinting, Font enumeration, TLS-level fingerprints (
606
- JA3/JA4), CDP attach banner ("Chrome is being controlled by automated software"), Extension presence detection
607
- - **Warning**: Do NOT rely on this to bypass commercial anti-bot services (Cloudflare Turnstile, Akamai, DataDome,
608
- PerimeterX). Real bot detection happens at multiple layers we cannot patch from inside the page
658
+ - **Does NOT cover**: Canvas fingerprinting, AudioContext fingerprinting, Font enumeration, TLS-level fingerprints
659
+ (JA3/JA4), CDP attach banner ("Chrome is being controlled by automated software"), Extension presence detection
660
+ - **Warning**: These patches do not pass Cloudflare. JS Challenge and Turnstile checkbox handling is a separate wait in
661
+ the real browser after navigation, input, or evaluate. It does not cover Akamai, DataDome, PerimeterX, interactive
662
+ CAPTCHAs, or IP reputation
609
663
 
610
664
  ## Known Limitations
611
665
 
@@ -623,9 +677,26 @@ MIT License - see [LICENSE](LICENSE) for details.
623
677
  - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
624
678
  - [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP documentation
625
679
 
626
-
627
680
  ## Operation status and diagnostics
628
681
 
629
- Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and `retryable`. Verification uses `matched`, `not_matched`, `unavailable`, or `error`; debugger timeouts report the action as `unknown` when completion cannot be proven. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action result. Browse and wait errors also retain any diagnostics collected before the action failed.
630
-
631
- `replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other input types use a native full-value update and return the requested and actual browser-normalized values. A standalone `select` on unsupported types returns `UNSUPPORTED_SELECTION`. Target timeouts include bounded locator, tab, frame, match, and candidate context. Precise iframe evaluation retries one stale execution context once and refuses ambiguous same-URL frames. Its response includes `retryAttempted`, bounded `retryReason`, and the final `frameContext` with the Extension frame, parent frame, URL, CDP frame, and execution context IDs. Port scanning aggregates ordinary pre-open failures at debug level; authentication and protocol rejections from identified MCP servers produce one bounded warning when the rejection summary changes.
682
+ Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and
683
+ `retryable`. Verification uses `matched`, `not_matched`, `unavailable`, or `error`; debugger timeouts report the action
684
+ as `unknown` when completion cannot be proven. Page-thrown exceptions report `actionExecuted=true` with
685
+ `actionStatus="failed"`; result materialization or serialization errors report `actionStatus="completed"` and
686
+ `failureStage="output"`. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action
687
+ result. Browse and wait errors also retain any diagnostics collected before the action failed. Target diagnostics query
688
+ the current tab state instead of relying on cached attach metadata.
689
+
690
+ `replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other
691
+ input types use a native full-value update and return the requested and actual browser-normalized values. A standalone
692
+ `select` on unsupported types returns `UNSUPPORTED_SELECTION`. CDP locator targets for `select` and `replace` are
693
+ focused through the CDP locator instead of Extension-only ref IDs. Password values are omitted from input failure
694
+ context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text`
695
+ values. Target timeouts include bounded locator, tab, frame, match, and candidate context. Explicit `tabId` and `frame`
696
+ scopes resolve the active backend before input, wait, logs, or extract work begins, so actions and verification use the
697
+ same target backend. Precise iframe evaluation defaults to `staleContextRetry="never"` and does not replay stale
698
+ scripts. `readOnly` permits one replay after the Extension verifies the frame identity and resolves a new execution
699
+ context. Responses include the policy, `retryAttempted`, bounded `retryReason`, and the final `frameContext` with the
700
+ Extension frame, parent frame, URL, CDP frame, and execution context IDs. Ambiguous same-URL frames are rejected. Port
701
+ scanning aggregates ordinary pre-open failures at debug level; authentication and protocol rejections from identified
702
+ MCP servers produce one bounded warning when the rejection summary changes.