V8 Cpu Profile Decoder MCP

v8-cpu-profile-decoder-mcp 🐸⚡

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:

{

"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.

{

"profile_path": "/app/profiles/CPU.20260516.cpuprofile", "top_n": 5, "min_self_percent": 1.0 }

[

{ "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.

{

"profile_path": "/app/profiles/CPU.20260516.cpuprofile", "function_name": "hashPassword", "top_callers": 3 }

{

"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.

{

"profile_path": "/app/profiles/CPU.20260516.cpuprofile", "top_n": 5 }

{

"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.

{

"profile_path": "/app/profiles/CPU.cpuprofile", "threshold_percent": 10 }

{

"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.

{

"before_profile_path": "/app/profiles/before.cpuprofile", "after_profile_path": "/app/profiles/after.cpuprofile", "top_n": 5 }

{

"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.

{

"profile_path": "/app/profiles/CPU.cpuprofile", "threshold_percent": 10 }

{

"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

npx v8-cpu-profile-decoder-mcp

Or install globally:

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

Generate a CPU profile in Node.js

# Single run

node --cpu-prof your-script.js

With custom output dir

node --cpu-prof --cpu-prof-dir ./profiles your-script.js

Or programmatically via Chrome DevTools → Performance tab → Record.

Claude Desktop config

{

"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

• playwright-trace-decoder-mcp — decode Playwright traces for CI failure root-cause analysis
• playwright-network-chaos-mcp — simulate network failures and latency in browser sessions
• flakiness-knowledge-graph-mcp — knowledge graph of flaky test patterns
• ast-impact-mapper-mcp — find affected tests from code changes via TypeScript AST
• playwright-spatial-layout-mcp — geometric spatial awareness of web layouts

---

📄 License

MIT © vola-trebla