nsight-graphics-mcp

一个本地 MCP Server，通过 NVIDIA Nsight Graphics 自带的 ngfx-replay 读取、筛选和分析 Graphics Capture。

它优先调用与 capture 版本兼容的官方 replayer/CLI 导出；对官方表格没有覆盖的 GPU Trace 数据，则读取本机同版本 WarpVizPlugin 内嵌的 protobuf 描述符来解码 .ngfx-gputrace，避免把某一版私有 schema 硬编码进项目：

• capture 元数据、兼容性和运行环境摘要；

• API function stream；

• object/resource 列表；

• capture 日志；

• capture 内嵌截图；

• GPU Trace Summary：Top-Level Throughput、Active Threads Per Warp 和 SM Warp Occupancy；

• 全部 GPU Trace counters、marker/range 聚合与 Trace Information；

• .ngfx-gputrace 中的 GPU/Device/Queue、command streams、API 参数、timestamp boundaries；

• Shader Pipelines 的类型、名称、stage/hash、debug-data blob 引用与 code-block 属性；

• D3D12 BeginEvent/EndEvent marker 的绝对时间范围，以及按 marker/任意时间窗口聚合的逐 PC、逐 Shader stall/sample 类型热点；

• 隐藏窗口 replay 的逐迭代 CPU、reset、FPS、截图差异和 GPU frame time。

当前已在 Windows 11、Nsight Graphics 2026.3.0 和 D3D12 .ngfx-capture 上完成端到端验证。

安装

要求：

• Node.js 22 或更新版本；

• 本机 NVIDIA Nsight Graphics；

• 本机能够访问待分析的 .ngfx-capture 或 .ngfx-bincap 文件。

cd D:\github\nsight-graphics-mcp
npm install
npm run build

Server 入口是：

D:\github\nsight-graphics-mcp\dist\server.js

MCP 配置

大多数支持 stdio MCP 的客户端都接受类似配置：

{
  "mcpServers": {
    "nsight-graphics": {
      "command": "node",
      "args": [
        "D:\\github\\nsight-graphics-mcp\\dist\\server.js"
      ]
    }
  }
}

Server 会自动选择标准安装目录中版本最高的 ngfx-replay.exe。也可以显式指定：

{
  "env": {
    "NSIGHT_GRAPHICS_REPLAYER": "C:\\Program Files\\NVIDIA Corporation\\Nsight Graphics 2026.3.0\\host\\windows-desktop-nomad-x64\\ngfx-replay.exe"
  }
}

MCP tools

推荐的调用顺序：

1. nsight_status

2. inspect_capture

3. analyze_capture

4. 用 list_capture_events / list_capture_resources 针对结果下钻

5. 只看 Summary 时调用 get_gpu_trace_summary

6. 需要完整 profiler 数据时调用 collect_gpu_trace_report，然后用其 report_id 分页查询 metrics、ranges、timeline 和 pipelines

7. 需要多轮 replay 计时时调用 profile_capture

事件类别是用于检索的描述性标签，不保证互斥。例如 DispatchRays 同时属于 dispatch 和 ray tracing；CPU descriptor copy 不会计入 GPU copy 类别。

例如可以直接向支持 MCP 的模型提问：

分析 C:\captures\frame.ngfx-capture，先检查兼容性，再总结 draw、dispatch、barrier、资源和最频繁 API。

筛出这个 capture 中所有 dispatch 和 ray tracing 事件，每页返回 100 条。

对这个 capture replay 10 次，排除前 2 次 warmup，采集 GPU frame time，并解释 reset overhead。

对这个 capture 采集 GPU Trace Summary，返回 SM/PCIe/VidL2/L1TEX 吞吐率、每 Warp 活跃线程和各 Shader Stage Warp Occupancy。

get_gpu_trace_summary 的数据含义

这个工具通过本机 ngfx.exe 启动一次隐藏窗口的 ngfx-replay.exe，使用适配当前 GPU 架构的 Top-Level Triage metric set，并解析 Nsight --auto-export 生成的 GPUTRACE_FRAME.xls 和 FRAME.xls。返回结构直接对应 GPU Trace UI 的 Summary 页：

• range：Entire Trace 的 Start、End 和 Duration；

• topLevelThroughput：SM、PCIe、VidL2、L1TEX 的 peak sustained throughput 百分比；

• activeThreadsPerWarp：Active / Predicated-On Active Threads Per Warp 及 Coherence；

• smWarpOccupancy：Unallocated Warps in Active SMs，以及 Compute、Pixel、Vertex、Mesh、RT 等非零 Shader Warp 行。

每个值同时包含原始浮点数和与 UI 一致的一位小数 display，并附带 Nsight 原始 metric 名称，便于复核。默认从 capture 的 primary_gpu 推断 architecture；无法推断时可显式传入 architecture。默认 gpu_clocks=unaltered，也可选择 base 或 boost。

