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 的摘要，而不是原始的多兆字节 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 分