Perfonext Render MCP

perfonext-render-mcp

分析 Next.js 应用中的 React 渲染行为，并在编辑器中应用修复。

perfonext-render-mcp 是一个模型上下文协议（MCP）服务，可为 GitHub Copilot、Claude Desktop、 Claude Code 及其他 MCP 客户端提供结构化、机器可读的 React 渲染分析，助力 Next.js 性能优化。 它会将实时捕获会话和 React DevTools Profiler 导出数据转换为组件开销、精确的重新渲染原因和回归差异—— 这些证据可供 MCP 客户端直接采取行动。

快速开始

perfonext-render-mcp 是标准的 MCP stdio 服务，因此适用于任何兼容 MCP 的客户端 （VS Code 中的 GitHub Copilot、Claude Desktop、Claude Code、Cursor 等）。使用 npx 直接运行：

npx -y @perfonext/render-mcp

或全局安装：

npm install -g @perfonext/render-mcp

安装后，可执行命令仍为 perfonext-render-mcp。

VS Code

将服务添加到 .vscode/mcp.json（工作区 MCP 配置文件）：

{
  "servers": {
    "perfonext-render": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@perfonext/render-mcp"]
    }
  }
}

重新加载 VS Code 窗口，然后运行 MCP: List Servers 启动服务；也可以在出现信任提示时接受。

Claude Desktop

将服务添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "perfonext-render": {
      "command": "npx",
      "args": ["-y", "@perfonext/render-mcp"]
    }
  }
}

重启 Claude Desktop 以加载新服务。

Claude Code

使用 CLI 添加服务：

claude mcp add perfonext-render -- npx -y @perfonext/render-mcp

或者将相同的 mcpServers 条目添加到 .mcp.json。

其他 MCP 客户端

任何支持 stdio MCP 服务的客户端都可以启动 npx -y @perfonext/render-mcp。请查阅客户端文档， 了解其 MCP 服务配置格式。

对于本地构建的检出版本，请将 command/args 指向 node 和仓库的 dist/index.js。

故障排除

在使用 nvm 的 macOS 上出现 spawn npx ENOENT / spawn node ENOENT

如果服务因该错误而无法启动，可能是图形界面 MCP 客户端无法找到 nvm。macOS 上的图形界面应用不会加载 shell 配置文件（.zshrc/.bashrc），因此通过 nvm 安装的 npx/node 不在 PATH 中。 请使用 npx 的绝对路径，并在 PATH 中包含相同的 Node 目录：

{
  "servers": {
    "perfonext-render": {
      "type": "stdio",
      "command": "/Users/YOU/.nvm/versions/node/v<version>/bin/npx",
      "args": ["-y", "@perfonext/render-mcp"],
      "env": {
        "PATH": "/Users/YOU/.nvm/versions/node/v<version>/bin:/usr/bin:/bin"
      }
    }
  }
}

将这些字段合并到客户端的服务条目中：VS Code 放在 servers 下，Claude Desktop/Code 放在 mcpServers 下。然后向助手询问：“对我的应用运行渲染分析。”

功能说明

perfonext-render-mcp 是 React DevTools Profiler 和 react-scan 的Agent 搭档，擅长生成机器可读的摘要、精确归因重渲染原因、基于源码进行后续分析，以及比较差异。整个流程为收集 → 分析 → 修复，且完全在本地进行：

• 收集 — 选择实时捕获（react-scan/lite 实时传输事件）或手动导出 DevTools 数据
• 分析 — MCP 返回结构化、机器可读的证据：组件开销、重渲染原因、提交拆解和回归问题
• 修复 — MCP 客户端利用这些证据提出并应用具体的代码更改

注意： 实时捕获会话处于活动状态时，React DevTools Timeline Profiler 将无法接收事件 （react-scan/lite 会接管性能分析通道）。调用 stop_render_capture 可恢复其功能。

功能：

• 实时捕获 — 通过本地 HTTP 端点，将正在运行的 React 应用中的每次提交的 fiber 事件直接传输到 MCP；无需手动导出
• 手动导出 — 加载导出的 React DevTools Profiler JSON 文件，作为另一种输入方式
• 一次调用即可汇总提交、开销最大的组件和检测到的渲染问题
• 为开销最高的提交排序，并显示每个峰值中的顶级组件
• 根据总渲染开销识别最慢的组件
• 突出显示反复重渲染的组件；实时捕获提供 changeDescription 数据时，会报告发生变化的确切 props/state/hooks，否则使用确定性启发式方法
• 在可用时，为排序后的组件标注其源文件和行号
• 从排序结果中过滤掉 DOM 宿主元素（div、span 等）和未命名组件，让分析结果更具可操作性
• 比较两个渲染性能分析结果，以发现回归和改进
• 将性能分析结果保存在内存中，让 MCP 客户端无需重新加载即可继续操作