采集会真实执行 GPU workload，大型 capture 可能需要数分钟。工具保留 Shader Pipeline 收集，以便把 Warp Occupancy 正确归因到 Compute、Pixel、Vertex 等阶段；只关闭与 Summary 无关的外部 shader debug info 收集。提供 output_directory 时会保留 report 和导出的表，否则解析完成后清理临时文件。

这些值是在当前 GPU/驱动上重新 replay 得到的，不是原始 .ngfx-capture 内置数据。UI 手动选择子区间后得到的汇总也会不同于 Entire Trace。

完整 GPU Trace report 工作流

collect_gpu_trace_report 会打开 Shader Pipeline、外部 shader debug info、截图和逐 action timing 收集，并返回一个进程内 report_id。不需要重新采集时，可以用 open_gpu_trace_export 打开此前保留的目录。后续查询都只解析内存中的同一份 report：

collect_gpu_trace_report(capture_path=...)
  -> report_id
list_gpu_trace_metrics(report_id=..., name_regex="throughput|occupancy")
list_gpu_trace_ranges(report_id=..., path_regex="Scene/PostProcess")
summarize_gpu_trace_range(report_id=..., range_id="range-42")
list_gpu_trace_timeline_events(report_id=..., timed_only=true)
get_gpu_trace_timeline_event(report_id=..., event_id="device-0/queue-0/stream-12/call-7")
list_gpu_trace_marker_ranges(report_id=..., path_regex="BasePass$")
list_gpu_trace_shader_pipelines(report_id=..., include_inactive=false)
list_gpu_trace_shader_objects(report_id=..., include_inactive=false)
analyze_gpu_trace_pc_sampling(report_id=..., marker_id="marker-92", top_pcs=25)

不传 output_directory 时，report 创建在系统临时目录，并由 release_gpu_trace_report 删除；MCP 进程异常退出时可能残留临时文件。传入 output_directory 的用户目录永远不会被 release 工具删除。

inventory.capabilities 对每类 UI 数据明确返回 complete、partial 或 unavailable，调用方应遵守这个状态。二进制解析使用与当前 Nsight 安装匹配的 WarpVizPlugin 内嵌 schema；如果 report 和安装版本不匹配或插件不可用，表格查询仍能工作，binary tools 会给出明确原因。

Timeline 中的 timing.coalesced=true 表示一个 timestamp interval 覆盖了多个相邻 call，不能把同一个 duration 当作每个 call 的独立耗时。重新采集时使用默认的 time_every_action=true 可提高逐 action 边界覆盖。

Shader Pipelines 的 pcSampleCount / pcSampleSharePercent 来自每个 SM 的原始 PC-sample records，再按 shader code-block VA range 关联；list_gpu_trace_shader_objects 会按 stage/hash 去重，直接对应截图中的 Group By: Shader Object 与 Samples %。工具也保留 estimatedSampleSharePercent（按 active-warps 权重归一化）供缺少 raw stream 时回退或交叉比较，但不会把估算伪装成精确值。

analyze_gpu_trace_pc_sampling 解码 WRPV PC-sampling storage v1 的 sample type 1–19，可区分 L1TEX/RT Core Long Scoreboard、Short Scoreboard、Wait、Selected、Not Selected、Throttle 等类型，并按绝对 PC、code-block、shader hash 聚合。每个 SM 只周期性写入 (PTIMER, 累计 sample index) 锚点，而不是为每条 sample 写 timestamp，因此时间窗口使用锚点间中点插值，并在结果中明确返回 exactPerSampleTimestamps=false。这项能力不依赖 Shader PDB。

debugBlobReferenced 只表示 code block 引用了 report 中的 debug-data blob，不等同于 Nsight 已具备显示嵌套调用、源码行或指令关联所需的全部调试信息。

逐 PC/Shader Hotspots 与 stall reason 已支持；Shader Flame Graph、Top-Down/Bottom-Up 调用栈、source line、SASS 文本和 instruction mix 仍需要继续解析 shader code/debug ELF 与 call-stack 数据。PDB 缺失主要影响源码/函数/变量关联，不影响当前的 PC 与 stall 数值聚合。

架构与性能模型

实现按数据生命周期分成三层：Nsight collector 只负责 replay/auto-export，report parser 负责表格和 WRPV/protobuf 解码，MCP query 层只做过滤、排序和分页。一次 collect_gpu_trace_report 或 open_gpu_trace_export 建立 session 后，后续查询不会再次启动 Nsight 进程。

• auto-export 的固定表格并行读取，整帧和最近使用的 range 派生结果会复用；

• WRPV loader 只读取 56-byte header、压缩 protobuf metadata 和每个 48-byte chunk header，不会为了查看 metadata 把大型 chunk payload 整体载入内存；

