v8-cpu-profile-decoder-mcp

View on GitHub

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

1 stars TypeScriptOthers Updated Jul 8, 2026

Documentation

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:

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

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?"_

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

Frequently asked questions

What is v8-cpu-profile-decoder-mcp?

v8-cpu-profile-decoder-mcp is MCP server that decodes V8 CPU profiles into token-efficient bottleneck summaries for AI agents

How do I install v8-cpu-profile-decoder-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is v8-cpu-profile-decoder-mcp open source?

Yes — it is hosted on GitHub at https://github.com/vola-trebla/v8-cpu-profile-decoder-mcp and has 1 stars.

Related MCP tools

servers

Model Context Protocol Servers

90,051 TypeScript

UI-TARS-desktop

The Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra

38,840 TypeScript

agentvlmvision+11

n8n-mcp

A MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you

22,825 TypeScript

mcpmcp-servern8n+1

Figma-Context-MCP

MCP server to provide Figma layout information to AI coding agents like Cursor

15,766 TypeScript

aicursorfigma+2

inbox-zero

The world's best AI personal assistant for email. Open source app to help you reach inbox zero fast.

12,148 TypeScript

aiemailnextjs+14

instant

Instant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.

10,507 TypeScript

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP

Documentation

v8-cpu-profile-decoder-mcp 🐸⚡

🤔 The Problem

🛠️ Tools

`extract_hottest_functions`

`analyze_call_tree_path`

`correlate_source_code`

`analyze_gc_pressure`

`diff_profiles`

`analyze_async_bottlenecks`

🚀 Installation

Generate a CPU profile in Node.js

Claude Desktop config

💡 Example Agent Prompts

🔗 Related Projects

📄 License

Frequently asked questions

What is v8-cpu-profile-decoder-mcp?

How do I install v8-cpu-profile-decoder-mcp?

Is v8-cpu-profile-decoder-mcp open source?

Related MCP tools