amhuppert/setup-perf-stack

Setup: Performance Debugging Stack

Bootstrap the MCP servers and skills required for Claude Code to autonomously investigate performance issues in web applications.

This skill only handles installation. For the actual investigation workflow (the reproduce → capture → analyze → fix → validate loop, framework-specific rules, per-scenario playbooks), use the investigate-web-perf skill once setup is complete.

What This Skill Installs

The anchor is chrome-devtools-mcp — it wraps Puppeteer + CDP and exposes performance_analyze_insight, which compresses a ~30 MB Chrome trace into a ~4 KB summary across 18 named insights (LCPBreakdown, INPBreakdown, ForcedReflow, DuplicatedJavaScript, CLSCulprits, etc.). Without this compression, raw traces blow the context window. Everything else layers on top.

| Component | Role | Required? | |-----------|------|-----------| | chrome-devtools-mcp | Lab traces, CDP, insights, Lighthouse-in-MCP | Yes | | Chrome DevTools Skills plugin | Curated LCP + a11y workflows that prevent Perf-API hallucinations | Yes | | next-devtools-mcp | Next.js 16+ dev-server bridge, route tree, Suspense automation | Next.js 16+ only | | @danielsogl/lighthouse-mcp | Batch scoring + regression diff | Optional; CDT MCP has lighthouse_audit | | react-scan dev dep | Runtime render profiler (successor to why-did-you-render) | React projects | | Dedicated Chrome debug profile | Required for authenticated sites (Chrome 136+ blocks default profile) | Auth flows only |

Before You Start

Ask the user (or infer from the repo) and confirm:

1. Framework — Next.js 16+ / Next.js 15 / plain React / Vite / other. Only install next-devtools-mcp for Next.js 16+.
2. Auth — Does the perf scenario require logging in? If yes, do step 5.
3. Scope — User-level (--scope user, every project inherits) or project-level (--scope project, only this repo). Default to user for the core tools.

Never install speculatively. Each MCP costs ~13–18k tokens of tool definitions per session; a minimal stack is the right default.

Step 1 — Install the Anchor: chrome-devtools-mcp

claude mcp add chrome-devtools --scope user -- npx chrome-devtools-mcp@latest

Privacy-sensitive or offline contexts:

claude mcp add chrome-devtools --scope user -- npx chrome-devtools-mcp@latest --no-performance-crux --no-usage-statistics

WSL: Chrome must be installed inside the Linux distro, not via the Windows host. Check with which google-chrome.

Step 2 — Install the Chrome DevTools Skills Plugin

These are the curated skills Google ships alongside the MCP. They encode the capture→analyze loop and counter the documented failure mode where models hallucinate non-existent Performance-API calls (chrome-devtools-mcp#1114).

/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
/plugin install chrome-devtools-mcp@chrome-devtools-mcp

This brings in at minimum: chrome-devtools-cli, debug-optimize-lcp, and the accessibility debug skill.

Step 3 — Framework-Specific MCP (Next.js 16+ Only)

Bridges the /_next/mcp dev-server endpoint for route/Suspense/compile-error introspection.

claude mcp add next-devtools --scope user -- npx -y next-devtools-mcp@latest

Skip this step for non-Next.js projects and for Next.js 15 or earlier.

Step 4 — Optional Lab Tooling

Lighthouse MCP (batch scoring, regression diffs, reusable prompts) — skip unless the user explicitly needs batch Lighthouse runs. chrome-devtools-mcp already exposes lighthouse_audit for one-off runs.

claude mcp add lighthouse --scope user -- npx @danielsogl/lighthouse-mcp@latest

react-scan as a dev dependency for in-browser render inspection:

npm install --save-dev react-scan

Optional convenience script for package.json:

"scripts": {
  "scan": "react-scan http://localhost:3000"
}

Do not install: @million/lint (deprecated on npm), why-did-you-render for new projects (maintenance-only since Jan 2025), any community "react-scan MCP" (none is officially supported; the one on LobeHub is an unrelated static analyzer).

Step 5 — Dedicated Chrome Debug Profile (Auth Flows Only)

Chrome 136+ blocks remote debugging against the default profile. For any authenticated page, launch a dedicated profile:

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chrome-debug"

Log in once in this profile (cookies persist across sessions), then reconfigure the MCP to attach to the running instance:

claude mcp remove chrome-devtools
claude mcp add chrome-devtools --scope user -- \
  npx chrome-devtools-mcp@latest \
  --browserUrl http://localhost:9222 \
  --user-data-dir "$HOME/.chrome-debug"

Step 6 — Smoke-Test the Install

Ask the agent to record a trace against a known URL:

Record a reload trace of https://example.com with Slow 4G + 4× CPU. Call performance_analyze_insight for LCPBreakdown. Report the LCP element and the dominant subpart.

Success signals:

• Agent calls performance_start_trace with emulation params, not freeform evaluate_script.
• Agent calls performance_analyze_insight with a valid insight name from the fixed list of 18.
• Agent receives a compact summary, not raw trace JSON.

Failure signals (reinstall steps 1–2):

• Agent invents performance.getEntriesByType("largest-contentful-paint-v2") or similar non-existent APIs.
• Agent dumps raw trace JSON into the response.
• performance_analyze_insight is not available as a tool.

Once the smoke test passes, hand off to the investigate-web-perf skill for real work.

Troubleshooting

• chrome-devtools-mcp process leak on Codex CLI — Open issue openai/codex#17574. Long sessions leak helper processes consuming tens of GB of swap. Run pkill -f chrome-devtools-mcp between sessions until patched.
• Context pollution — Each screenshot is ~2k tokens; verbose tool outputs degrade instruction-following past ~60% context. Use /clear between unrelated perf investigations, delegate trace triage to subagents, prefer snapshots over screenshots.
• Non-deterministic numbers — LCP/INP vary ±15–30% from CPU thermal state and GC. This is a property of the metric, not a setup issue. The investigate-web-perf skill handles this by always pinning emulation and running N=3.
• Authenticated page times out — You skipped step 5. Default profile debugging is blocked since Chrome 136.
• Agent hallucinates Perf-API methods — You skipped step 2. The curated skills exist specifically for this failure mode.

Community Skills Security Caveat

Snyk's ToxicSkills study found ~13% of community "awesome-skill" packages had critical security issues, some exfiltrating credentials. Review every SKILL.md and bundled script before installing community skills. Safe base: Anthropic's own skills/ repo, addyosmani/web-quality-skills, and skills bundled with ChromeDevTools/chrome-devtools-mcp.