why-did-you-render-mcp

An MCP server that bridges why-did-you-render data from the browser to coding agents. It captures unnecessary React re-render reports in real time and exposes them as MCP tools, so agents can diagnose and fix performance issues without manual browser inspection.

How It Works

Browser (React app)
  │
  │  why-did-you-render detects unnecessary re-render
  │
  ▼
Client (runs in browser)  ── WebSocket ──▶  MCP Server (Node.js)
                                                │
                                                ├─ Persists to ~/.wdyr-mcp/renders/
                                                │
                                                ▼
                                          Coding Agent (Claude, etc.)
                                          queries via MCP tools

The client runs inside your React app alongside why-did-you-render. Whenever an unnecessary re-render is detected, it sanitizes the render data and sends it over WebSocket to the MCP server. The server stores reports as JSONL files and exposes them through MCP tools that coding agents can query.

Packages

This project is a monorepo with two published packages:

Package	npm	Description
@0x1f320.sh/why-did-you-render-mcp		MCP server (Node.js) — exposes render data as MCP tools
@0x1f320.sh/why-did-you-render-mcp-client		Browser client — captures re-render data and sends it to the server

The client can be installed independently without pulling in server dependencies (MCP SDK, socket.io server, etc.).

Installation

# In your React project (client only — no server deps)
npm install @0x1f320.sh/why-did-you-render-mcp-client@latest @welldone-software/why-did-you-render

Setup

1. Configure why-did-you-render with the client

In your app's entry point (e.g. src/main.tsx or src/index.tsx), set up why-did-you-render with the MCP client as its notifier:

import React from "react";
import whyDidYouRender from "@welldone-software/why-did-you-render";
import { buildOptions } from "@0x1f320.sh/why-did-you-render-mcp-client";

if (process.env.NODE_ENV === "development") {
  whyDidYouRender(React, {
    ...buildOptions(),
    trackAllPureComponents: true,
  });
}

The client automatically uses location.origin as the project identifier and connects to ws://localhost:4649 by default. You can customize both:

const { notifier } = buildOptions({
  wsUrl: "ws://localhost:5555",
  projectId: "my-app",
});

2. Add the MCP server to your agent

<details> <summary>Claude Code</summary>

claude mcp add why-did-you-render -- npx -y @0x1f320.sh/why-did-you-render-mcp@latest

</details>

<details> <summary>Claude Desktop</summary>

claude mcp add-json why-did-you-render '{"command":"npx","args":["-y","@0x1f320.sh/why-did-you-render-mcp@latest"]}' -s user

Or manually edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "why-did-you-render": {
      "command": "npx",
      "args": ["-y", "@0x1f320.sh/why-did-you-render-mcp@latest"]
    }
  }
}

</details>

<details> <summary>Cursor</summary>

cursor --add-mcp '{"name":"why-did-you-render","command":"npx","args":["-y","@0x1f320.sh/why-did-you-render-mcp@latest"]}'

Or add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "why-did-you-render": {
      "command": "npx",
      "args": ["-y", "@0x1f320.sh/why-did-you-render-mcp@latest"]
    }
  }
}

</details>

<details> <summary>Windsurf</summary>

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "why-did-you-render": {
      "command": "npx",
      "args": ["-y", "@0x1f320.sh/why-did-you-render-mcp@latest"]
    }
  }
}

</details>

<details> <summary>VS Code (GitHub Copilot)</summary>

code --add-mcp '{"name":"why-did-you-render","command":"npx","args":["-y","@0x1f320.sh/why-did-you-render-mcp@latest"]}'

Or add to .vscode/mcp.json in your project:

{
  "servers": {
    "why-did-you-render": {
      "command": "npx",
      "args": ["-y", "@0x1f320.sh/why-did-you-render-mcp@latest"]
    }
  }
}

</details>

3. Start your dev server and interact with the app

Once both the MCP server and your React dev server are running, interact with your app in the browser. The agent can now query re-render data using the MCP tools below.

MCP Tools

