@0x1f320.sh/why-did-you-render-mcp 2.0.0 → 2.0.1-dev.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +272 -0
- package/package.json +4 -2
package/README.md
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
# why-did-you-render-mcp
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@0x1f320.sh/why-did-you-render-mcp)
|
|
4
|
+
[](https://www.npmjs.com/package/@0x1f320.sh/why-did-you-render-mcp-client)
|
|
5
|
+
[](https://github.com/0x1f320/why-did-you-render-mcp/actions/workflows/ci.yml)
|
|
6
|
+
[](https://www.npmjs.com/package/@0x1f320.sh/why-did-you-render-mcp)
|
|
7
|
+
|
|
8
|
+
An [MCP](https://modelcontextprotocol.io/) server that bridges [why-did-you-render](https://github.com/welldone-software/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.
|
|
9
|
+
|
|
10
|
+
## How It Works
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
Browser (React app)
|
|
14
|
+
│
|
|
15
|
+
│ why-did-you-render detects unnecessary re-render
|
|
16
|
+
│
|
|
17
|
+
▼
|
|
18
|
+
Client (runs in browser) ── WebSocket ──▶ MCP Server (Node.js)
|
|
19
|
+
│
|
|
20
|
+
├─ Persists to ~/.wdyr-mcp/renders/
|
|
21
|
+
│
|
|
22
|
+
▼
|
|
23
|
+
Coding Agent (Claude, etc.)
|
|
24
|
+
queries via MCP tools
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
## Packages
|
|
30
|
+
|
|
31
|
+
This project is a monorepo with two published packages:
|
|
32
|
+
|
|
33
|
+
| Package | npm | Description |
|
|
34
|
+
| --- | --- | --- |
|
|
35
|
+
| `@0x1f320.sh/why-did-you-render-mcp` | [](https://www.npmjs.com/package/@0x1f320.sh/why-did-you-render-mcp) | MCP server (Node.js) — exposes render data as MCP tools |
|
|
36
|
+
| `@0x1f320.sh/why-did-you-render-mcp-client` | [](https://www.npmjs.com/package/@0x1f320.sh/why-did-you-render-mcp-client) | Browser client — captures re-render data and sends it to the server |
|
|
37
|
+
|
|
38
|
+
The client can be installed independently without pulling in server dependencies (MCP SDK, socket.io server, etc.).
|
|
39
|
+
|
|
40
|
+
## Installation
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
# In your React project (client only — no server deps)
|
|
44
|
+
npm install @0x1f320.sh/why-did-you-render-mcp-client@latest @welldone-software/why-did-you-render
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Setup
|
|
48
|
+
|
|
49
|
+
### 1. Configure why-did-you-render with the client
|
|
50
|
+
|
|
51
|
+
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:
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
import React from "react";
|
|
55
|
+
import whyDidYouRender from "@welldone-software/why-did-you-render";
|
|
56
|
+
import { buildOptions } from "@0x1f320.sh/why-did-you-render-mcp-client";
|
|
57
|
+
|
|
58
|
+
if (process.env.NODE_ENV === "development") {
|
|
59
|
+
whyDidYouRender(React, {
|
|
60
|
+
...buildOptions(),
|
|
61
|
+
trackAllPureComponents: true,
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The client automatically uses `location.origin` as the project identifier and connects to `ws://localhost:4649` by default. You can customize both:
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
const { notifier } = buildOptions({
|
|
70
|
+
wsUrl: "ws://localhost:5555",
|
|
71
|
+
projectId: "my-app",
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### 2. Add the MCP server to your agent
|
|
76
|
+
|
|
77
|
+
<details>
|
|
78
|
+
<summary>Claude Code</summary>
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
claude mcp add why-did-you-render -- npx -y @0x1f320.sh/why-did-you-render-mcp@latest
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
</details>
|
|
85
|
+
|
|
86
|
+
<details>
|
|
87
|
+
<summary>Claude Desktop</summary>
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
claude mcp add-json why-did-you-render '{"command":"npx","args":["-y","@0x1f320.sh/why-did-you-render-mcp@latest"]}' -s user
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Or manually edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"mcpServers": {
|
|
98
|
+
"why-did-you-render": {
|
|
99
|
+
"command": "npx",
|
|
100
|
+
"args": ["-y", "@0x1f320.sh/why-did-you-render-mcp@latest"]
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
</details>
|
|
107
|
+
|
|
108
|
+
<details>
|
|
109
|
+
<summary>Cursor</summary>
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
cursor --add-mcp '{"name":"why-did-you-render","command":"npx","args":["-y","@0x1f320.sh/why-did-you-render-mcp@latest"]}'
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Or add to `.cursor/mcp.json` in your project:
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{
|
|
119
|
+
"mcpServers": {
|
|
120
|
+
"why-did-you-render": {
|
|
121
|
+
"command": "npx",
|
|
122
|
+
"args": ["-y", "@0x1f320.sh/why-did-you-render-mcp@latest"]
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
</details>
|
|
129
|
+
|
|
130
|
+
<details>
|
|
131
|
+
<summary>Windsurf</summary>
|
|
132
|
+
|
|
133
|
+
Add to `~/.codeium/windsurf/mcp_config.json`:
|
|
134
|
+
|
|
135
|
+
```json
|
|
136
|
+
{
|
|
137
|
+
"mcpServers": {
|
|
138
|
+
"why-did-you-render": {
|
|
139
|
+
"command": "npx",
|
|
140
|
+
"args": ["-y", "@0x1f320.sh/why-did-you-render-mcp@latest"]
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
</details>
|
|
147
|
+
|
|
148
|
+
<details>
|
|
149
|
+
<summary>VS Code (GitHub Copilot)</summary>
|
|
150
|
+
|
|
151
|
+
```sh
|
|
152
|
+
code --add-mcp '{"name":"why-did-you-render","command":"npx","args":["-y","@0x1f320.sh/why-did-you-render-mcp@latest"]}'
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Or add to `.vscode/mcp.json` in your project:
|
|
156
|
+
|
|
157
|
+
```json
|
|
158
|
+
{
|
|
159
|
+
"servers": {
|
|
160
|
+
"why-did-you-render": {
|
|
161
|
+
"command": "npx",
|
|
162
|
+
"args": ["-y", "@0x1f320.sh/why-did-you-render-mcp@latest"]
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
</details>
|
|
169
|
+
|
|
170
|
+
### 3. Start your dev server and interact with the app
|
|
171
|
+
|
|
172
|
+
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.
|
|
173
|
+
|
|
174
|
+
## MCP Tools
|
|
175
|
+
|
|
176
|
+
| Tool | Description |
|
|
177
|
+
| --- | --- |
|
|
178
|
+
| `get_renders` | Returns all captured unnecessary re-renders, including stack traces. Optionally filter by `component` name. |
|
|
179
|
+
| `get_render_summary` | Returns a summary of re-renders grouped by component with counts and durations. |
|
|
180
|
+
| `get_commits` | Lists React commit IDs that have recorded render data. Use these IDs with `get_renders_by_commit`. |
|
|
181
|
+
| `get_renders_by_commit` | Returns all unnecessary re-renders for a specific React commit ID, including stack traces. |
|
|
182
|
+
| `get_tracked_components` | Lists components currently tracked by why-did-you-render. |
|
|
183
|
+
| `get_projects` | Lists all active projects (identified by their origin URL). |
|
|
184
|
+
| `save_snapshot` | Saves the current render summary as a named snapshot for later comparison. |
|
|
185
|
+
| `list_snapshots` | Lists all saved render snapshots with their timestamps. |
|
|
186
|
+
| `compare_snapshots` | Compares two saved render snapshots and shows per-component render count changes. |
|
|
187
|
+
| `delete_snapshot` | Deletes a saved render snapshot by name. |
|
|
188
|
+
| `wait_for_renders` | Waits for new renders after code changes (e.g. HMR), with configurable timeout. |
|
|
189
|
+
| `clear_renders` | Clears all stored render data. Optionally scope to a specific project. |
|
|
190
|
+
| `pause_renders` | Pauses render data collection in the browser. Clients stop reporting until resumed. |
|
|
191
|
+
| `resume_renders` | Resumes render data collection previously paused with `pause_renders`. |
|
|
192
|
+
|
|
193
|
+
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.
|
|
194
|
+
|
|
195
|
+
### Stack traces
|
|
196
|
+
|
|
197
|
+
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.
|
|
198
|
+
|
|
199
|
+
Each frame has the following structure:
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
{
|
|
203
|
+
type: "hook" | "component", // "hook" for names starting with `use`, otherwise "component"
|
|
204
|
+
name: string, // e.g. "useFilter", "Dashboard"
|
|
205
|
+
location: {
|
|
206
|
+
path: string, // source file path (source-mapped when available)
|
|
207
|
+
line: number, // line number in the source file
|
|
208
|
+
},
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
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.
|
|
213
|
+
|
|
214
|
+
### Snapshots
|
|
215
|
+
|
|
216
|
+
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:
|
|
217
|
+
|
|
218
|
+
1. Call `save_snapshot` with a name (e.g. `"before-fix"`)
|
|
219
|
+
2. Make code changes and interact with the app
|
|
220
|
+
3. Call `save_snapshot` with another name (e.g. `"after-fix"`)
|
|
221
|
+
4. Call `compare_snapshots` to see per-component render count changes
|
|
222
|
+
|
|
223
|
+
Snapshots are stored as JSON files in `~/.wdyr-mcp/snapshots/`.
|
|
224
|
+
|
|
225
|
+
### HMR-aware waiting
|
|
226
|
+
|
|
227
|
+
`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:
|
|
228
|
+
|
|
229
|
+
1. Agent edits code
|
|
230
|
+
2. Agent calls `wait_for_renders` (with optional timeout)
|
|
231
|
+
3. Tool waits for HMR to complete and new renders to arrive
|
|
232
|
+
4. Returns the new render data for analysis
|
|
233
|
+
|
|
234
|
+
### Commit-level grouping
|
|
235
|
+
|
|
236
|
+
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:
|
|
237
|
+
|
|
238
|
+
1. Call `get_commits` to list available commit IDs
|
|
239
|
+
2. Call `get_renders_by_commit` with a specific ID to see all renders in that commit
|
|
240
|
+
|
|
241
|
+
## Architecture
|
|
242
|
+
|
|
243
|
+
```
|
|
244
|
+
Browser (project-a) ──┐
|
|
245
|
+
Browser (project-b) ──┤
|
|
246
|
+
▼
|
|
247
|
+
MCP #1 → WS(:4649) (first instance binds, "owner")
|
|
248
|
+
MCP #2 → WS(:4649) → relay client ──▶ MCP #1
|
|
249
|
+
│
|
|
250
|
+
▼
|
|
251
|
+
~/.wdyr-mcp/
|
|
252
|
+
├─ renders/ (JSONL files, shared across instances)
|
|
253
|
+
│ ├─ http___localhost_3000.jsonl
|
|
254
|
+
│ └─ http___localhost_5173.jsonl
|
|
255
|
+
└─ snapshots/ (JSON files, named snapshots)
|
|
256
|
+
└─ before-fix.json
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
- **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.
|
|
260
|
+
- **Multi-project support** — Each project is identified by `location.origin`. Render data is stored in per-project JSONL files.
|
|
261
|
+
- **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.
|
|
262
|
+
- **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.
|
|
263
|
+
|
|
264
|
+
## Configuration
|
|
265
|
+
|
|
266
|
+
| Environment Variable | Default | Description |
|
|
267
|
+
| --- | --- | --- |
|
|
268
|
+
| `WDYR_WS_PORT` | `4649` | WebSocket server port |
|
|
269
|
+
|
|
270
|
+
## License
|
|
271
|
+
|
|
272
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@0x1f320.sh/why-did-you-render-mcp",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.1-dev.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "MCP server that receives why-did-you-render reports from the browser and exposes them as tools for AI coding agents to diagnose React performance issues",
|
|
6
6
|
"license": "MIT",
|
|
@@ -44,12 +44,14 @@
|
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
46
|
"@modelcontextprotocol/sdk": "^1.12.1",
|
|
47
|
-
"@why-did-you-render-mcp/types": "workspace:*",
|
|
48
47
|
"socket.io": "^4.8.3",
|
|
49
48
|
"socket.io-client": "^4.8.3",
|
|
50
49
|
"xxhash-wasm": "^1.1.0",
|
|
51
50
|
"zod": "^3.24.4"
|
|
52
51
|
},
|
|
52
|
+
"devDependencies": {
|
|
53
|
+
"@why-did-you-render-mcp/types": "workspace:*"
|
|
54
|
+
},
|
|
53
55
|
"publishConfig": {
|
|
54
56
|
"access": "public"
|
|
55
57
|
}
|