Perfonext Profiler MCP

io.github.souvikdu由 GitHub 帳號 souvikdu 發布v0.7.3更新於 Oct 24, 2026

MCP server for analyzing V8/Chrome CPU profiles with line-level tick attribution.

已驗證STDIO僅桌面開發者工具資料與分析

概覽

AI 產生的概覽

本機 MCP 伺服器，載入 V8/Chrome CPU 效能剖析檔，讓助理取得熱點排名、依 npm 套件統計的成本，以及標註原始碼的熱點行。

可以做什麼
載入並彙整效能剖析檔：解析 .cpuprofile 檔或含 CPU 資料的 Chrome trace 匯出，列出已載入的剖析檔，並先提供擷取剖析檔的操作步驟。熱點排名：依自身耗時列出最耗時的函式，並標註所屬 npm 套件或使用者程式碼。解釋函式：顯示耗時、呼叫端與被呼叫端，可選擇附上依 V8 取樣數標註的原始碼行。依 npm 套件彙整自身耗時，找出成本最高的相依套件。比較兩份剖析檔以找出效能退步，並針對熱點函式提供結構化的最佳化建議。
適用情境
適合在為 Next.js 伺服器或 Node 指令碼做效能剖析時使用：希望助理直接解讀 CPU 剖析資料，而不是讀取數 MB 的原始傾印，例如尋找熱點、找出昂貴的相依套件，或比較基準剖析檔與新剖析檔。
執行需求
以 stdio 伺服器在本機執行，透過 npx 啟動 npm 套件 @perfonext/profiler-mcp，因此需要 Node.js 與 npm。未宣告驗證、環境變數或標頭。磁碟上需已有 .cpuprofile 檔或 Chrome trace 匯出。
安裝前請注意
讀取原始碼的工具會存取磁碟檔案；僅能讀取目前工作目錄內的檔案，其他路徑會被拒絕。效能剖析檔及從中讀取的原始碼行會傳給所連線的助理，因此不要分析不希望與該用戶端共享的程式碼。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Perfonext Profiler MCP，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

perfonext-profiler-mcp

Analyze V8 and Chrome CPU profiles to find hotspots in Next.js servers and scripts.

[npm] [npm downloads] [license] [website]

perfonext-profiler-mcp is a Model Context Protocol (MCP) server that gives GitHub Copilot, Claude Desktop, Claude Code, and other MCP clients structured CPU profiling data for Next.js performance work. It loads V8 and Chrome CPU profiles and turns them into hotspot rankings, per-package costs, and source-annotated hot lines — evidence agents can reason over instead of ingesting multi-megabyte profile dumps.

Quick Start

perfonext-profiler-mcp is a standard MCP stdio server, so it works with any MCP-compatible client (GitHub Copilot in VS Code, Claude Desktop, Claude Code, Cursor, and others). Run it directly with npx:

bash
npx -y @perfonext/profiler-mcp

Or install globally:

bash
npm install -g @perfonext/profiler-mcp

The executable command remains perfonext-profiler-mcp after installation.

VS Code

Add the server to .vscode/mcp.json (the workspace MCP configuration file):

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

Reload the VS Code window and run MCP: List Servers to start it, or accept the trust prompt when it appears.

Claude Desktop

Add the server to claude_desktop_config.json:

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

Restart Claude Desktop to pick up the new server.

Claude Code

Add the server with the CLI:

bash
claude mcp add perfonext-profiler -- npx -y @perfonext/profiler-mcp

Or add the same mcpServers entry to .mcp.json.

Other MCP clients

Any client that supports stdio MCP servers can launch npx -y @perfonext/profiler-mcp. Consult your client's documentation for its MCP server configuration format.

For a locally-built checkout, point command/args at node and the repo's dist/index.js instead.

Troubleshooting

spawn npx ENOENT / spawn node ENOENT on macOS with nvm

If the server fails to start with this error, your GUI MCP client likely cannot see nvm. GUI apps on macOS do not load shell config (.zshrc/.bashrc), so nvm-installed npx/node are not on PATH. Use an absolute npx path and include the same Node directory in PATH:

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

Merge these fields into your client's server entry, under servers for VS Code or mcpServers for Claude Desktop/Code. Then ask your assistant: "How do I capture a CPU profile of my Next.js server?"

What It Does

  • loads .cpuprofile files and Chrome trace exports that contain CPU profile data
  • identifies the hottest functions by self time, annotated with the originating npm package
  • explains caller and callee relationships for a selected function
  • reads actual source code for hot functions and annotates each line with V8 sample counts (v0.2.0)
  • aggregates CPU self-time per npm package to find expensive third-party dependencies (v0.3.0)
  • compares two profiles to surface regressions and improvements
  • returns deterministic optimization suggestions for common hotspots
  • summarizes loaded profiles so an MCP client can keep context tight

Tools

ToolDescription
how_to_collectReturn a ready-to-run command and step-by-step recipe for capturing a .cpuprofile, then loading it. Use this when you don't have a profile yet
load_profileParse and load a .cpuprofile file or Chrome trace export from disk
get_hotspotsFind top functions by self-time. Each entry includes a package field identifying the npm package or (user code)
explain_functionExplain a function's timing, callers, and callees. Pass includeSource: true to attach annotated source lines
read_source_contextRead the actual source file for a hot function and annotate each line with tick counts from positionTicks
get_package_costsAggregate CPU self-time by npm package — shows which dependencies are most expensive
compare_profilesCompare two profiles and highlight regressions
suggest_optimizationsGenerate structured, multi-pattern optimization suggestions for hot functions. Detects high fan-in, recursion, dominant callers, and V8-specific patterns. Deduplicates functions split across multiple call sites
get_profile_summarySummarize one profile or list all loaded profiles