Tool	Description
get_renders	Returns all captured unnecessary re-renders, including stack traces. Optionally filter by component name.
get_render_summary	Returns a summary of re-renders grouped by component with counts and durations.
get_commits	Lists React commit IDs that have recorded render data. Use these IDs with get_renders_by_commit.
get_renders_by_commit	Returns all unnecessary re-renders for a specific React commit ID, including stack traces.
get_tracked_components	Lists components currently tracked by why-did-you-render.
get_projects	Lists all active projects (identified by their origin URL).
save_snapshot	Saves the current render summary as a named snapshot for later comparison.
list_snapshots	Lists all saved render snapshots with their timestamps.
compare_snapshots	Compares two saved render snapshots and shows per-component render count changes.
delete_snapshot	Deletes a saved render snapshot by name.
wait_for_renders	Waits for new renders after code changes (e.g. HMR), with configurable timeout.
clear_renders	Clears all stored render data. Optionally scope to a specific project.
pause_renders	Pauses render data collection in the browser. Clients stop reporting until resumed.
resume_renders	Resumes render data collection previously paused with pause_renders.

When multiple projects are active, tools accept an optional project parameter (the browser's origin URL, e.g. http://localhost:3000). If omitted and only one project exists, it is auto-selected.

Stack traces

Each render report includes a stackFrames array that traces the hook chain and component tree that triggered the re-render. The client captures a stack trace on every render update, parses it with error-stack-parser, filters out React/WDYR internals, and resolves bundled locations back to original source files via source maps.

Each frame has the following structure:

{
  type: "hook" | "component",  // "hook" for names starting with `use`, otherwise "component"
  name: string,                // e.g. "useFilter", "Dashboard"
  location: {
    path: string,              // source file path (source-mapped when available)
    line: number,              // line number in the source file
  },
}

Agents can use stackFrames to pinpoint the exact source location of each unnecessary re-render — navigating directly to the file and line that caused it, without requiring manual browser inspection.

Snapshots

Snapshots let agents capture the current render summary at a point in time and compare it against a later state. This is useful for measuring whether a code change actually reduced unnecessary re-renders:

1. Call save_snapshot with a name (e.g. "before-fix")
2. Make code changes and interact with the app
3. Call save_snapshot with another name (e.g. "after-fix")
4. Call compare_snapshots to see per-component render count changes

Snapshots are stored as JSON files in ~/.wdyr-mcp/snapshots/.

HMR-aware waiting

wait_for_renders lets agents wait for new renders after a code change. It detects HMR (Hot Module Replacement) events from both Vite and webpack, so it knows when the browser has applied the update. This enables a workflow like:

1. Agent edits code
2. Agent calls wait_for_renders (with optional timeout)
3. Tool waits for HMR to complete and new renders to arrive
4. Returns the new render data for analysis

Commit-level grouping

Each render report is tagged with a React commit ID, allowing agents to inspect which components re-rendered together in the same commit. The client tracks commits by hooking into __REACT_DEVTOOLS_GLOBAL_HOOK__.onCommitFiberRoot, which React calls synchronously once per commit. A typical workflow:

1. Call get_commits to list available commit IDs
2. Call get_renders_by_commit with a specific ID to see all renders in that commit

Architecture

Browser (project-a) ──┐
Browser (project-b) ──┤
                      ▼
                MCP #1 → WS(:4649)  (first instance binds, "owner")
                MCP #2 → WS(:4649)  → relay client ──▶ MCP #1
                      │
                      ▼
               ~/.wdyr-mcp/
               ├─ renders/  (JSONL files, shared across instances)
               │  ├─ http___localhost_3000.jsonl
               │  └─ http___localhost_5173.jsonl
               └─ snapshots/  (JSON files, named snapshots)
                  └─ before-fix.json

• Multiple MCP instances can run simultaneously. Only the first instance (the "owner") starts the WebSocket server; others connect as socket.io clients to relay commands (e.g. pause/resume) to the owner. All instances share the same data directories.
• Multi-project support — Each project is identified by location.origin. Render data is stored in per-project JSONL files.
• No daemon required — Each MCP instance is independent. The WebSocket server is opportunistically claimed by whichever instance starts first. Commands requiring WS access are relayed to the owner.
• Value dictionary deduplication — Render reports often repeat the same prevValue/nextValue objects across thousands of entries. Each JSONL file stores a content-addressed dictionary on its first line, mapping xxhash-wasm hashes to unique values. Render lines reference them via @@ref:<hash> sentinels instead of inlining the full object, dramatically reducing file size. Reads hydrate refs transparently.

Configuration

Environment Variable	Default	Description
WDYR_WS_PORT	4649	WebSocket server port

License

MIT