react-render-profile-mcp

react-render-profile-mcp

面向 React 的自主性能 SRE 与自动修复引擎，以模型上下文协议（MCP）服务的形式提供。专为弥合 AI 编码 Agent（Claude、Cursor、Copilot）的性能感知差距而构建。

---

👁️ 盲点：为什么 AI Agent 会破坏 React 生产环境

当 AI Agent 重构 Context Provider、更改状态架构或接入全局存储时，它对运行时性能影响完全没有感知。

Agent 可以成功通过单元测试并编译代码，同时引入灾难性的性能回退：

• 一次状态更新级联触发 80 次不必要的子组件重新渲染。
• 不稳定的 Zustand/Redux 选择器引用触发无限渲染循环。
• Hydration 不匹配迫使 React 丢弃服务端渲染的 HTML，并从头开始挂载。
• 不稳定的 key 属性导致组件在每个渲染周期中都卸载并重新挂载（生命周期异常）。

react-render-profile-mcp 为 AI Agent 提供一只“第三只眼”，以动态测量、可视化并自动修复这些性能瓶颈。

---

⚡ AI-SRE 的四大支柱

此服务不会输出原始 JSON 转储，而是将性能数据整理为结构化、可执行的洞察，涵盖四大核心工程支柱：

🧠 1. AST 自动修复引擎（ts-morph）

当发现瓶颈时，Agent 无需手动重写代码。服务可以直接修改磁盘上的组件源代码：

• 提升（Hoisting）：将对象和数组字面量静态提升到渲染函数体之外。
• 动态记忆化：将不稳定的函数和变量包装在 useCallback 和 useMemo 中，并计算依赖数组。
• ROI 包装：仅当分析得出的自身耗时和无效渲染次数证明比较开销合理时，才将组件包装在 React.memo 中（ROI > 1.5）。
• 规则审计：扫描代码以防止编译器回退（检测 Date.now()、Math.random() 或渲染阶段的 useRef 修改）。

📊 2. 交互式 SVG 级联可视化工具（MCP 资源）

使用自定义资源 URI 方案 react-profile://commits/{commitId}/cascade?profile_path={profile_path}，直接在 Agent 聊天窗口中生成父子渲染图。

• 触发源使用不同的 HSL 调色板样式，以区分传播渠道：
  • 🔵 Context 触发：蓝色（海浪）
  • 🟠 Zustand/Redux 存储：橙色（订阅者涟漪）
  • 🔴 Props 失效：红色（引用不匹配）
  • 🟢 状态变更：绿色（翡翠色触发源）

🛡️ 3. RSC Flight 流与安全分析器

分析 React Server Components（RSC）Flight 流，以优化交付：

• 识别臃肿的数据块（> 50KB）和串行瀑布流。
• 扫描负载，查找原型遍历漏洞利用，例如 CVE-2025-55182（React2Shell）。

⚛️ 4. 多层跟踪关联器

使用 blink.user_timing 标记，将 React 提交与 Chrome Performance 时间线事件对齐。

• 测量提交后的布局、绘制和样式计算任务，以计算对 Core Web Vitals 的实际影响（CLS / INP 估算值）。

---

🛠️ MCP 工具参考

以下是此服务提供的工具的简要说明。所有工具都必须接收指向 React DevTools 导出 .json 文件的 profile_path。

工具名称	参数	用途 / 输出
get_render_summary	profile_path	提供提交次数、总渲染时间、无效渲染次数和生命周期异常的概览。
find_spurious_renders	profile_path、min_render_count？	列出使用相同 props/state 渲染的组件。将触发原因分类为 UNSTABLE_PARENT_REF 或 CONTEXT_UPDATE。
analyze_compiler_efficacy	profile_path、invalid_threshold？	计算失效指数，用于确定 React Compiler 或 React.memo 被绕过的位置。
diagnose_hydration_and_suspense	profile_path、waterfall_threshold_ms？	检测服务端与客户端的水合不匹配，以及嵌套 Suspense 获取瀑布。
evaluate_external_store_performance	profile_path、max_blocking_task_ms？	查找不稳定的 useSyncExternalStore 选择器和高优先级阻塞同步任务。
trace_state_cascade_footprint	profile_path、commit_index	跟踪虚拟所有者树，以衡量更新的传播深度和消费者数量。
suggest_memoization	profile_path、min_wasted_ms？	根据平均自身耗时（阈值为 > 2ms）提供高 ROI 的 React.memo 建议。
remediate_component	file_path、component_name、unstable_props、roi_score	修改磁盘上的 AST，以提升变量、包装钩子并应用记忆化。
audit_compiler_rules	file_path、component_name	静态审查组件源代码，检查是否违反 React Compiler 规则。
profile_rsc_stream	stream_payload	解析 RSC Flight 日志，审查数据块大小、瀑布和 React2Shell 漏洞。
correlate_chrome_trace	profile_path、trace_path	将 React 提交与 Chrome 跟踪事件对齐，以计算对 CLS/INP 网页性能指标的影响。

---

🤖 提示词注入：教你的 Agent 进行性能分析

要充分利用此服务，请将以下提示词添加到 Agent 的系统指令中（例如 .cursorrules、Cursor System Prompt 或 Claude Custom Instructions）：

You are equipped with `react-render-profile-mcp`. Use it systematically whenever:

1. You make structural changes to React components, global state providers, or store selectors.
2. The user reports lag, slow input response, or UI stuttering.
3. You refactor context providers, Zustand selectors, or Redux dispatches.

Debugging Workflow:

- Ask the user to record and export a React DevTools profile (.json).
- Run `get_render_summary` to understand the scale of the problem and look for `lifecycle_anomaly: true` (unstable keys).
- Run `find_spurious_renders` and `analyze_compiler_efficacy` to pinpoint unstable prop references.
- Call the `react-profile://commits/{commitId}/cascade` resource to visualize cascades.
- Use `remediate_component` to automatically apply AST optimizations (hoisting static variables, wrapping hooks) instead of doing it manually.

---

📋 如何导出性能分析文件

1. 在浏览器中打开 React DevTools。
2. 切换到 Profiler 标签页。
3. 点击 Record 按钮（圆形），与应用交互以触发性能问题，然后点击 Stop。
4. 点击 Save Profile 图标（💾）下载 .json 文件。
5. 将该文件的绝对路径提供给 MCP 服务。

---

⚙️ 设置与安装

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "react-render-profile": {
      "command": "npx",
      "args": ["-y", "react-render-profile-mcp"]
    }
  }
}

Cursor / VS Code / 其他客户端

添加一个类型为 command 的 MCP 服务：

• 命令：npx -y react-render-profile-mcp

---

🔧 幕后实现

• 原生支持 ESM：使用 TypeScript ESM 构建，针对快速导入 Node.js 进行了优化。
• React DevTools v5 协议：原生解码序列化的操作数组，解析 fiber 快照和名称映射。
• Lane 识别：区分高优先级 lane 更新和并发过渡提交（低优先级／空闲），以避免误报回归问题。
• AST 修改安全性：实现 ts-morph 语句操作块，避免多轮重写时常见的解析器状态损坏问题。

---

MCP 工具集的一部分

与以下项目协同开发：

• tailwind-context-resolver-mcp — 解析 Tailwind 设计令牌并验证工具类。
• v8-cpu-profile-decoder-mcp — 解码 V8 CPU 性能分析文件，用于 Node.js 后端性能调优。

---

许可证

MIT