Every tool result carries a nextStep breadcrumb pointing at the natural follow-up call, so an MCP client can walk the collect → analyze → fix loop without guessing.

Example Prompts

  • "How do I capture a CPU profile of my Next.js server?"
  • "Load the CPU profile at ./profile.cpuprofile and show me the top hotspots."
  • "Which npm packages are consuming the most CPU in this profile?"
  • "Explain why processData is expensive in the loaded profile."
  • "Show me the actual source lines for processData and mark which lines are hottest."
  • "Explain transformResult and include the annotated source code."
  • "Compare my baseline and current CPU profiles and tell me what got slower."
  • "Suggest optimizations for the top three hotspots."

Deep Tool Reference

Per-tool input/output schemas and manual profile capture

how_to_collect details

jsonc
// Input{ "scenario": "next-server" } // or "script"; defaults to "next-server"
// Output{  "scenario": "next-server",  "summary": "Profile a production Next.js server while it handles a single request. ...",  "command": "node --cpu-prof --cpu-prof-dir=./.perf-profiles ./node_modules/next/dist/bin/next start",  "steps": [ "...", "load_profile({ filePath: \"./.perf-profiles/<file>.cpuprofile\" })" ],  "outputDir": "./.perf-profiles",  "nextStep": "After stopping the server, call load_profile with the .cpuprofile ..."}

next-server profiles a production Next.js server while it serves a single request. If next start says standalone output is unsupported, use the script scenario with .next/standalone/server.js. script profiles that standalone server (or another Node entry). Keep the scenario to one route and one hit. Node writes one .cpuprofile per process/worker thread into the output directory. The Next server command uses Node CLI flags (not NODE_OPTIONS) so it is the same on Unix and Windows.

read_source_context details

jsonc
// Input{ "profileId": "<id>", "functionName": "myFn", "contextLines": 10 }
// Output (per line){  "lineNumber": 42,  "content": "  for (let i = 0; i < items.length; i++) {",  "ticks": 18,      // V8 samples that landed on this line  "isHot": true     // true when ticks >= 50% of peak ticks for this function}

The returned window is sized to cover the function's actual hot lines, not just a fixed radius around its declaration — a function's real bottleneck is often well past its function line. contextLines (default 10) sets the minimum padding around both the declaration and the hot lines; if any ticks still fall outside the returned window, the top-level result includes hiddenTicks (a count) and a warning telling you to retry with a larger contextLines. explain_function also accepts contextLines when called with includeSource: true.

Only files inside the current working directory can be read. file:// URLs and absolute paths are both handled; http://, node: builtins, and paths outside the project root are rejected.

suggest_optimizations details

jsonc
// Input{ "profileId": "<id>", "limit": 5 }
// Output (per function){  "function": "processData",  "file": "file:///app/src/processor.js",  "line": 10,  "selfPercent": "18.2%",  "patterns": [    {      "pattern": "high-fan-in",      "detail": "Called from 6 distinct call sites (e.g. renderRow, buildTree, …)",      "suggestion": "This function is a shared hot path. Ensure it is well-optimised and monomorphic …"    },    {      "pattern": "hot-caller",      "detail": "84% of calls come from \"renderRow\"",      "suggestion": "Focus optimisation effort on \"renderRow\" rather than this function …"    }  ],  "topSuggestion": "This function is a shared hot path …"}

Patterns detected (multiple can fire for the same function):

PatternTrigger
gc-pressureFunction name matches GC/Scavenge/MarkCompact
json-serializationJSON.parse / JSON.stringify
regex-costRegExp / exec / test calls
v8-deoptCompile / Recompile / Optimize / Deoptimize
high-fan-in≥ 3 distinct parent call sites
recursionFunction appears in its own descendant sub-tree
hot-callerOne caller accounts for ≥ 80% of call-site occurrences
cpu-boundFallback when no other pattern matches

Functions that appear at multiple call sites are automatically merged before ranking so the same logical function is only reported once.

get_package_costs details

jsonc
// Input{ "profileId": "<id>", "limit": 10 }
// Output (per package){  "rank": 1,  "package": "lodash",  "selfTime": "42.3ms",  "selfPercent": "14.1%",  "totalTimeIncludingCallbacks": "58.0ms",  "totalPercentIncludingCallbacks": "19.3%",  "topFunctions": [    { "function": "chunk", "file": "lodash/chunk.js", "line": 41, "selfTime": "28.0ms", "selfPercent": "9.3%" }  ]}

selfTime is the time spent inside the package's own code. totalTimeIncludingCallbacks also counts everything the package called into — including your own callbacks handed back to it — so it can exceed what removing the package would actually save.

Scoped packages (@babel/core, @next/env, etc.) are handled correctly. User code and native builtins (no node_modules in the path) are excluded.

Generating a CPU Profile

Ask Copilot to call how_to_collect for a ready-to-run recipe, or generate one manually:

Next.js production server (profile a single request):

bash
node --cpu-prof --cpu-prof-dir=./.perf-profiles ./node_modules/next/dist/bin/next start# hit the route once, then stop the process so it can exit and write the profile

If next start reports that standalone output is unsupported:

bash
node --cpu-prof --cpu-prof-dir=./.perf-profiles .next/standalone/server.js

Chrome DevTools:

  1. Open DevTools and go to the Performance tab.
  2. Record the scenario you want to inspect.
  3. Stop recording and save the result as a .cpuprofile export.

Related Perfonext Tools

Development

bash
npm installnpm run buildnpm test

The repository already includes sample fixtures under tests/fixtures/ for local validation.

License

MIT

來源：README.md，提交 c6ff838

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.7.3最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分