## Summary
This PR fixes several documentation and skill-reference issues across
the repo to improve accuracy and reduce confusion in implementation and
troubleshooting workflows.
## Changes
- corrected CLI examples in skill docs
- fixed the documented argument order for `performance_analyze_insight`
- updated the memory leak fallback script path
- corrected generated tool reference wording by updating the
source-of-truth tool descriptions
---------
Co-authored-by: ojonesjr <50652264+ojonesjr@users.noreply.github.com>
## Summary
Fix `chrome-devtools start` so it no longer implicitly enables
`isolated` when `--userDataDir` is provided.
Previously, the CLI wrapper always defaulted `isolated` to `true` for
`start`, which caused `userDataDir` and `isolated` to conflict even when
the user only specified `--userDataDir`. This made it impossible to
start the CLI daemon against a persistent browser profile.
## Changes
- Update `chrome-devtools start` default handling in
`src/bin/chrome-devtools.ts`
- only default `isolated=true` when `userDataDir` is not set
- Clarify the `isolated` CLI description to document the conditional
default
- Update `docs/cli.md` to reflect that:
- `headless` is enabled by default
- `isolated` is enabled by default unless `--userDataDir` is provided
- Fix a small error message typo
## Why
This matches the intended semantics of the flags:
- `--isolated` means use a temporary user data dir
- `--userDataDir` means use a persistent, explicit user data dir
If the user passes `--userDataDir`, the CLI should not also implicitly
enable `isolated`.
## Testing
- Ran:
- `npm test -- tests/cli.test.ts`
- `npm test -- tests/e2e/chrome-devtools.test.ts`
Added an e2e regression test in `tests/e2e/chrome-devtools.test.ts` to
verify that:
- `chrome-devtools start --userDataDir <temp dir>` succeeds
- the CLI no longer fails with `Arguments userDataDir and isolated are
mutually exclusive`
- the daemon starts successfully when `userDataDir` is provided
## Summary
When installing `chrome-devtools-mcp` as a Claude Code plugin (from the
official Anthropic marketplace or via `/plugin marketplace add`), the
plugin system clones the repository using HTTPS
(`https://github.com/ChromeDevTools/chrome-devtools-mcp.git`). In
environments where outbound HTTPS connectivity to GitHub is restricted —
such as servers behind corporate firewalls, restrictive proxy
configurations, or hosts with port 443 blocked — this clone operation
fails with a timeout:
```
chrome-devtools-mcp@claude-plugins-official: Failed to download/cache plugin chrome-devtools-mcp:
Failed to clone repository: Cloning into '...'...
fatal: unable to access 'https://github.com/ChromeDevTools/chrome-devtools-mcp.git/':
Failed to connect to github.com port 443 after 136078 ms: Couldn't connect to server
```
This is a real-world scenario encountered on production Linux servers
where SSH to GitHub (port 22) works but HTTPS (port 443) is blocked or
unreliable. The Claude Code plugin marketplace
(`anthropics/claude-plugins-official`) specifies the HTTPS URL as the
plugin source, and users have no way to override this URL within the
plugin system itself.
## Changes
### `docs/troubleshooting.md`
Added a new troubleshooting section **Claude Code plugin installation
fails with `Failed to clone repository`** under Specific problems that
documents:
- **The exact error message** users encounter, making it searchable
- **Root cause explanation**: restricted HTTPS connectivity, firewalls,
proxy configs
- **Workaround 1 — SSH redirect**: Using `git config --global
url."git@github.com:".insteadOf "https://github.com/"` to transparently
redirect all GitHub HTTPS git operations to use SSH
- **Workaround 2 — CLI installation**: Using `claude mcp add
chrome-devtools --scope user npx chrome-devtools-mcp@latest` to install
the MCP server via npm/npx instead of git clone
### `README.md`
Added a `[!TIP]` callout in the Claude Code **Install as a Plugin**
section that cross-references the troubleshooting guide.
## Motivation
The HTTPS clone URL for this plugin is defined in the Anthropic official
plugin marketplace, not in this repository. Since users cannot change
the marketplace URL configuration, the most actionable fix from this
repository's side is to document the issue and provide clear
workarounds.
## Test plan
- [x] `npm run check-format` passes (eslint + prettier)
- [x] `npm run gen` produces no unexpected diff (auto-generated docs
unchanged)
- [x] Documentation-only change — no code, tool, or schema modifications
- [x] Markdown anchor link in README TIP callout correctly references
the troubleshooting section heading
- [x] Both workaround commands verified in the environment where this
issue was encountered
Added solutions for MCP server connection issues on Windows 10,
including using cmd and absolute path for npx.
---------
Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com>
Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
Addresses cases where DevTools MCP tools were not consistently picked up
from natural language prompts by improving tool descriptions and
metadata.
Validation:
Tested locally across multiple prompts related to LCP and page
performance.
MCP tools were selected more consistently after the description updates.
Refs #940
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com>
Co-authored-by: Nikolay Vitkov <34244704+Lightning00Blade@users.noreply.github.com>
Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
- **feat: add troubleshooting skill definition and expand documentation
with details on autoConnect timeouts and extension debugging
conflicts.**
- **docs: Simplify troubleshooting skill instructions by removing
explicit tool mentions and updating the troubleshooting guide link.**
- **docs: Update troubleshooting guide to recommend and correct usage of
`--logFile` for capturing debug logs.**
- **docs: Enhance troubleshooting guide with 'Tool not found' error,
`--autoConnect` Chrome 144+ requirement, and `startup_timeout_ms` tip
for Windows.**
- **docs: Clarify that Chrome 144+ must be running for `--autoConnect`
and add a verification step for remote debugging.**
- **feat: Add an initial troubleshooting step to read and interpret MCP
configuration, renumbering subsequent steps.**
- **docs: Add detailed troubleshooting steps for `Could not find
DevToolsActivePort` and other common connection errors.**
- **docs: Add troubleshooting guidance for empty profile creation due to
typos or misconfiguration.**
- reduces the token usage.
- makes emulation and script compatible with CLI.
- documents .nullable() and .object() restrictions for the future.
- the emulation tools do not have nullable anymore and undefined would
clear the emulation instead. The model is thus required to provide all
emulation settings at once.
Closes https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/918
`type_text` is useful for pages that do not have a11y and, thus, uid is
not known. It's also useful for testing user-like keyboard input and
testing the focus state changes. The `fill` tools force the focus change
and require an uid and therefore are not suitable for these tasks.
## Summary
Enhances wait_for to support waiting on multiple possible texts and
resolve when any one appears.
This addresses long-running flows that can end in different UI outcomes
(for example, "Complete" or "Error"), avoiding unnecessary 300s waits
when only one expected string is provided.
Closes#916.
## Tool Update
### wait_for
Waits for text on the selected page, now with any-match support.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| text | string \| string[] | yes | A single text or a non-empty list of
texts. Resolves when any value appears. |
| timeout | integer | no | Maximum wait in ms (0 keeps default
behavior). |
---
## Design / Implementation
- Kept backward compatibility: existing single-string text calls
continue to work unchanged.
- Added schema support for string | string[] with non-empty array
validation.
- Updated context API to accept string | string[].
- Matching logic now normalizes to an array and races all candidates
across all frames using both:
- aria/<text>
- text/<text>
- Added clearer response output for array input:
- Element matching one of ["Complete","Error"] found.
- Updated generated tool docs for the new wait_for contract.
- Improved docs generation to render ZodUnion types (so union params are
documented correctly, not as unknown).
---
## Tests
Added/updated coverage for:
- Schema acceptance of:
- single string
- non-empty string array
- rejection of empty array
- Any-match array success case
- Any-match array when matching text appears later (async/delayed
content)
- Existing wait_for behavior remains covered for single-text usage
Executed relevant test suites:
- tests/tools/snapshot.test.ts
- tests/McpContext.test.ts
- tests/index.test.ts
Confirmation after the change applied:
https://opncd.ai/share/8m6I4r4a
## Summary
Adds storage-isolated browser contexts via an optional `isolatedContext`
parameter on the `new_page` tool, following the simplified design
proposed by @OrKoN in #926.
Pages created with the same `isolatedContext` name share cookies,
localStorage, and storage. Pages in different isolated contexts (or the
default context) are fully isolated — ideal for testing multi-user
real-time features like chat, notifications, or collaborative editing.
## Changes
### `new_page` tool
- New optional `isolatedContext: string` parameter
- If specified, creates/reuses a named `BrowserContext` and opens a page
in it
- If omitted, uses the default browser context (existing behavior
unchanged)
### `McpContext`
- `#isolatedContexts` Map: LLM-provided names → Puppeteer
`BrowserContext` instances
- `#pageToIsolatedContextName` WeakMap: GC-safe page → context name
reverse lookup
- Auto-discovery: externally created browser contexts get
`isolated-context-1`, `isolated-context-2`, etc.
- `getIsolatedContextName(page)`: returns the isolated context name for
a page (used by response formatting)
- `page.browserContext()` used for context membership detection (no
custom target event forwarding needed)
- No context cleanup in `dispose()` or `closePage()` — either the entire
browser is closed or we disconnect without destroying state
### `McpResponse`
- Page list includes `isolatedContext=${name}` labels (both text and
structured JSON output)
### `ToolDefinition`
- `Context` interface extended with `getIsolatedContextName(page)`
method
## What's NOT included (by design)
- **No `TargetEventEmitter`**: Puppeteer forwards target events from
`BrowserContext` → `Browser` internally
- **No context cleanup**: Browser contexts are not closed on `dispose()`
or page close, per maintainer guidance
- **No `about:blank` cleanup**: Default context and isolated contexts
coexist side-by-side
## Example
```
> new_page url="https://app.example.com/chat" isolatedContext="userA"
> new_page url="https://app.example.com/chat" isolatedContext="userB"
> list_pages
Page 1: [app.example.com/chat] isolatedContext=userA
Page 2: [app.example.com/chat] isolatedContext=userB [selected]
```
Pages in different isolated contexts have fully independent cookies,
localStorage, IndexedDB, and WebSocket connections.
## Tests
- 6 new tests covering `isolatedContext` feature in
`tests/tools/pages.test.ts`
- All existing tests pass (333+)
- Zero type errors, lint clean
Closes#926
---------
Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
Added workarounds for using chrome-devtools-mcp in WSL.
Drive-by: moved known issues from readme to troubleshooting.
Drive-by: updated skill to link to troubleshooting.
Drive-by: rephrased for clarity.
Docs-only change: add a troubleshooting note for macOS Web Bluetooth
chooser crashes in MCP-launched Chrome and the Bluetooth permission
workaround.
Fixes#917
## Summary
- Add `background` boolean parameter to the `new_page` tool
- When set to `true`, the new page opens in the background without
bringing it to the front
- Uses Puppeteer's existing `background` option for `browser.newPage()`
Fixes#826
---------
Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com>
Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
bringToFront() not only brings the tab to front in the browser but also
the browser window itself. This PR fixes the issue by making the call to
bringToFront() optional allowing agents to bring a tab to the user's
attention if needed but not always. To mitigate the risk of selected
page that is in the background being throttled, this PR implements
emulation of the focused page to make background tabs run as usual.
Guy Owen