V8 Cpu Profile Decoder Mcp

io.github.vola-trebla由 GitHub 帳號 vola-trebla 發布v0.3.0更新於 Oct 24, 2026

MCP server that decodes V8 CPU profiles into token-efficient bottleneck summaries for AI agents

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

概覽

AI 產生的概覽

將 V8 CPU 效能設定檔解碼成精簡的瓶頸摘要，讓助理能找出 Node.js 應用程式中的熱點函式、呼叫端、GC 壓力與非同步開銷。

可以做什麼
它在本機解析 .cpuprofile 檔案，回傳節省 token 的摘要，而不是原始的多 MB JSON。工具包括 extract_hottest_functions（依自身耗時排序的熱點函式，過濾 V8 與 Node 內建項目）、analyze_call_tree_path（找出某函式的呼叫端與呼叫次數）、correlate_source_code（透過 .js.map 將編譯後的 JS 對應回 TypeScript）、analyze_gc_pressure（依類型統計 GC 佔比並與門檻比較）、diff_profiles（比較兩個設定檔的每函式差異）以及 analyze_async_bottlenecks（事件迴圈與微任務開銷）。
適用情境
當 Node.js 服務變慢，且你已有透過 node --cpu-prof 或 Chrome DevTools 產生的 .cpuprofile 檔案，並希望助理找出熱點函式、追蹤某個慢函式的呼叫來源、判斷 GC 或非同步開銷是否為主因，或比較最佳化前後的設定檔時使用。沒有設定檔時它沒有用處。
執行需求
以 npm 套件形式透過 stdio 在本機執行（npx v8-cpu-profile-decoder-mcp 或全域安裝），需要 Node.js。未宣告帳號、API 金鑰、環境變數或標頭。它從本機路徑讀取 .cpuprofile 檔案，原始碼對應還需要對應的 .js.map 檔案。
安裝前請注意
這些工具會讀取助理提供的 .cpuprofile 檔案路徑，因此設定檔路徑可能把程式碼庫中的原始檔路徑與函式名稱暴露給模型。它只讀取設定檔，不會修改，且未宣告任何憑證、網路存取或付費行為。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 V8 Cpu Profile Decoder Mcp，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

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

其他 MCP 客戶端

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

README

v8-cpu-profile-decoder-mcp 🐸⚡

[npm version] [npm downloads] [CI] [License: MIT]

An MCP server that decodes V8 CPU profiles into token-efficient bottleneck summaries for AI agents.

Your Node.js app is slow. You ran --cpu-prof. Now you have a 20MB .cpuprofile file — and your AI agent is completely blind to it.

🤔 The Problem

V8 CPU profiles are massive. A typical .cpuprofile from a production Node.js app is 5–50MB of raw JSON — millions of lines mapping memory addresses, tick counts, and microsecond execution sequences. It looks like this:

json
{  "nodes": [    { "id": 1482, "callFrame": { "functionName": "processRequest", "url": "file:///app/dist/server.js", "lineNumber": 847 }, "hitCount": 3241, "children": [1483, 1490] },    ...  ],  "samples": [1482, 1483, 1482, 1490, 1482, ...],  "timeDeltas": [120, 98, 115, 102, ...]}

An AI agent attempting to read this file instantly collapses its context window and fails. Even if it could read it, it can't run the aggregation algorithms needed to compute inclusive/exclusive CPU times across the call tree.

So when you ask your agent:

  • 🙈 "Which function is consuming the most CPU?"
  • 🙈 "What's calling my slow database query?"
  • 🙈 "Which TypeScript file is the bottleneck actually coming from?"

...it's guessing. It has no access to the profiling data.

v8-cpu-profile-decoder-mcp fixes that. It decodes the profile locally and hands the agent a 10-line semantic summary instead of a 50MB file.

🛠️ Tools

extract_hottest_functions

Parses the .cpuprofile and returns the top N functions ranked by exclusive CPU time (self time). Filters out V8 internals and Node.js built-ins — only user code.

json
{  "profile_path": "/app/profiles/CPU.20260516.cpuprofile",  "top_n": 5,  "min_self_percent": 1.0}
json
[  {    "rank": 1,    "functionName": "hashPassword",    "url": "file:///app/dist/auth/crypto.js",    "lineNumber": 42,    "selfTimeMs": 1842.5,    "totalTimeMs": 1842.5,    "selfPercent": 61.32,    "totalPercent": 61.32,    "hitCount": 3241  },  {    "rank": 2,    "functionName": "parseJsonBody",    "url": "file:///app/dist/middleware/body.js",    "lineNumber": 18,    "selfTimeMs": 412.1,    "totalTimeMs": 412.1,    "selfPercent": 13.71,    "totalPercent": 13.71,    "hitCount": 724  }]

analyze_call_tree_path

Finds all callers of a specific function and shows how often each one invoked it. Accepts partial, case-insensitive function name matching.

json
{  "profile_path": "/app/profiles/CPU.20260516.cpuprofile",  "function_name": "hashPassword",  "top_callers": 3}
json
{  "targetFunction": "hashPassword",  "matchedNodes": 2,  "totalSelfTimeMs": 1842.5,  "totalPercent": 61.32,  "callers": [    {      "functionName": "loginHandler",      "url": "file:///app/dist/routes/auth.js",      "lineNumber": 94,      "callCount": 2180,      "selfTimeMs": 240.1    },    {      "functionName": "validateSession",      "url": "file:///app/dist/middleware/auth.js",      "lineNumber": 31,      "callCount": 1061,      "selfTimeMs": 116.8    }  ]}

