Chrome Dev MCP

Chrome Dev MCP

Use the managed chrome-dev-mcp-cli facade for browser-internal evidence. It reuses one identity-checked MCP child instead of starting one child per agent session. Keep host-native registration only as an explicit compatibility and rollback path.

Require the locally configured safe wrapper, launcher, and pinned UXC 0.17.0 facade. Never silently fall back to a host-native server because doing so recreates the per-session runtime fan-out this skill is designed to avoid.

For runtime or skill upgrades, follow references/maintenance.md: check versions, preserve rollback, stage, activate, verify real operations and process reuse, then synchronize hosts. Ordinary page tasks do not load this maintenance workflow.

Keep the user contract simple

Let the user remember only /chrome-dev-mcp. Handle connection checks, recovery, profile gates, shared-session reuse, and explicit pageId routing internally. With no additional task, return only CHROME_DEV_MCP_READY after sanitized shared readiness. When the same invocation includes a page task, use the readiness-plus-task fast path below instead of discarding a list_pages result that the task immediately needs. On failure, report one failing layer and one required action.

Execute the slash entry

Treat /chrome-dev-mcp without a task as a readiness-only action. Treat the same invocation with a page task as readiness-plus-task.

1. For readiness-only, run scripts/uxc-readiness.zsh from this skill. It performs a real shared list_pages call, discards the page payload, and returns only CHROME_DEV_MCP_READY on success.
2. For readiness-plus-task, run scripts/uxc-readiness.zsh --private-result. This strict mode validates the configured binary/link ownership contract, prepends the managed binary directory ahead of inherited PATH, calls shared list_pages exactly once, and returns its JSON only to the agent. Keep the result private and reuse that same current-turn result as both transport proof and fresh numeric pageId resolution. Do not run the payload-discarding mode first or call the linked CLI directly.
3. If either path reports a connection or wrapper failure, run scripts/ensure-connection.zsh --recover, then retry exactly once with the same path: scripts/uxc-readiness.zsh for readiness-only, or scripts/uxc-readiness.zsh --private-result for readiness-plus-task. The latter post-recovery JSON is the fresh result for the task.
4. If the CLI, shell, or required response type is unavailable, report NATIVE_COMPAT_REQUIRED; do not start a native server automatically.
5. Use host-native chrome-devtools only when the user explicitly requests native compatibility or approves it after that blocker. Mark that mode because it adds one runtime per host session.
6. A successful list_pages proves readiness, not the requested page operation. Claim the task VERIFIED only after its Console, Network, snapshot, interaction, or other requested command independently completes.
7. Never expose the private page list or unrelated page URLs, titles, body text, cookies, tokens, or target data.

Use /chrome-dev-mcp in Claude Code and Grok, $chrome-dev-mcp in Codex, and preload chrome-dev-mcp in Hermes when deterministic selection is needed.

Preserve the runtime invariant

Keep one default chain:

managed chrome-dev-mcp-cli
  -> pinned UXC daemon and one reusable stdio session
  -> user-configured safe wrapper
  -> identity-checked loopback Chrome
  -> pinned chrome-devtools-mcp runtime

Require the safe wrapper to validate its configured endpoint, WebSocket address, browser process, and intended profile before exposing the MCP runtime. Let the wrapper launch only the configured isolated profile when the endpoint is absent. Never scan ports, read DevToolsActivePort, attach to a remote endpoint, or silently fall back to another browser.

Treat skill discovery, shared transport discovery, server handshake, tool discovery, endpoint identity, and a real tool call as separate layers. Host-native MCP discovery is a compatibility-only layer.

Route by task semantics

Use this skill for:

• DOM or accessibility snapshots and in-page JavaScript evidence.
• Console, Network, Performance, Lighthouse, or heap diagnostics.
• Chrome DevTools MCP/CDP connectivity and correct-profile diagnosis.
• Multi-host discovery and real-tool-call acceptance.

Use the host's native Chrome/browser capability for ordinary navigation and form filling. Use native Computer Use for browser chrome, macOS windows, and cross-app work. Do not substitute Playwright, Computer Use, raw CDP, or another browser layer for missing DevTools evidence when the requested evidence is browser-internal.

Start with runtime proof

