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