correlate_source_code

Maps compiled JS bottlenecks back to their original TypeScript source locations using .js.map files. Falls back gracefully to compiled JS locations if no source map is found.

json
{  "profile_path": "/app/profiles/CPU.20260516.cpuprofile",  "top_n": 5}
json
{  "resolved": [    {      "rank": 1,      "generatedUrl": "file:///app/dist/auth/crypto.js",      "generatedLine": 42,      "source": {        "originalFile": "src/auth/crypto.ts",        "originalLine": 38,        "originalColumn": 2,        "originalFunction": "hashPassword"      },      "selfTimeMs": 1842.5,      "selfPercent": 61.32    }  ],  "sourcemapErrors": []}

analyze_gc_pressure

Reports garbage collection overhead as a percentage of profiling duration, broken down by GC type. Flags when GC exceeds a configurable threshold and provides a targeted recommendation.

json
{  "profile_path": "/app/profiles/CPU.cpuprofile",  "threshold_percent": 10}
json
{  "gc_ticks": 184,  "total_ticks": 1240,  "gc_percentage": 14.84,  "gc_type_breakdown": {    "scavenger": 122,    "mark_sweep": 0,    "mark_compact": 0,    "incremental": 62,    "generic": 0  },  "exceeds_threshold": true,  "threshold_percent": 10,  "verdict": "GC consumed 14.84% of CPU — exceeds the 10% threshold. Dominated by Scavenger (short-lived object pressure). Consider object pooling, reusing buffers, or reducing closure captures."}

diff_profiles

Compares two .cpuprofile files (before/after an optimization) and returns per-function CPU time deltas, normalized against each profile's total duration. Frames are matched by call-frame coordinates, not transient node IDs, so alignment is stable across profiling sessions.

json
{  "before_profile_path": "/app/profiles/before.cpuprofile",  "after_profile_path": "/app/profiles/after.cpuprofile",  "top_n": 5}
json
{  "before_duration_ms": 5000,  "after_duration_ms": 4800,  "total_execution_delta_ms": -200,  "total_execution_delta_percent": -4,  "top_improvements": [    {      "function_name": "hashPassword",      "url": "file:///app/dist/auth/crypto.js",      "line_number": 42,      "before_ms": 1842.5,      "after_ms": 620.1,      "absolute_diff_ms": -1222.4,      "relative_diff_percent": -66.34    }  ],  "top_regressions": [],  "only_in_before": [],  "only_in_after": []}

analyze_async_bottlenecks

Detects event-loop overhead by identifying V8 internal frames representing async machinery — microtask queue processing, nextTick saturation, and timer/immediate callbacks.

json
{  "profile_path": "/app/profiles/CPU.cpuprofile",  "threshold_percent": 10}
json
{  "total_ticks": 1240,  "async_ticks": 186,  "event_loop_overhead_ms": 372,  "event_loop_overhead_percent": 15.0,  "dominant_async_patterns": [    { "pattern": "promise_chains", "ticks": 142, "percent": 11.45 },    { "pattern": "nexttick_saturation", "ticks": 44, "percent": 3.55 }  ],  "verdict": "Event-loop overhead is 15.0% of CPU — exceeds the 10% threshold. Promise chain overhead is visible in the profile. Consider batching microtasks, using Promise.all() to parallelise I/O, or offloading CPU-bound continuations to worker threads."}

🚀 Installation

bash
npx v8-cpu-profile-decoder-mcp

Or install globally:

bash
npm install -g v8-cpu-profile-decoder-mcp

Generate a CPU profile in Node.js

bash
# Single runnode --cpu-prof your-script.js
# With custom output dirnode --cpu-prof --cpu-prof-dir ./profiles your-script.js

Or programmatically via Chrome DevTools → Performance tab → Record.

Claude Desktop config

json
{  "mcpServers": {    "v8-cpu-profile-decoder-mcp": {      "command": "npx",      "args": ["-y", "v8-cpu-profile-decoder-mcp"]    }  }}

💡 Example Agent Prompts

"Here's my CPU profile at /app/profiles/CPU.cpuprofile — which function is consuming the most CPU?"

"Find what's calling processRequest in this profile and how often"

"Map the top 10 hottest functions back to their original TypeScript files"

"My Node.js API is slow under load — profile is at /tmp/CPU.cpuprofile, find the bottleneck"

"Is GC the bottleneck? Check the profile at /tmp/CPU.cpuprofile and tell me what kind of allocation is causing it"

"Compare these two profiles before and after my optimization — which functions improved and which regressed?"

"Is this app spending too much CPU on async overhead and event-loop machinery?"

🔗 Related Projects

📄 License

MIT © vola-trebla

來源：README.md，提交 71fd9dc

工具

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

版本歷史

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

評分

已滿足適用檢查項的 50%

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

  • 近 30 天內可連通25 分

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

  • 已宣告認證方式10 分

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

  • 已列出工具15 分

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

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