• timeline timestamp boundaries 每个 command stream 只排序一次，之后线性生成全部 call timing；

• PC 地址建立排序前缀索引，code-block sample 统计由全表扫描变为二分区间求和；

• pipeline、shader object、code-block correlation 和最近使用的 PC-sampling 查询采用 report-local 有界 LRU；

• 不要求排序的 list tools 会扫描并计数全部匹配项，但内存中只保留当前页。

• GPU Trace 与动态 profile replay 默认经过同一个单并发队列，避免两个侵入式采集同时争用 GPU、相互污染计数器。

.ngfx-gputrace 解压后的 protobuf 对象和 PC sampling buffers 会在 session 生命周期内驻留，以换取快速交互查询。默认最多同时驻留 4 个 session，避免多份大型 report 无界占用内存。完成分析后应调用 release_gpu_trace_report；这既释放索引，也会清理 MCP 自动创建的临时 report 目录。

profile_capture 的计时含义

动态 profile 默认使用隐藏窗口、关闭 VSync，并通过 Nsight 的 performance report 读取每次迭代：

• frameTimeMs：replayer 执行 workload 的 CPU submit 与 finish wait 之和；

• gpuTimeMs：Nsight 在 command list 边界插入时间戳后计算的 GPU workload 时间；

• resetTotalMsPerFrame：CPU state reset、GPU data reset 提交和 reset GPU wait；

• replayAdjustedFps：排除 reset 后的 replay FPS；

• replayTotalFps：包含 reset 的总 FPS；

• screenshotMae：replay 与 capture screenshot 的 mean absolute error。

首轮通常包含 pipeline/shader/cache 冷启动。工具保留所有原始迭代，但汇总时排除 warmup_iterations。这些数据描述的是当前机器上的 replay，不是原进程当时的帧时间；逐 event 的 GPU 瓶颈仍应使用 Nsight GPU Trace。

如果提供 output_directory，Nsight 生成的 CSV、README、capture/replay/diff 图片会保留在唯一子目录中；否则它们只在系统临时目录中存在，读取后自动清理。

安全策略

Nsight Graphics capture 可能嵌入被捕获进程的完整环境变量。环境中经常存在 API key、token、密码或内部服务地址。

本项目采取以下默认且不可绕过的保护：

• 永不通过 MCP 返回环境变量值；

• include_environment_names=true 也只返回变量名；

• 对命令行、日志和诊断中的 token、JWT、Bearer header 和常见 key 格式再次脱敏；

• 缓存中只保存已经脱敏的 metadata；

• 不复制原 capture，也不修改原 capture。

内嵌截图本身不做视觉脱敏，调用或保存截图前应确认其中没有敏感画面。

环境变量

验证

npm run check
npm test
npm run test:integration -- "C:\path\to\capture.ngfx-capture"
npm run test:gpu-trace -- "C:\path\to\capture.ngfx-capture" ".\.cache\gpu-trace-artifacts"
npm run test:gpu-trace -- --open-export ".\.cache\gpu-trace-artifacts\nsight-mcp-gpu-trace-..."

端到端验证使用本地私有 capture 完成；仓库不包含 capture、导出产物、截图、应用标识或具体性能数据。

已知边界

Graphics Capture 的官方 metadata CLI 能可靠提供 event 名称和 object identity，但不提供完整 Event Details、resource dimensions 或 pipeline state；GPU Trace report 则提供 profiler command-stream 参数，但它们不是左侧 Graphics Debugger event tree 的一一替代。因此：

• 静态 call count 只能描述 workload 形状，不能单独证明性能瓶颈；

• capture 标记了 unsupported operation 或 incompatibility 时，replay 结果需要保守解释；

• marker range、任意时间窗口和逐 PC stall 聚合已支持；单条 sample 的时间来自 per-SM 锚点插值，不是硬件逐 sample 精确 timestamp；

• 精确 Shader Profiler Samples % 与 stall reason 已支持；flame graph、源码行、SASS 文本和 instruction mix 仍需要解析 shader code/debug ELF、call stack 与依赖信息；

• Graphics Debugger 左侧 Event Details、API Inspector、Object Browser 的完整 parity 仍需要接入 replay RPC 或更深的 capture 容器解析；

• 截图中 Nsight 自身提示 171 个 shader 缺少所需 debug info。MCP 目前能报告 debug-data blob 引用，但尚未复刻 Nsight 对“所需调试信息完整性”的判定和 171 这一统计；不存在的 source correlation 也无法恢复。

参考：NVIDIA Graphics Capture CLI、NVIDIA GPU Trace、NVIDIA GPU Trace UI、NVIDIA Shader Profiler、Model Context Protocol TypeScript SDK。

License

MIT