Adonis0123/adonis-skills / skills/chrome-dev-mcp
chrome-dev-mcp
VerifiedUse this skill when the user invokes /chrome-dev-mcp or asks for Chrome DevTools MCP, CDP, list_pages/select_page, UXC packaging for Chrome DevTools, DOM snapshots, Console, Network, Performance, Lighthouse, heap analysis, browser-internal debugging, connection recovery, or correct-Chrome validation across Claude Code, Codex, Grok Build/Grok002, Cursor CLI, Hermes, or WorkBuddy. Use it when the evidence is Chrome-specific (Lighthouse, a full trace, heap data) or the caller has no page session yet; a page already open in ego-browser keeps its own Console and request diagnosis. Also use it as the verification step right after the user or this session changes a web UI or asks to accept or check a page: collect a screenshot, Console, and Network evidence before calling it done. Do not use it for ordinary navigation, form filling, scraping, or desktop UI unless browser-internal signals or UI-change acceptance are required. A passing readiness or list_pages check proves the connection only, never the change.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.4 KB |
| evals/evals.json | config | 14.7 KB |
| evals/trigger-eval.json | config | 3.3 KB |
| references/host-verification.md | markdown | 5.9 KB |
| references/maintenance.md | markdown | 4.5 KB |
| references/profile-identity.md | markdown | 1.6 KB |
| references/uxc-facade.md | markdown | 7.5 KB |
| scripts/configure-local.zshexecutable | script | 1.8 KB |
| scripts/ensure-connection.zshexecutable | script | 2.6 KB |
| scripts/host-acceptance.zshexecutable | script | 6.9 KB |
| scripts/install-uxc.zshexecutable | script | 4.0 KB |
| scripts/lib/load-config.zshexecutable | script | 438 B |
| scripts/lib/readiness-envelope.zsh | script | 1.5 KB |
| scripts/lib/uxc-link-contract.zsh | script | 1.5 KB |
| scripts/lib/uxc-owned-binary.zsh | script | 2.8 KB |
| scripts/lib/uxc-release.zshexecutable | script | 642 B |
| scripts/setup-uxc-link.zshexecutable | script | 3.1 KB |
| scripts/test/host-acceptance.test.mjs | script | 5.3 KB |
| scripts/test/readiness-envelope.test.mjs | script | 2.7 KB |
| scripts/test/ui-acceptance.test.mjs | script | 5.2 KB |
| scripts/uxc-readiness.zshexecutable | script | 2.7 KB |
SKILL.md
View on GitHub---
name: chrome-dev-mcp
description: "Use this skill when the user invokes /chrome-dev-mcp or asks for Chrome DevTools MCP, CDP, list_pages/select_page, UXC packaging for Chrome DevTools, DOM snapshots, Console, Network, Performance, Lighthouse, heap analysis, browser-internal debugging, connection recovery, or correct-Chrome validation across Claude Code, Codex, Grok Build/Grok002, Cursor CLI, Hermes, or WorkBuddy. Use it when the evidence is Chrome-specific (Lighthouse, a full trace, heap data) or the caller has no page session yet; a page already open in ego-browser keeps its own Console and request diagnosis. Also use it as the verification step right after the user or this session changes a web UI or asks to accept or check a page: collect a screenshot, Console, and Network evidence before calling it done. Do not use it for ordinary navigation, form filling, scraping, or desktop UI unless browser-internal signals or UI-change acceptance are required. A passing readiness or list_pages check proves the connection only, never the change."
metadata:
author: adonis
version: "1.7.0"
---
# Chrome Dev MCP
Collect browser-internal evidence (snapshots, Console, Network, Performance, Lighthouse, heap) from one identity-checked Chrome through the shared `chrome-dev-mcp-cli`. Every agent on the machine reuses one daemon-backed MCP child, so the rules below exist to keep that shared session healthy and to keep your claims honest.
Everything a page task needs is in this file. Read a reference only when its trigger below applies; the `uxc-facade` skill is a packaging method and is not needed to run a task.
## Get a proven connection
Run helpers with `zsh` from this skill's directory (under `bash` they abort with `A: unbound variable`).
| Invocation | Command | On success |
| ------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------- |
| `/chrome-dev-mcp` with no task | `zsh scripts/uxc-readiness.zsh` | Reply only `CHROME_DEV_MCP_READY` |
| Any page task | `zsh scripts/uxc-readiness.zsh --private-result` | Keep the `list_pages` JSON private and use it to pick the numeric `pageId` |
Both run one real shared `list_pages` and check the UXC envelope and the tool result (`data.isError`). A page task runs only the private mode, once; do not run the sanitized mode first.
If readiness prints `STATUS=ERROR`:
1. Except for `link_contract_mismatch` (step 3), run `zsh scripts/ensure-connection.zsh --recover` once, then repeat the same readiness command once. The post-recovery JSON is your page list.
2. `ERROR_CLASS=exclusive_key_busy` means another MCP session holds the browser. If this session called host-native Chrome DevTools tools (for example `mcp__chrome-devtools__*`), that session is the holder: stop using them. Otherwise another agent is mid-call; the single retry above is enough.
3. `ERROR_CLASS=link_contract_mismatch` means the shared launcher was generated for a different copy of this skill (for example an installed copy while you run from a repository checkout). Recovery cannot fix it. Read the bound copy with `grep -o "UXC_LINK_SKILL_PATH='[^']*'" "$(command -v chrome-dev-mcp-cli)"` and rerun the helpers from that directory. Do not rerun `setup-uxc-link.zsh` to repoint the launcher: it is shared by every agent and fails closed on a foreign contract by design.
4. Still failing: report the one failing layer (`ERROR_CLASS` or `REASON`) and one next action. `WRONG_PROFILE`, `WRONG_BINARY`, or `NOT_CHROME` fail closed; read [references/profile-identity.md](references/profile-identity.md).
Never run `uxc daemon stop`, restart, or kill UXC, Chrome, or MCP processes to recover: the daemon and browser are shared, so this cuts off other agents' sessions. Never loop on retries, scan ports, read `DevToolsActivePort`, attach to another browser, call `uxc` directly, or fall back to `npx`/`@latest`. Do not substitute Playwright, Computer Use, or raw CDP for a failed connection; their evidence comes from a different browser session. If `chrome-dev-mcp-cli` is missing, run `zsh scripts/setup-uxc-link.zsh` once (it installs the launcher only when the pinned owned UXC is present and refuses foreign links); if that fails, report `NATIVE_COMPAT_REQUIRED`. Use host-native `chrome-devtools` only when the user explicitly asks for native compatibility, and label that mode.
## Pick the target page
- Take `pageId` from this turn's `list_pages`, never from an earlier turn. Other agents open, close, and navigate tabs, so ids shift: re-run `list_pages` and match by URL before each batch of writes, after recovery, and after any navigation.
- The page list is the text at `data.content[0].text`, one tab per line as `<id>: <title> (<url>) [selected]`. Match on the URL inside the last parentheses, not the title; a host/port prefix match is enough when the user gave no path.
- Pass `pageId=<id>` to every page-scoped call. Do not rely on `select_page` state.
- If the requested tab is not in the list, it belongs to another browser or profile. Say so. Open the URL with `new_page` only when it needs no existing login state; otherwise ask the user to open it in the managed Chrome.
- Never print the page list or unrelated URLs, titles, body text, cookies, or tokens.
## Call the CLI correctly
```bash
chrome-dev-mcp-cli --timeout-ms 15000 take_snapshot pageId=3
chrome-dev-mcp-cli evaluate_script pageId=3 waitForStableDom=false 'function=() => document.title'
chrome-dev-mcp-cli list_network_requests pageId=3 pageSize=20 'resourceTypes:=["fetch","xhr"]'
chrome-dev-mcp-cli navigate_page pageId=3 type=url url='http://localhost:3000/x' timeout=30000
chrome-dev-mcp-cli <operation> -h # live schema wins over this file
```
- Arguments are `key=value`, or `key:=<json>` for arrays and objects. There are no `--pageId`/`--json` flags and no `call` subcommand.
- `--timeout-ms` is a global flag and goes before the operation. `navigate_page` and `new_page` have their own 10-second navigation timeout: pass `timeout=30000` for dev servers. A navigation timeout often means a slow `load` event, not a failed page; take a snapshot before retrying.
- `"ok": true` only means UXC delivered the call. The operation failed if `data.isError` is true; read `data.content[0].text` for the reason.
- Use `waitForStableDom=false` for read-only `evaluate_script`. Take a fresh snapshot before element work and after each interaction; `uid`s change when the DOM changes. Re-read Console and Network after an interaction too, because earlier lists do not include what the interaction triggered.
## Write artifacts to the runtime temp root
Screenshots, snapshots, traces, heap snapshots, and saved bodies go under `"$(getconf DARWIN_USER_TEMP_DIR)"` (the MCP child's `os.tmpdir()`, `/var/folders/.../T/`). The runtime rejects `/tmp`, host scratchpads, and repository paths with `is not within any of the configured workspace roots`. Always pass `filePath` for screenshots, because the inline image is truncated and unusable; `format=jpeg` saves with a `.jpeg` extension. Copy the file elsewhere afterwards if needed, and return the path with a bounded summary. Never add `--allow-unrestricted-paths`. If that directory is also denied, stop trying other paths and report the artifact `UNVERIFIED`.
## Collect Network evidence
1. `list_network_requests` with the fresh `pageId`; pick the failing request's `reqid`.
2. `get_network_request pageId=<id> reqid=<reqid>` returns status, headers, and body inline. Use `responseFilePath=` under the runtime temp root only for a large body. Read only the fields the task needs.
3. A missing body does not mean the request failed or returned nothing; Chrome may not retain bodies of failed, redirected, or streamed responses. Report the status and headers, mark the body unavailable, and never replay a request with side effects to get it.
## Keep a time budget
Readiness bounds its `list_pages` at 45 seconds. Allow one recovery and one retry per invocation. Keep a routine diagnosis within about 90 seconds of tool time; when the budget is spent or a call fails, report what you have and mark the rest `UNVERIFIED`. Performance traces and Lighthouse state their own durations, so skip `--timeout-ms` for them.
## Share the browser safely
Calls through `chrome-dev-mcp-cli` still run one at a time: the runtime can run tools for different pages in parallel, but the shared UXC session delivers them in order, so concurrent calls save no time. No cross-agent lock exists for multi-step writes to one tab. When another agent may own the tab, report `UNVERIFIED` instead of racing it. Real pointer, keyboard, focus, and screen-recording sequences share one desktop cursor, so serialize them across agents. The daemon exclusive key is a browser ownership guard: do not remove it, invent per-agent keys, or kill its holder.
## Report honestly
`CHROME_DEV_MCP_READY` and `list_pages` prove the connection only. Claim a task `VERIFIED` only after the requested snapshot, Console, Network, Performance, or interaction call itself returned without `data.isError`.
When the user or this session just changed a web UI, this skill is the verification step: an agent that stops at the code diff has not seen the page. After reloading or repeating the interaction on the fresh `pageId`, collect three pieces of evidence before calling the change done, because each catches a different failure:
- A `take_screenshot` with `filePath` under the runtime temp root shows the resulting UI; a snapshot or diff cannot show layout or styling.
- `list_console_messages` read after the interaction shows new errors the change introduced.
- Read `list_network_requests` after the interaction. The relevant `list_network_requests` entry shows the request the change should have made and its status. When no request is expected (for example a CSS-only change or local UI toggle), a successfully read empty Network list is valid evidence: state that no request was expected or observed. Do not invent or replay a request to satisfy this check. An expected request that is absent, or a Network call that fails, leaves the change `UNVERIFIED`.
If one is missing, report the change `UNVERIFIED` and name the gap. A question only about Console or Network on an already open page needs just that evidence, not a screenshot.
Invoke as `/chrome-dev-mcp` in Claude Code, Grok, and Cursor CLI (`cursor-agent`), `$chrome-dev-mcp` in Codex; preload `chrome-dev-mcp` in Hermes for deterministic selection.
## Read only when needed
| Trigger | Reference |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Wrong browser, profile, or login context | [references/profile-identity.md](references/profile-identity.md) |
| Installing or relinking UXC, the runtime chain, isolated-browser parallelism | [references/uxc-facade.md](references/uxc-facade.md) |
| Upgrading Chrome DevTools MCP, UXC, or this skill | [references/maintenance.md](references/maintenance.md) |
| Multi-host acceptance, process-count checks, native compatibility rollback | [references/host-verification.md](references/host-verification.md) |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |