{
  "markdown": "# perfonext-render-mcp\n\n> Analyze React render behavior in Next.js apps and apply fixes in the editor.\n\n[![npm](https://img.shields.io/npm/v/@perfonext/render-mcp)](https://www.npmjs.com/package/@perfonext/render-mcp)\n[![npm downloads](https://img.shields.io/npm/dt/@perfonext/render-mcp)](https://www.npmjs.com/package/@perfonext/render-mcp)\n[![license](https://img.shields.io/npm/l/@perfonext/render-mcp)](https://www.npmjs.com/package/@perfonext/render-mcp)\n\n`perfonext-render-mcp` is a Model Context Protocol (MCP) server that gives GitHub Copilot, Claude Desktop,\nClaude Code, and other MCP clients structured, machine-readable React render analysis for Next.js performance\nwork. It turns live capture sessions and React DevTools Profiler exports into component costs, exact rerender\ncauses, and regression diffs — evidence an MCP client can act on directly.\n\n## Quick Start\n\n`perfonext-render-mcp` is a standard MCP stdio server, so it works with any MCP-compatible client\n(GitHub Copilot in VS Code, Claude Desktop, Claude Code, Cursor, and others). Run it directly with `npx`:\n\n```bash\nnpx -y @perfonext/render-mcp\n```\n\nOr install globally:\n\n```bash\nnpm install -g @perfonext/render-mcp\n```\n\nThe executable command remains `perfonext-render-mcp` after installation.\n\n### VS Code\n\nAdd the server to `.vscode/mcp.json` (the workspace MCP configuration file):\n\n```json\n{\n  \"servers\": {\n    \"perfonext-render\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@perfonext/render-mcp\"]\n    }\n  }\n}\n```\n\nReload the VS Code window and run **MCP: List Servers** to start it, or accept the trust prompt when it appears.\n\n### Claude Desktop\n\nAdd the server to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"perfonext-render\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@perfonext/render-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop to pick up the new server.\n\n### Claude Code\n\nAdd the server with the CLI:\n\n```bash\nclaude mcp add perfonext-render -- npx -y @perfonext/render-mcp\n```\n\nOr add the same `mcpServers` entry to `.mcp.json`.\n\n### Other MCP clients\n\nAny client that supports stdio MCP servers can launch `npx -y @perfonext/render-mcp`. Consult your\nclient's documentation for its MCP server configuration format.\n\nFor a locally-built checkout, point `command`/`args` at `node` and the repo's `dist/index.js` instead.\n\n## Troubleshooting\n\n### `spawn npx ENOENT` / `spawn node ENOENT` on macOS with nvm\n\nIf the server fails to start with this error, your GUI MCP client likely cannot see nvm. GUI apps on\nmacOS do not load shell config (`.zshrc`/`.bashrc`), so nvm-installed `npx`/`node` are not on `PATH`.\nUse an absolute `npx` path and include the same Node directory in `PATH`:\n\n```json\n{\n  \"servers\": {\n    \"perfonext-render\": {\n      \"type\": \"stdio\",\n      \"command\": \"/Users/YOU/.nvm/versions/node/v<version>/bin/npx\",\n      \"args\": [\"-y\", \"@perfonext/render-mcp\"],\n      \"env\": {\n        \"PATH\": \"/Users/YOU/.nvm/versions/node/v<version>/bin:/usr/bin:/bin\"\n      }\n    }\n  }\n}\n```\n\nMerge these fields into your client's server entry, under `servers` for VS Code or `mcpServers` for\nClaude Desktop/Code. Then ask your assistant: _\"Run a render analysis on my app.\"_\n\n## What It Does\n\n`perfonext-render-mcp` is the **agent companion** to React DevTools Profiler and `react-scan` — best at\nmachine-readable summaries, exact rerender-cause attribution, source-aware follow-up, and diffing. The loop is\n**collect → analyze → fix**, all locally:\n\n- **collect** — choose live capture (react-scan/lite streams events in real time) or manual DevTools export\n- **analyze** — the MCP returns structured, machine-readable evidence: component costs, rerender causes, commit breakdowns, and regressions\n- **fix** — your MCP client uses that evidence to propose and apply concrete code changes\n\n> **Note:** while a live capture session is active, React DevTools Timeline Profiler will not receive events\n> (react-scan/lite takes over the profiling channel). Calling `stop_render_capture` restores it.\n\nCapabilities:\n\n- **live capture** — streams per-commit fiber events from a running React app directly into the MCP over a local HTTP endpoint; no manual export required\n- **manual export** — loads exported React DevTools Profiler JSON files as an alternative input path\n- summarizes commits, the most expensive components, and detected render issues in one call\n- ranks the hottest commits and shows the top components inside each spike\n- identifies the slowest components by total render cost\n- highlights components with repeated rerenders, reporting the **exact** changed props/state/hooks when live\n  capture provides `changeDescription` data, and falling back to deterministic heuristics otherwise\n- annotates ranked components with their source file and line when available\n- filters DOM host elements (`div`, `span`, …) and unnamed components out of ranked output so findings stay actionable\n- compares two render profiles to surface regressions and improvements\n- keeps profiles in memory so an MCP client can iterate without re-loading\n\n## Tools\n\n### Entry point\n\n| Tool                    | Description                                                                                                                                                                                    |\n| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `begin_render_analysis` | Entry point. Accepts `approach: \"live\" \\| \"manual\"`. For `live`: starts a capture session and returns the instrumentation snippet. For `manual`: returns React DevTools Profiler export steps. |\n\n### Live capture\n\n| Tool                   | Description                                                                                                                                                         |\n| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `run_render_capture`   | Called after instrumentation is wired up. Accepts `method: \"manual-interaction\" \\| \"test-suite\"`. Returns focused instructions for whichever method the user picks. |\n| `stop_render_capture`  | Stop the session, finalize buffered events into a profile, and return a `profileId` plus `dataQuality` (`exact` \\| `heuristic`) for analysis                        |\n| `get_captured_renders` | Optional diagnostic: peek at session progress without stopping (commit count, unknown events). Only call if something seems wrong.                                  |\n\n### Analysis\n\n| Tool                  | Description                                                                                                                                                                                          |\n| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `load_render_profile` | Parse and load an exported React DevTools Profiler JSON file from disk (manual path entry point)                                                                                                     |\n| `get_render_summary`  | Summarize a loaded profile: top components by render cost, hottest commits, and detected render issues                                                                                               |\n| `get_hot_commits`     | Rank the most expensive commits and show the top components inside each spike                                                                                                                        |\n| `get_slow_components` | Rank the slowest components by total actual render time                                                                                                                                              |\n| `get_rerender_causes` | Explain rerender causes with evidence, confidence, and a risk score. Reports exact changed props/state/hooks when `changeDescription` data is present (`dataQuality: \"exact\"`), heuristics otherwise |\n| `compare_renders`     | Diff two loaded render profiles and rank regressions, improvements, additions, and removals                                                                                                          |\n\n## Usage Walkthrough\n\nAsk your assistant: _\"Run a render analysis on my app.\"_\n\nYour MCP client calls `begin_render_analysis` and asks you to choose:\n\n**Option A — Live capture (recommended)**\n\nYour MCP client will:\n\n1. Start a capture session (ingest server on `127.0.0.1:7721`)\n2. Install `react-scan` as a devDependency if not present\n3. Write `instrumentation-client.js` at your project root with the session snippet\n4. Import it from your app's client-side entry point\n5. Ask whether you want to interact manually or run a test suite (`run_render_capture`)\n6. Stop the session and run analysis\n\n> Running a test suite? Use `npx playwright test` as usual. `react-scan/lite` installs\n> `__REACT_DEVTOOLS_GLOBAL_HOOK__` itself, so a visible window and the React DevTools extension are not\n> required. The run still yields `changeDescription` data and `dataQuality: \"exact\"`.\n\n> **Two preconditions commonly cause a silent `commitCount: 0`:**\n>\n> - **Build flavor.** A plain `next build`/`next start` compiles out React's profiling hooks entirely.\n>   Choose one of:\n>   - `next dev` — real component names, but dev-mode overhead means render timings and proportions\n>     may not match what real users experience in production.\n>   - `next build --profile` then `next start` — production-accurate timings, but component names get\n>     minified to 1-2 letters (e.g. `\"V\"`) by production minification, regardless of the profiling flag.\n>     `get_render_summary` surfaces a warning when this is detected.\n> - **Instrumentation timing.** `instrument()` must run before React initializes — a static top-level import\n>   (as shown in the generated snippet) works; mounting it as a React component, or calling it inside a\n>   `useEffect`, runs too late and silently captures nothing.\n\nThe ingest server runs on a **fixed port (7721)**. Only the `sessionId` line in `instrumentation-client.js` changes between sessions — the file does not need to be re-wired each time.\n\n**Option B — Manual DevTools export**\n\n1. Open React DevTools in the browser → Profiler tab → Record\n2. Interact with the app\n3. Export the JSON and share the file path\n4. Your MCP client calls `load_render_profile({ filePath: \"...\" })`\n\n## Example Prompts\n\n- \"Run a render analysis on my app.\"\n- \"Stop the capture and show me the slowest components.\"\n- \"Which components are re-rendering the most and why?\"\n- \"Compare this run to the profile I captured before the refactor.\"\n- \"I already have a React DevTools export — load it and tell me what's slow.\"\n- \"Show me the hottest commits and which components dominated each spike.\"\n\n## Related Perfonext Tools\n\n- [perfonext-profiler-mcp](https://github.com/souvikdu/perfonext-profiler-mcp) — CPU profiling (V8/Chrome) for Next.js servers\n- [perfonext-build-mcp](https://github.com/souvikdu/perfonext-build-mcp) — Next.js bundle/build analysis\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nSample fixtures live under `tests/fixtures/`.\n\n## License\n\nMIT\n",
  "bytes": 11564,
  "sha": "13d139b42668e9d52eb7f4b0b5d69938e9b8294579acfe1440bbe69527acbce9",
  "repo_slug": "souvikdu/perfonext-render-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_souvikdu_perfonext_render_mcp_77ec2360/readme"
}