Let Claude drive real Chrome via chrome-devtools-mcp

[srid]

Prototype for #518. Wires the official chrome-devtools-mcp server so Claude (and any other MCP client) can drive a real headless Chrome against Kolu's own dev server — evaluate_script, list_console_messages, take_screenshot, network inspection, performance traces, all 29 tools. Solves the recurring "I'm guessing at CSS cascade / computed styles" round-trip that inspired the issue.

The wiring lives in three places. .mcp.json at the repo root is the bit Claude Code actually reads — Claude starts outside the nix devshell, so the nix develop --command just ai::mcp-chrome-devtools wrapper bridges into a shell where npx/node and the Playwright-provided Chrome-for-Testing are on PATH. The launcher recipe sits in agents/ai.just alongside the rest of the APM/agent dev tooling, and resolves Chrome's binary inline by globbing $PLAYWRIGHT_BROWSERS_PATH/chromium-*/chrome-linux64/chrome so there's no shell.nix surface area to maintain. Reuses Playwright's Chrome-for-Testing 143, which chrome-devtools-mcp officially supports — no new browser dependency, just the Node package fetched by npx.

End-to-end smoke verified: JSON-RPC initialize returns chrome_devtools v0.21.0 with tools.listChanged capability advertised. Navigated to http://localhost:7681, took an a11y snapshot, evaluated document.querySelectorAll('[data-terminal-id]') to probe live sidebar state — all 29 tools work as expected. Warm nix develop eval stays at ~0.25s.

Follow-up encapsulation is gated on microsoft/apm#655. Once that PR (Claude Code MCP adapter) merges and lands in juspay's fork, the chrome-devtools entry folds into agents/apm.yml's dependencies.mcp and .mcp.json becomes a generated artifact of just ai::apm. The TODO is captured in the mcp-chrome-devtools recipe's doc comment.

Telemetry note. chrome-devtools-mcp sends usage statistics to Google by default, and performance traces send URLs to the Chrome CrUX API. Left default-on for this prototype — if unwanted, add --no-usage-statistics --no-performance-crux to the recipe before merge.

Refs #518.

[srid]

Hickey Analysis

Structural review run against the plan before implementation. Three findings, all addressed (or deferred with justification):

(a) Chrome executable discovery was split across Nix → shell glob → env → JSON. Initial plan used a shellHook glob over $PLAYWRIGHT_BROWSERS_PATH/chromium-*/chrome-linux64/chrome — brittle (silent on Playwright layout change) and pushed path ownership out of the Nix layer. Addressed: refactored to Nix-eval-time resolution via builtins.readFile over playwright-driver/browsers.json (idiom from wiki.nixos.org/wiki/Playwright). Fails loud at eval if layout changes; builtins.head throws on empty filter result. No shell glob remains.

(b) "Headless Linux only" was prose, not a structural constraint. Considered gating with lib.optionalAttrs pkgs.stdenv.isLinux { … }. Deferred for prototype scope — the derived path uses chrome-linux64 which simply won't exist on Darwin, so chrome-devtools-mcp fails loud at startup rather than silently succeeding with wrong chrome. Comment in shell.nix explains the constraint. Revisit if/when this graduates past prototype.

(c) MCP integration establishes a pattern without considering multi-MCP strategy. The standalone .mcp.json + justfile recipe works for one server; unclear whether a second MCP should share a recipe convention, a config file, or a discovery mechanism. Deferred — not blocking for a prototype, but someone should decide before adding MCP #2 so we don't end up with ad-hoc integration per server.

Fact-check of the applied simplification: moving path computation to Nix eval vs. shellHook was verified to preserve warm nix develop time (0.203s over 3 runs, matches the ~0.3s project target) — builtins.readFile IFD is memoized, no regression.

[srid]

[srid]

/do results

Step	Status	Verification
sync	✓	fetched origin, forge=github, branch=awed-speck, clean tree
research	✓	confirmed .mcp.json+env-expansion, playwright chromium = CfT 143
hickey	✓	nix-eval-time path resolution accepted (later dropped for encapsulation); multi-MCP strategy deferred
branch	✓	on awed-speck per user directive "in this branch"
implement	✓	three commits: initial wiring (216b159), forward-compat comment (63a28ec), agents/ai.just encapsulation (5a844c9)
check	✓	just check: pnpm typecheck clean across all 7 packages
docs	—	skipped — dev-time Claude Code affordance, no Architecture changes
police	✓	rules/fact-check/elegance all clear
fmt	✓	just fmt: 0 files reformatted
commit	✓	3 commits pushed to awed-speck
test	—	skipped — MCP config + dev tooling, no runtime/UI changes
create-pr	✓	draft PR #519; hickey analysis posted as PR comment
ci	✓	all 12 contexts success; e2e@aarch64-darwin flaked once on OSC-52 clipboard race, passed on retry — logged to #320

Optimization suggestions

• Encapsulation was a multi-iteration restructure. Would have shipped one commit instead of three if I'd checked the ~/code/apm source earlier — specifically the adapters directory — before concluding APM couldn't target Claude Code. The apm install -t claude flag + existing .claude/ auto-detection were documented, but the MCP adapter gap wasn't obvious without reading adapters/client/. Next time: for "is this feature supported?" questions about upstream tooling, ls the adapter directory before trusting the CLI help text.
• nix develop warmup via shell.nix edits. Each shell.nix change invalidates eval cache → first run ~2s, subsequent runs drop back to ~0.25s. Consider batching multiple shell.nix experiments into one edit to pay the cold-eval cost once.
• Darwin e2e flake on OSC-52 clipboard (Flaky tests log #320) keeps costing a CI retry slot. The failure mode (navigator.clipboard leaking prior scenario content on darwin) suggests the fix is a per-scenario clipboard reset in hooks.ts, not just logging the flake.