1. Before using any page ID from an earlier turn, obtain shared list_pages or reuse the eligible readiness-plus-task result from this turn.
2. Reuse one current-turn result only when no recovery, navigation, or target ambiguity occurred after it. Otherwise refresh list_pages before resolving the target. Ask only when the fresh result cannot resolve the target safely.
3. Pass the fresh numeric pageId to every page-scoped command. Do not rely on shared select_page state.
4. Take a fresh text snapshot before element work.
5. Collect only the requested internal signals.
6. After interaction, take a new snapshot and refresh the relevant Console or Network evidence.

Do not echo unrelated page data. A successful handshake is not proof of attachment; a completed list_pages call is the minimum runtime proof.

Recover by failed layer

Shared CLI absent

Run scripts/setup-uxc-link.zsh only after confirming the pinned owned UXC binary is installed. Fail closed on a foreign link or binary. Do not substitute npx, @latest, or auto-connect.

Startup or tool call failed

Run scripts/ensure-connection.zsh --recover from this skill, then retry the path-specific shared list_pages proof once. Use scripts/uxc-readiness.zsh for readiness-only and scripts/uxc-readiness.zsh --private-result for readiness-plus-task; retain the recovered private result for fresh pageId resolution. The helper reads the one-time local configuration produced by scripts/configure-local.zsh; it does not depend on shell aliases or login-shell startup.

If identity validation reports the wrong browser or profile, fail closed. Read references/profile-identity.md. Never close or restart an existing browser without explicit authorization.

Keep UXC as the default facade

Read references/uxc-facade.md for installation, ownership, reuse, and acceptance details. UXC exposes the safe wrapper as a deterministic JSON-first CLI and reuses its stdio child through a local daemon. It replaces eager native registration as the normal execution path, but it does not replace correct-browser validation.

Use uxc-facade for the generic packaging contract. This skill remains the owner of Chrome identity, connection recovery, explicit pageId routing, safe payload handling, and real-call acceptance.

Reuse scripts/install-uxc.zsh for the pinned UXC binary and its owner manifest. Keep Chrome-specific linking in scripts/setup-uxc-link.zsh; scripts/uxc-readiness.zsh owns both payload-stripping readiness and the private-result task fast path. Never execute an unowned uxc, accept a PATH fallback, or overwrite a managed link whose exact contract differs.

Handle concurrency

Use the installed chrome-dev-mcp-cli for every call. Its managed launcher fixes the working directory before UXC computes session identity and invokes the owned binary by absolute path. UXC 0.17.0 includes the caller's working directory in stdio identity; calling uxc <wrapper> directly from project directories creates competing sessions for the same exclusive key. The exclusive key is a browser ownership guard, not a task lock: do not remove it, invent per-agent keys for the same browser, kill another session, or loop until it releases. Repair a known legacy launcher with scripts/setup-uxc-link.zsh; it preserves the exact old owned link and refuses foreign contracts.

Real system-pointer input has one shared cursor and foreground window across the desktop. Serialize drag, keyboard, focus, and screen-recording sequences that depend on them, even across different tabs. For parallel browser work, prefer explicit pageId DevTools operations on separate pages. A required real-pointer test must reserve exclusive desktop use for its duration; a transport fix cannot make simultaneous pointer control independent.

With Chrome DevTools MCP 1.9.0, use --pageIdRouting (enabled by default); older wrappers may name the experimental flag. Verify the live schema still requires pageId after upgrading. Pass a fresh pageId to every page-scoped read or write so one agent cannot change another agent's selected-page context. Different page IDs route safely, but the runtime serializes individual tool calls and does not guarantee parallel execution. No cross-agent transaction lock exists for multi-step writes to one tab; report that case UNVERIFIED and stop when ownership is unclear. Use separate isolated browsers for truly parallel writes that cannot share a tab safely.

For a purely read-only evaluate_script, use waitForStableDom=false when the live schema supports it; DOM mutations still need stability and post-action verification. Keep output bounded to the requested evidence.

Shared UXC does not negotiate workspace roots. Write screenshots, snapshots, traces, or heap data only to an OS temporary path first, return the path and a bounded summary, then move the artifact only after its contents and destination are validated. Never add --allow-unrestricted-paths. If the host must render native content blocks, use explicit native compatibility mode.

Report acceptance

For multi-host validation, report each host independently:

Use VERIFIED only after the real shared tool call. Report native compatibility separately and leave it NOT_USED on the healthy default path. Otherwise report UNVERIFIED or the explicit external blocker.

For multi-session installation or performance acceptance, also verify process count before and after concurrent calls: one shared MCP child with the same PID, not one child per host. Check OS parent processes as well as UXC sessions, because eager native children are invisible to UXC. Read references/host-verification.md for residual-process handling.