内容
# v8-cpu-profile-decoder-mcp
[](https://www.npmjs.com/package/v8-cpu-profile-decoder-mcp)
[](https://www.npmjs.com/package/v8-cpu-profile-decoder-mcp)
[](https://github.com/vola-trebla/v8-cpu-profile-decoder-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
一个 MCP 服务器，负责将 V8 CPU 配置文件解码为 **token-efficient bottleneck summaries**，供 AI 代理使用。
你的 Node.js 应用很慢。你运行了 `--cpu-prof` 命令。现在你有一个 20MB 的 `.cpuprofile` 文件 —— 而你的 AI 代理完全无法读取它。
## 🤔 问题
V8 CPU 配置文件非常庞大。一个典型的 `.cpuprofile` 文件，来自生产环境的 Node.js 应用，大小为 **5–50MB 的原始 JSON** —— 数百万行映射内存地址、 tick 计数和微秒执行序列。内容如下：
```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, ...]
}
```
AI 代理尝试读取此文件时，**立即崩溃其上下文窗口** 并失败。即使它能读取，也无法运行聚合算法来计算调用树中包含/排除的 CPU 时间。
所以，当你问你的 AI 代理：
- 🙈 _"哪个函数消耗了最多的 CPU？"_
- 🙈 _"是什么调用了我的慢速数据库查询？"_
- 🙈 _"实际上，瓶颈来自哪个 TypeScript 文件？"_
...它只能猜测。它无法访问配置文件数据。
`v8-cpu-profile-decoder-mcp` 解决了这个问题。它在本地解码配置文件，并为代理提供 **10 行语义摘要**，而不是 50MB 文件。
## 🛠️ 工具
### `extract_hottest_functions`
解析 `.cpuprofile` 文件，并返回按独占 CPU 时间排名的前 N 个函数（自身时间）。
过滤掉 V8 内部和 Node.js 内置函数 —— 仅限用户代码。
```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`
查找特定函数的调用者，并显示每个调用者调用它的频率。
接受部分、大小写不敏感的函数名称匹配。
```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`
使用 `.js.map` 文件将编译的 JS 瓶颈映射回其 **原始 TypeScript 源位置**。
如果找不到源映射，则会优雅地回退到编译的 JS 位置。
```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`
报告垃圾回收开销占配置文件持续时间的百分比，按 GC 类型细分。
当 GC 超过可配置的阈值时发出信号，并提供有针对性的建议。
```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 消耗了 14.84% 的 CPU — 超过 10% 的阈值。主要是 Scavenger（短寿命对象压力）。考虑对象池、重用缓冲区或减少闭包捕获。"
}
```
---
### `diff_profiles`
比较两个 `.cpuprofile` 文件（优化前/后），并返回每个函数的 CPU 时间差异，
针对每个配置文件的总持续时间进行归一化。帧通过调用帧坐标匹配，而不是瞬态节点 ID，因此在配置文件会话中对齐是稳定的。
```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`
通过识别 V8 内部帧来检测事件循环开销，这些帧代表异步机制 —
微任务队列处理、`nextTick` 饱和和定时器/立即回调。
```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": "事件循环开销占 CPU 的 15.0% — 超过 10% 的阈值。配置文件中可见 Promise 链开销。考虑批量处理微任务、使用 Promise.all() 并行化 I/O，或将 CPU 绑定的继续传递给工作线程。"
}
```
---
## 🚀 安装
```bash
npx v8-cpu-profile-decoder-mcp
```
或全局安装：
```bash
npm install -g v8-cpu-profile-decoder-mcp
```
### 在 Node.js 中生成 CPU 配置文件
```bash
# 单次运行
node --cpu-prof your-script.js
# 使用自定义输出目录
node --cpu-prof --cpu-prof-dir ./profiles your-script.js
```
或通过 Chrome DevTools → 性能选项卡 → 记录。
### Claude Desktop 配置
```json
{
"mcpServers": {
"v8-cpu-profile-decoder-mcp": {
"command": "npx",
"args": ["-y", "v8-cpu-profile-decoder-mcp"]
}
}
}
```
---
## 💡 示例代理提示
> _"这是我的 `/app/profiles/CPU.cpuprofile` 处的 CPU 配置文件 — 哪个函数消耗了最多的 CPU？"_
> _"在该配置文件中找到调用 `processRequest` 的函数及其调用频率"_
> _"将最热的 10 个函数映射回其原始 TypeScript 文件"_
> _"我的 Node.js API 在负载下很慢 — 配置文件位于 `/tmp/CPU.cpuprofile`，请找到瓶颈"_
> _"GC 是瓶颈吗？检查 `/tmp/CPU.cpuprofile` 处的配置文件并告诉我是什么类型的分配导致了它"_
> _"比较这两个配置文件，优化前后的配置文件 — 哪些函数改进了，哪些函数退化了？"_
> _"该应用程序是否在异步开销和事件循环机制上花费了太多 CPU？"_
---
## 🔗 相关项目
- [playwright-trace-decoder-mcp](https://github.com/vola-trebla/playwright-trace-decoder-mcp) — 解码 Playwright 跟踪信息以进行 CI 故障根本原因分析
- [playwright-network-chaos-mcp](https://github.com/vola-trebla/playwright-network-chaos-mcp) — 在浏览器会话中模拟网络故障和延迟
- [flakiness-knowledge-graph-mcp](https://github.com/vola-trebla/flakiness-knowledge-graph-mcp) — 易失性测试模式的知识图谱
- [ast-impact-mapper-mcp](https://github.com/vola-trebla/ast-impact-mapper-mcp) — 通过 TypeScript AST 查找受代码更改影响的测试
- [playwright-spatial-layout-mcp](https://github.com/vola-trebla/playwright-spatial-layout-mcp) — 网页布局的几何空间感知
---
## 📄 许可证
MIT © [vola-trebla](https://github.com/vola-trebla)
