@pyrokine/mcp-chrome 2.1.0 → 2.3.0

package/README.md

@@ -95,6 +95,15 @@ browse(action="open", url="https://example.com")
 extract(type="screenshot")
 ```
 
+**Optional pairing token**
+
+By default, local Extension mode does not require a token. To restrict the Extension connection, start the MCP server
+with `MCP_CHROME_PAIRING_TOKEN`, then enter the same token in the Extension popup:
+
+```bash
+MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
+```
+
 ### Mode 2: CDP Mode (Fallback)
 
 CDP mode launches or connects to a dedicated Chrome instance. Used when the Extension is not installed, or for
@@ -167,8 +176,10 @@ Special-case parameters:
 - `keydown` on a key already held emits `rawKeyDown` with `autoRepeat: true` (Puppeteer-compatible long-press).
 
 Parameters: `humanize` enables Bézier curve movement and random delays. `diagnostics=true` returns new console
-warnings/errors and failed network requests after the action. `tabId` targets a specific tab. `frame` targets an
-iframe (CSS selector or index). Both Extension mode only.
+warnings/errors and failed network requests after the action. `postCondition` waits for a page state after the events so
+callers can distinguish dispatched input from completed page behavior. `postCondition.timeout` defaults to 3000 ms and
+is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and accepts 50-5000 ms. `tabId` targets a specific
+tab. `frame` targets an iframe (CSS selector or index). Both Extension mode only.
 
 **`click`-specific**: `force: true` skips actionability checks (useful for testing or hidden elements). Actionability
 failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering element details, candidate blockers, and
@@ -196,8 +207,10 @@ accepts `clip` for coordinate-region capture, `compareWith` for PNG baseline com
 image. Screenshot responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`,
 `scale`, `clip`, and `capabilities`. PNG comparison is capped before decode at 25 MiB per PNG and 12,000,000 pixels; use
 `clip` or `scale` for larger captures. Hidden Extension tabs return `HIDDEN_TAB_SCREENSHOT` instead of auto-focusing the
-browser. `state` returns `interactiveElements`; `metadata` returns `frames` in both Extension and CDP modes. `tabId`
-targets a specific tab. `frame` targets an iframe. Both Extension mode only.
+browser. If another debugger blocks the precise screenshot path, viewport fallback reports `degraded`, `fallback`, and
+`limitations`; unsupported fallback options return structured `SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns
+`interactiveElements`; `metadata` returns `frames` in both Extension and CDP modes. `tabId` targets a specific tab.
+`frame` targets an iframe. Both Extension mode only.
 
 **`attribute` special prefix**: `computed:<property>` returns the computed CSS style value (e.g. `computed:color`,
 `computed:font-size`). Use `computed:*` to return all computed style properties as JSON (returns 300+ properties — use
@@ -226,17 +239,18 @@ the DOM settled, `domStable: false` if still mutating when the budget ran out.
 
 Execute JavaScript in page context.
 
-| Parameter     | Description                                                                                                                       |
-|---------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| `script`      | JavaScript code. Bare `return` statements auto-wrapped in IIFE                                                                    |
-| `scriptFile`  | Read script from a local file (alternative to `script`, relative paths default to controlled temp dir, use `cwd:` for repo files) |
-| `args`        | Arguments passed to script (script must be a function expression)                                                                 |
-| `mode`        | `precise` (default, debugger API) or `stealth` (JS injection)                                                                     |
-| `output`      | Save result to file (relative paths default to controlled temp dir, use `cwd:` to persist in repo)                                |
-| `tabId`       | Target a specific tab (Extension mode)                                                                                            |
-| `frame`       | Target an iframe by CSS selector or index (Extension mode)                                                                        |
-| `timeout`     | End-to-end budget (ms)                                                                                                            |
-| `diagnostics` | Return new console warnings/errors and failed network requests after execution                                                    |
+| Parameter       | Description                                                                                                                       |
+|-----------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `script`        | JavaScript code. Bare `return` statements auto-wrapped in IIFE                                                                    |
+| `scriptFile`    | Read script from a local file (alternative to `script`, relative paths default to controlled temp dir, use `cwd:` for repo files) |
+| `args`          | Arguments passed to script (script must be a function expression)                                                                 |
+| `mode`          | `precise` (default, debugger API) or `stealth` (JS injection)                                                                     |
+| `output`        | Save result to file (relative paths default to controlled temp dir, use `cwd:` to persist in repo)                                |
+| `tabId`         | Target a specific tab (Extension mode)                                                                                            |
+| `frame`         | Target an iframe by CSS selector or index (Extension mode)                                                                        |
+| `timeout`       | End-to-end budget (ms)                                                                                                            |
+| `diagnostics`   | Return new console warnings/errors and failed network requests after execution                                                    |
+| `postCondition` | Wait for text, selector, URL fragment, or script result after execution                                                           |
 
 `script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
 paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
@@ -245,7 +259,9 @@ streams.
 
 Results >100KB are auto-saved to the controlled OS temp directory with a structured hint returned. DOM nodes,
 `NodeList`, and `HTMLCollection` results return `NON_SERIALIZABLE_EVALUATE_RESULT` with a hint to return simple fields
-such as `textContent` or `outerHTML`.
+such as `textContent` or `outerHTML`. `postCondition` is optional; when it is not provided, `success=true` only means
+the script executed and returned. When it is provided and does not match before timeout, the tool returns
+`POST_CONDITION_FAILED` with the last observed checks.
 
 ### manage - Page & Environment Management
 
@@ -273,8 +289,9 @@ such as `textContent` or `outerHTML`.
 | `cdp`          | Send raw CDP command (advanced, e.g. `Runtime.evaluate`)   |
 
 Tab/window management actions are Extension-mode only. Actions that change visible browser state require explicit
-`targetId` or `windowId` and return `affected.before/after`. `closeWindow` refuses mixed windows with unmanaged tabs and
-returns `WINDOW_HAS_UNMANAGED_TABS`.
+`targetId` or `windowId` and return `affected.before/after`. `focusWindow` only returns success after the target window
+is observed as focused; otherwise it returns `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with
+unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`.
 
 **Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
 
@@ -290,8 +307,9 @@ returns `WINDOW_HAS_UNMANAGED_TABS`.
 | `network` | Network request logs (with URL filter) |
 
 Parameters: `output` saves result to file. Network logs include completed requests, HTTP 4xx/5xx responses, and failed
-loads with `errorText`, `method`, `url`, `status`, `timestamp`, and `duration` when available. `tabId` targets a
-specific tab (Extension mode). `frame` is not applicable for logs.
+loads with `errorText`, `method`, `url`, `status`, `timestamp`, and `duration` when available. `urlPattern` supports
+`*` for any number of characters and `?` for one character. `tabId` targets a specific tab (Extension mode). `frame` is
+not applicable for logs.
 
 ### cookies - Cookie Management