工具

入口点

工具	说明
begin_render_analysis	入口点。接受 approach: "live" | "manual"。对于 live：启动捕获会话并返回检测代码片段。对于 manual：返回 React DevTools Profiler 导出步骤。

实时捕获

工具	说明
run_render_capture	接入检测代码后调用。接受 method: "manual-interaction" | "test-suite"。根据用户选择的方法返回针对性的说明。
stop_render_capture	停止会话，将缓冲事件整理成性能分析结果，并返回用于分析的 profileId 和 dataQuality（exact | heuristic）
get_captured_renders	可选诊断：在不停止会话的情况下查看进度（提交数、未知事件）。仅在出现异常时调用。

分析

工具	描述
load_render_profile	从磁盘解析并加载导出的 React DevTools Profiler JSON 文件（手动输入路径的入口）
get_render_summary	总结已加载的性能分析文件：渲染成本最高的组件、耗时最长的提交，以及检测到的渲染问题
get_hot_commits	按开销对提交进行排序，并显示每次性能峰值中的主要组件
get_slow_components	按总实际渲染时间对最慢的组件进行排序
get_rerender_causes	结合证据、置信度和风险评分说明重新渲染的原因。当存在 changeDescription 数据时，报告发生变化的具体 props/state/hooks（dataQuality: "exact"）；否则使用启发式判断
compare_renders	对比两个已加载的渲染性能分析文件，并按回归、改进、新增和移除进行排序

使用流程

向你的助手提问："对我的应用运行渲染分析。"

你的 MCP 客户端会调用 begin_render_analysis，并让你选择：

选项 A — 实时捕获（推荐）

你的 MCP 客户端将：

1. 启动捕获会话（摄取服务器运行于 127.0.0.1:7721）
2. 如果尚未安装，则将 react-scan 安装为 devDependency
3. 在项目根目录写入包含会话代码片段的 instrumentation-client.js
4. 从应用的客户端入口点导入该文件
5. 询问你想手动交互，还是运行测试套件（run_render_capture）
6. 停止会话并运行分析

要运行测试套件？照常使用 npx playwright test。react-scan/lite 会自行安装 __REACT_DEVTOOLS_GLOBAL_HOOK__，因此不需要可见窗口或 React DevTools 扩展。 运行仍会生成 changeDescription 数据，且 dataQuality: "exact"。

以下两个前提条件常会导致静默出现 commitCount: 0：

• 构建类型。 普通的 next build/next start 会完全剔除 React 的性能分析钩子。 请选择以下方式之一：
  • next dev — 组件名称真实，但开发模式的开销意味着渲染耗时和占比可能与真实用户在生产环境中的体验不符。
  • 先运行 next build --profile，再运行 next start — 耗时与生产环境一致，但无论是否启用性能分析标志，生产环境的压缩都会将组件名称缩短为 1 至 2 个字母（例如 "V"）。 检测到此情况时，get_render_summary 会显示警告。
• 插桩时机。 instrument() 必须在 React 初始化之前运行——使用静态顶层导入（如生成的代码片段所示）即可；将其挂载为 React 组件，或在 useEffect 中调用，都会太晚，且不会产生任何捕获结果。

摄取服务器运行在固定端口（7721）。不同会话之间，只有 instrumentation-client.js 中的 sessionId 行会变化——无需每次都重新配置该文件。

选项 B — 手动导出 DevTools 数据

1. 在浏览器中打开 React DevTools → Profiler 标签页 → Record
2. 与应用交互
3. 导出 JSON 并分享文件路径
4. 你的 MCP 客户端调用 load_render_profile({ filePath: "..." })

示例提示词

• “对我的应用运行渲染分析。”
• “停止捕获，并告诉我最慢的组件。”
• “哪些组件重新渲染最多？为什么？”
• “将此次运行与重构前捕获的性能分析结果进行比较。”
• “我已经有 React DevTools 导出文件了——加载它并告诉我哪里比较慢。”
• “显示开销最大的提交，以及每次峰值中占主导的组件。”

相关 Perfonext 工具

• perfonext-profiler-mcp — 为 Next.js 服务器进行 CPU 性能分析（V8/Chrome）
• perfonext-build-mcp — Next.js 包和构建分析

开发

npm install
npm run build
npm test

示例测试数据位于 tests/fixtures/ 下。

许可证

MIT