@pyrokine/mcp-chrome 2.4.1 → 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.
- package/README.md +213 -158
- package/README_zh.md +245 -187
- package/dist/anti-detection/behavior.js +1 -1
- package/dist/anti-detection/behavior.js.map +1 -1
- package/dist/anti-detection/injection.d.ts.map +1 -1
- package/dist/anti-detection/injection.js +2 -1
- package/dist/anti-detection/injection.js.map +1 -1
- package/dist/cdp/client.d.ts +2 -2
- package/dist/cdp/client.d.ts.map +1 -1
- package/dist/cdp/client.js +7 -4
- package/dist/cdp/client.js.map +1 -1
- package/dist/core/browser-driver.d.ts +3 -2
- package/dist/core/browser-driver.d.ts.map +1 -1
- package/dist/core/browser-driver.js +1 -0
- package/dist/core/browser-driver.js.map +1 -1
- package/dist/core/errors.d.ts +9 -0
- package/dist/core/errors.d.ts.map +1 -1
- package/dist/core/errors.js +16 -1
- package/dist/core/errors.js.map +1 -1
- package/dist/core/os-mouse.d.ts +65 -0
- package/dist/core/os-mouse.d.ts.map +1 -0
- package/dist/core/os-mouse.js +334 -0
- package/dist/core/os-mouse.js.map +1 -0
- package/dist/core/session.d.ts +14 -4
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +159 -54
- package/dist/core/session.js.map +1 -1
- package/dist/core/types.d.ts +10 -0
- package/dist/core/types.d.ts.map +1 -1
- package/dist/core/types.js +2 -0
- package/dist/core/types.js.map +1 -1
- package/dist/core/unified-session.d.ts +24 -3
- package/dist/core/unified-session.d.ts.map +1 -1
- package/dist/core/unified-session.js +143 -25
- package/dist/core/unified-session.js.map +1 -1
- package/dist/extension/bridge.d.ts +16 -0
- package/dist/extension/bridge.d.ts.map +1 -1
- package/dist/extension/bridge.js +27 -0
- package/dist/extension/bridge.js.map +1 -1
- package/dist/extension/http-server.d.ts.map +1 -1
- package/dist/extension/http-server.js +6 -1
- package/dist/extension/http-server.js.map +1 -1
- package/dist/tools/browse.d.ts +1 -1
- package/dist/tools/browse.d.ts.map +1 -1
- package/dist/tools/browse.js +72 -26
- package/dist/tools/browse.js.map +1 -1
- package/dist/tools/challenge.d.ts +153 -0
- package/dist/tools/challenge.d.ts.map +1 -0
- package/dist/tools/challenge.js +573 -0
- package/dist/tools/challenge.js.map +1 -0
- package/dist/tools/cookies.d.ts.map +1 -1
- package/dist/tools/cookies.js +8 -4
- package/dist/tools/cookies.js.map +1 -1
- package/dist/tools/diagnostics.d.ts +2 -2
- package/dist/tools/diagnostics.d.ts.map +1 -1
- package/dist/tools/diagnostics.js +26 -8
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/evaluate.d.ts.map +1 -1
- package/dist/tools/evaluate.js +61 -9
- package/dist/tools/evaluate.js.map +1 -1
- package/dist/tools/extract.d.ts.map +1 -1
- package/dist/tools/extract.js +110 -51
- package/dist/tools/extract.js.map +1 -1
- package/dist/tools/input.d.ts.map +1 -1
- package/dist/tools/input.js +148 -22
- package/dist/tools/input.js.map +1 -1
- package/dist/tools/logs.js +2 -2
- package/dist/tools/logs.js.map +1 -1
- package/dist/tools/manage.d.ts.map +1 -1
- package/dist/tools/manage.js +20 -7
- package/dist/tools/manage.js.map +1 -1
- package/dist/tools/network-sanitizer.d.ts.map +1 -1
- package/dist/tools/network-sanitizer.js +1 -0
- package/dist/tools/network-sanitizer.js.map +1 -1
- package/dist/tools/png.js +5 -3
- package/dist/tools/png.js.map +1 -1
- package/dist/tools/post-condition.d.ts.map +1 -1
- package/dist/tools/post-condition.js +12 -3
- package/dist/tools/post-condition.js.map +1 -1
- package/dist/tools/target-diagnostics.d.ts +7 -0
- package/dist/tools/target-diagnostics.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.js +18 -1
- package/dist/tools/target-diagnostics.js.map +1 -1
- package/dist/tools/wait.d.ts.map +1 -1
- package/dist/tools/wait.js +41 -39
- package/dist/tools/wait.js.map +1 -1
- package/extension/dist/assets/{index.ts-GG6dPUPX.js → index.ts-Bqcu2qiN.js} +286 -9
- package/extension/dist/manifest.json +1 -1
- package/extension/dist/service-worker-loader.js +1 -1
- package/extension/dist/src/popup/popup.html +44 -44
- package/package.json +8 -7
- package/dist/extension/native-host-installer.d.ts +0 -21
- package/dist/extension/native-host-installer.d.ts.map +0 -1
- package/dist/extension/native-host-installer.js +0 -147
- package/dist/extension/native-host-installer.js.map +0 -1
- package/dist/extension/socket-server.d.ts +0 -32
- package/dist/extension/socket-server.d.ts.map +0 -1
- package/dist/extension/socket-server.js +0 -177
- package/dist/extension/socket-server.js.map +0 -1
- package/dist/extension/ws-server.d.ts +0 -40
- package/dist/extension/ws-server.d.ts.map +0 -1
- package/dist/extension/ws-server.js +0 -246
- package/dist/extension/ws-server.js.map +0 -1
- package/dist/native-host/index.js +0 -280
- package/dist/native-host/mcp-chrome-host +0 -2
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,
|
|
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
|
|
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,14 +90,12 @@ Claude Desktop / Other Clients:
|
|
|
89
90
|
|
|
90
91
|
```json
|
|
91
92
|
{
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
|
|
@@ -104,9 +103,10 @@ Claude Desktop / Other Clients:
|
|
|
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
105
|
connection status. `browse(action="connect")` and the local `/api/info` endpoint report the active Extension background
|
|
107
|
-
bundle hash and compare it with the bundle shipped beside the server. `bundleStatus="stale"` means Chrome is still
|
|
108
|
-
an older unpacked Extension bundle; reload the Extension in `chrome://extensions/`.
|
|
109
|
-
|
|
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.
|
|
110
110
|
|
|
111
111
|
```
|
|
112
112
|
browse(action="list") // List all tabs
|
|
@@ -117,15 +117,15 @@ extract(type="screenshot")
|
|
|
117
117
|
**Pairing token**
|
|
118
118
|
|
|
119
119
|
Extension mode keeps zero-config local auto-connect by default. On shared machines, CI runners, or containers where
|
|
120
|
-
untrusted local processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the MCP server and enter
|
|
121
|
-
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:
|
|
122
122
|
|
|
123
123
|
```bash
|
|
124
124
|
MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
|
|
125
125
|
```
|
|
126
126
|
|
|
127
|
-
To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server
|
|
128
|
-
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.
|
|
129
129
|
|
|
130
130
|
### Mode 2: CDP Mode (Fallback)
|
|
131
131
|
|
|
@@ -142,54 +142,94 @@ browse(action="connect", port=9222)
|
|
|
142
142
|
browse(action="open", url="https://example.com")
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
-
>
|
|
146
|
-
>
|
|
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.
|
|
147
149
|
|
|
148
150
|
## Available Tools (8 Tools)
|
|
149
151
|
|
|
150
152
|
### browse - Browser Management & Navigation
|
|
151
153
|
|
|
152
|
-
| Action | Description
|
|
153
|
-
|
|
154
|
-
| `launch` |
|
|
155
|
-
| `connect` |
|
|
156
|
-
| `list` | List all pages/tabs
|
|
157
|
-
| `attach` | Attach to a specific page/tab
|
|
158
|
-
| `open` | Navigate to URL
|
|
159
|
-
| `back` | Go back in history
|
|
160
|
-
| `forward` | Go forward in history
|
|
161
|
-
| `refresh` | Reload page
|
|
162
|
-
| `close` | Close
|
|
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` |
|
|
163
165
|
|
|
164
166
|
Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
|
|
165
167
|
(whether tab is controlled by MCP Chrome), `isActive` (whether it's the current operation target), `windowId`, `index`,
|
|
166
168
|
`pinned`, `incognito`, and `status` (`loading`/`complete`). The tree includes `windowCount`, `focusedWindowId`,
|
|
167
169
|
`activeTargetId`, and each window's ordered `tabs` list, so callers can distinguish the active tab inside each window
|
|
168
|
-
from the page currently visible in the focused window.
|
|
169
|
-
`
|
|
170
|
-
|
|
171
|
-
|
|
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.
|
|
172
212
|
|
|
173
213
|
### input - Keyboard & Mouse Input
|
|
174
214
|
|
|
175
215
|
Event sequence model supporting arbitrary combinations:
|
|
176
216
|
|
|
177
|
-
| Event Type | Description
|
|
178
|
-
|
|
179
|
-
| `keydown` / `keyup` | Key press/release
|
|
180
|
-
| `click` | Click
|
|
181
|
-
| `mousedown` / `mouseup` | Mouse button press/release
|
|
182
|
-
| `mousemove` | Mouse movement
|
|
183
|
-
| `wheel` | Mouse wheel scroll
|
|
184
|
-
| `touchstart` / `touchmove` / `touchend` | Touch events
|
|
185
|
-
| `type` | Type text (with optional `delay`, `dispatch` for React/Vue)
|
|
186
|
-
| `wait` | Pause between events
|
|
187
|
-
| `select` | Select text by content (mouse sim)
|
|
188
|
-
| `replace` | Find and replace text
|
|
189
|
-
| `drag` | HTML5 drag-and-drop (
|
|
190
|
-
| `editorContext` | Read focused editor and selection context
|
|
191
|
-
| `editorInsert` | Insert text at the current editor selection
|
|
192
|
-
| `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList`
|
|
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` |
|
|
193
233
|
|
|
194
234
|
Special-case parameters:
|
|
195
235
|
|
|
@@ -199,28 +239,29 @@ Special-case parameters:
|
|
|
199
239
|
the CDP commands API has no JS-event equivalent.
|
|
200
240
|
- `keydown` on a key already held emits `rawKeyDown` with `autoRepeat: true` (Puppeteer-compatible long-press).
|
|
201
241
|
|
|
202
|
-
Parameters: `humanize` enables Bézier curve movement and random delays.
|
|
203
|
-
warnings/errors and failed network requests after the action. `postCondition`
|
|
204
|
-
callers can distinguish dispatched input from completed page behavior.
|
|
205
|
-
is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and
|
|
206
|
-
tab. `frame` targets an iframe (CSS selector or index). Both are
|
|
207
|
-
action, diagnostics, and post-condition use the backend selected
|
|
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.
|
|
208
249
|
|
|
209
250
|
**`click`-specific**: `force: true` skips actionability checks (useful for testing or hidden elements). Actionability
|
|
210
251
|
failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering element details, candidate blockers, and
|
|
211
|
-
suggestions.
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
and
|
|
217
|
-
|
|
218
|
-
|
|
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.
|
|
219
260
|
|
|
220
261
|
### extract - Content Extraction
|
|
221
262
|
|
|
222
263
|
| Type | Description |
|
|
223
|
-
|
|
264
|
+
| ------------ | ------------------------------------------------- |
|
|
224
265
|
| `text` | Extract text content |
|
|
225
266
|
| `html` | Extract HTML source |
|
|
226
267
|
| `frameHtml` | Extract HTML from the selected iframe |
|
|
@@ -232,10 +273,12 @@ may be used together. Locator targets for `select` and `replace` work in CDP mod
|
|
|
232
273
|
Parameters: `output` saves result to file (or directory for `images=data`). `images` (`info`/`data`) extracts image
|
|
233
274
|
metadata or data alongside HTML. `frameHtml` extracts the current iframe document after `frame` routing. Screenshot
|
|
234
275
|
accepts `clip` for coordinate-region capture, `compareWith` for PNG baseline comparison, and `diffOutput` for a PNG diff
|
|
235
|
-
image.
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
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
|
|
239
282
|
`limitations`; unsupported fallback options return structured `SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns
|
|
240
283
|
`interactiveElements`; `metadata` returns `frames` in both Extension and CDP modes. `tabId` targets a specific tab.
|
|
241
284
|
`frame` targets an iframe. Both Extension mode only.
|
|
@@ -251,35 +294,35 @@ browser. If another debugger blocks the precise screenshot path, viewport fallba
|
|
|
251
294
|
### wait - Wait for Conditions
|
|
252
295
|
|
|
253
296
|
| For | Description |
|
|
254
|
-
|
|
297
|
+
| ------------ | --------------------------------------------------- |
|
|
255
298
|
| `element` | Wait for element (visible/hidden/attached/detached) |
|
|
256
299
|
| `navigation` | Wait for navigation complete |
|
|
257
300
|
| `time` | Fixed delay |
|
|
258
|
-
| `idle` | Wait for
|
|
301
|
+
| `idle` | Wait for DOM or network quiet period |
|
|
259
302
|
|
|
260
303
|
Parameters: `tabId` targets a specific tab. `frame` targets an iframe. Both Extension mode only.
|
|
261
304
|
|
|
262
|
-
**`idle`-specific**:
|
|
263
|
-
no DOM changes.
|
|
264
|
-
|
|
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`.
|
|
265
308
|
|
|
266
309
|
### evaluate - JavaScript Execution
|
|
267
310
|
|
|
268
311
|
Execute JavaScript in page context.
|
|
269
312
|
|
|
270
|
-
| Parameter
|
|
271
|
-
|
|
272
|
-
| `script`
|
|
273
|
-
| `scriptFile`
|
|
274
|
-
| `args`
|
|
275
|
-
| `mode`
|
|
276
|
-
| `staleContextRetry` | iframe stale-context policy: `never` (default) or `readOnly`
|
|
277
|
-
| `output`
|
|
278
|
-
| `tabId`
|
|
279
|
-
| `frame`
|
|
280
|
-
| `timeout`
|
|
281
|
-
| `diagnostics`
|
|
282
|
-
| `postCondition`
|
|
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 |
|
|
283
326
|
|
|
284
327
|
`script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
|
|
285
328
|
paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
|
|
@@ -290,17 +333,19 @@ Results >100KB are auto-saved to the controlled OS temp directory with a structu
|
|
|
290
333
|
`NodeList`, and `HTMLCollection` results return `NON_SERIALIZABLE_EVALUATE_RESULT` with a hint to return simple fields
|
|
291
334
|
such as `textContent` or `outerHTML`. Result materialization and serialization failures report `actionExecuted=true`,
|
|
292
335
|
`actionStatus="completed"`, and `failureStage="output"` because the page script has already finished. Evaluate defaults
|
|
293
|
-
to `precise` even when global `inputMode` is `stealth`, and its
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
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.
|
|
299
344
|
|
|
300
345
|
### manage - Page & Environment Management
|
|
301
346
|
|
|
302
347
|
| Action | Description |
|
|
303
|
-
|
|
348
|
+
| -------------- | ---------------------------------------------------------- |
|
|
304
349
|
| `newPage` | Create new controlled page/tab |
|
|
305
350
|
| `closePage` | Close controlled page and return `affected.before/after` |
|
|
306
351
|
| `adoptPage` | Mark an existing tab as controlled without focusing it |
|
|
@@ -323,9 +368,11 @@ the Extension may then resolve a new context and replay it once within the remai
|
|
|
323
368
|
| `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
|
|
324
369
|
|
|
325
370
|
Tab/window management actions are Extension-mode only. Actions that change visible browser state require explicit
|
|
326
|
-
`targetId` or `windowId` and return `affected.before/after`. `
|
|
327
|
-
|
|
328
|
-
|
|
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`.
|
|
329
376
|
|
|
330
377
|
**Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
|
|
331
378
|
|
|
@@ -336,30 +383,31 @@ unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`.
|
|
|
336
383
|
### logs - Browser Logs
|
|
337
384
|
|
|
338
385
|
| Type | Description |
|
|
339
|
-
|
|
386
|
+
| --------- | -------------------------------------- |
|
|
340
387
|
| `console` | Console logs (with level filter) |
|
|
341
388
|
| `network` | Network request logs (with URL filter) |
|
|
342
389
|
|
|
343
|
-
Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and
|
|
344
|
-
raw browser levels such as `warn` and `log` are normalized before filtering and return. Network logs include
|
|
345
|
-
requests, HTTP 4xx/5xx responses, and failed loads with `errorText`, `method`, `url`, `status`, `timestamp`,
|
|
346
|
-
when available. URL query parameters commonly used for credentials, signatures, passwords, and tokens are
|
|
347
|
-
`[REDACTED]` in inline responses, diagnostics, and explicit `output` files. Redacted entries include
|
|
348
|
-
`urlOriginalLength`, and `redactedQueryParameters`. Inline network results limit each sanitized URL to
|
|
349
|
-
add `urlLength` plus `urlTruncated: true` when shortened. `urlPattern` supports `*` for any number
|
|
350
|
-
for one character. `tabId` targets a specific tab (Extension mode). `frame` is not applicable for
|
|
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.
|
|
351
399
|
|
|
352
400
|
### cookies - Cookie Management
|
|
353
401
|
|
|
354
|
-
| Action | Description
|
|
355
|
-
|
|
356
|
-
| `get` | Get cookies
|
|
357
|
-
| `set` | Set cookie
|
|
358
|
-
| `delete` | Delete cookie
|
|
359
|
-
| `clear` | Delete cookies
|
|
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` |
|
|
360
408
|
|
|
361
|
-
**Note**: `clear` requires
|
|
362
|
-
|
|
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.
|
|
363
411
|
|
|
364
412
|
## Target: Unified Element Locator
|
|
365
413
|
|
|
@@ -367,57 +415,43 @@ All tools use a unified `Target` type for element location:
|
|
|
367
415
|
|
|
368
416
|
```typescript
|
|
369
417
|
// By accessibility (recommended - most stable)
|
|
370
|
-
{ role:
|
|
418
|
+
const byRole = { role: 'button', name: 'Submit' }
|
|
371
419
|
|
|
372
420
|
// By accessibility with exact accessible name
|
|
373
|
-
{ role:
|
|
421
|
+
const byExactRole = { role: 'button', name: 'Submit', exact: true }
|
|
374
422
|
|
|
375
423
|
// By text content
|
|
376
|
-
{ text:
|
|
424
|
+
const byText = { text: 'Click here', exact: true }
|
|
377
425
|
|
|
378
426
|
// By form label
|
|
379
|
-
{
|
|
380
|
-
label: "Email"
|
|
381
|
-
}
|
|
427
|
+
const byLabel = { label: 'Email' }
|
|
382
428
|
|
|
383
429
|
// By placeholder
|
|
384
|
-
{
|
|
385
|
-
placeholder: "Enter your name"
|
|
386
|
-
}
|
|
430
|
+
const byPlaceholder = { placeholder: 'Enter your name' }
|
|
387
431
|
|
|
388
432
|
// By title attribute
|
|
389
|
-
{
|
|
390
|
-
title: "Close dialog"
|
|
391
|
-
}
|
|
433
|
+
const byTitle = { title: 'Close dialog' }
|
|
392
434
|
|
|
393
435
|
// By alt text (images)
|
|
394
|
-
{
|
|
395
|
-
alt: "Profile picture"
|
|
396
|
-
}
|
|
436
|
+
const byAlt = { alt: 'Profile picture' }
|
|
397
437
|
|
|
398
438
|
// By test ID
|
|
399
|
-
{
|
|
400
|
-
testId: "submit-button"
|
|
401
|
-
}
|
|
439
|
+
const byTestId = { testId: 'submit-button' }
|
|
402
440
|
|
|
403
441
|
// By CSS selector
|
|
404
|
-
{
|
|
405
|
-
css: "#login-form .submit-btn"
|
|
406
|
-
}
|
|
442
|
+
const byCss = { css: '#login-form .submit-btn' }
|
|
407
443
|
|
|
408
444
|
// Disambiguate multiple matches (0-based)
|
|
409
|
-
{ css:
|
|
445
|
+
const secondMatch = { css: '.ant-select-input', nth: 1 }
|
|
410
446
|
|
|
411
447
|
// By CSS + text (filter by text content)
|
|
412
|
-
{ css:
|
|
448
|
+
const byCssText = { css: 'button', text: 'Submit', exact: true }
|
|
413
449
|
|
|
414
450
|
// By XPath
|
|
415
|
-
{
|
|
416
|
-
xpath: "//button[@type='submit']"
|
|
417
|
-
}
|
|
451
|
+
const byXPath = { xpath: "//button[@type='submit']" }
|
|
418
452
|
|
|
419
453
|
// By coordinates
|
|
420
|
-
{ x: 100, y: 200 }
|
|
454
|
+
const byCoordinates = { x: 100, y: 200 }
|
|
421
455
|
```
|
|
422
456
|
|
|
423
457
|
## Usage Examples
|
|
@@ -511,7 +545,9 @@ input(events=[
|
|
|
511
545
|
], frame="iframe.login-frame")
|
|
512
546
|
```
|
|
513
547
|
|
|
514
|
-
Selectors and numeric indices follow the parent document's DOM iframe order. Subframes absent from that DOM, including
|
|
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.
|
|
515
551
|
|
|
516
552
|
### Wait for Element
|
|
517
553
|
|
|
@@ -601,8 +637,8 @@ mcp-chrome/
|
|
|
601
637
|
|
|
602
638
|
## Security Notes
|
|
603
639
|
|
|
604
|
-
- **Trust boundary**: Extension mode auto-connects to local MCP servers by default. Use `MCP_CHROME_PAIRING_TOKEN`, or
|
|
605
|
-
`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
|
|
606
642
|
untrusted code can reach `127.0.0.1:19222-19299`. WebSocket upgrades require a `chrome-extension://` Origin header,
|
|
607
643
|
which blocks browser pages and curl, but does not stop a malicious local process running as the same user.
|
|
608
644
|
- Extension mode: shares your browser sessions — only use on trusted machines
|
|
@@ -610,7 +646,8 @@ mcp-chrome/
|
|
|
610
646
|
- Default ports bind to 127.0.0.1 only (localhost)
|
|
611
647
|
- The `evaluate` tool can execute arbitrary JavaScript
|
|
612
648
|
- The `manage cdp` action can send arbitrary CDP commands
|
|
613
|
-
- Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still
|
|
649
|
+
- Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still
|
|
650
|
+
contain sensitive information
|
|
614
651
|
|
|
615
652
|
### Anti-detection (stealth) — what it actually does
|
|
616
653
|
|
|
@@ -618,10 +655,11 @@ The `stealth` mode (`safe` / `aggressive`) only patches a small set of fingerpri
|
|
|
618
655
|
|
|
619
656
|
- **Covers**: `navigator.webdriver`, `cdc_*` properties, User-Agent string, a few WebGL vendor/renderer values, Chrome
|
|
620
657
|
runtime properties
|
|
621
|
-
- **Does NOT cover**: Canvas fingerprinting, AudioContext fingerprinting, Font enumeration, TLS-level fingerprints
|
|
622
|
-
JA3/JA4), CDP attach banner ("Chrome is being controlled by automated software"), Extension presence detection
|
|
623
|
-
- **Warning**:
|
|
624
|
-
|
|
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
|
|
625
663
|
|
|
626
664
|
## Known Limitations
|
|
627
665
|
|
|
@@ -639,9 +677,26 @@ MIT License - see [LICENSE](LICENSE) for details.
|
|
|
639
677
|
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
|
|
640
678
|
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP documentation
|
|
641
679
|
|
|
642
|
-
|
|
643
680
|
## Operation status and diagnostics
|
|
644
681
|
|
|
645
|
-
Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and
|
|
646
|
-
|
|
647
|
-
|
|
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.
|