V8 Cpu Profile Decoder Mcp

io.github.vola-treblaPublished by GitHub account vola-treblav0.3.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyFiles & StorageDeveloper ToolsData & Analytics

Overview

AI-generated overview

Decodes V8 CPU profiles into compact bottleneck summaries so an assistant can find hot functions, callers, GC pressure, and async overhead in Node.js apps.

What you can do
It parses .cpuprofile files locally and returns token-efficient summaries instead of the raw multi-megabyte JSON. Tools include extract_hottest_functions (top functions by self time, filtering V8 and Node internals), analyze_call_tree_path (callers of a named function with call counts), correlate_source_code (mapping compiled JS back to TypeScript via .js.map files), analyze_gc_pressure (GC share by type against a threshold), diff_profiles (per-function deltas between two profiles), and analyze_async_bottlenecks (event-loop and microtask overhead).
When to use it
Use it when a Node.js service is slow and you have a .cpuprofile from node --cpu-prof or Chrome DevTools, and you want the assistant to identify hot functions, trace what calls a slow function, check whether GC or async overhead dominates, or compare profiles before and after an optimization. It is not useful without a profile file.
Requirements
Runs locally over stdio as an npm package (npx v8-cpu-profile-decoder-mcp or a global install); Node.js is needed. No accounts, API keys, environment variables, or headers are declared. It reads .cpuprofile files from local paths, and source-map correlation needs the matching .js.map files.
Before you install
The tools read .cpuprofile files from paths the assistant supplies, so a profile path can expose source file paths and function names from your codebase to the model. It only reads profiles and does not modify them, and it declares no credentials, network access, or spending.

Installation

In SourceWeft

  1. Open V8 Cpu Profile Decoder Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit 71fd9dc

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts