An MCP (Model Context Protocol) server for NVIDIA Nsight Graphics on
Windows. It wraps the entire Nsight Graphics command-line surface
(ngfx.exe, ngfx-capture.exe, ngfx-replay.exe, ngfx-rpc.exe, the
nv-aftermath-* tools, , the layer-install
batch scripts, the NGFX in-app SDK headers, , and the bundled
DXC) so an LLM agent can drive Graphics Capture, GPU Trace Profiler,
Generate C++ Capture, OpenGL Frame Debugger, Aftermath crash analysis, and
in-app integration end-to-end — without the Nsight UI.
MCP server for NVIDIA Nsight Graphics — wraps the full CLI surface (ngfx / ngfx-capture / ngfx-replay / Aftermath / NGFX SDK) and indexes captures into SQLite for fast LLM-driven analysis. 105 tools.
星标
12
工具
—
可用率
—
nv-nsight-remote-monitor.exe
glslang.exe
Why a wrapper? The Nsight Graphics CLIs are scriptable, but their
outputs are coarse: ngfx-replay --metadata-functions dumps the entire
recorded API stream to stdout, --metadata-objects dumps every API
object as JSON, .nsight-gputrace reports are zip-like archives, and
the NGFX in-app SDK is a tree of headers. nsight-graphics-mcp indexes
those coarse outputs into per-capture SQLite databases, peeks inside
the archives, parses the SDK headers, and exposes precise queries the
LLM can call instantly without re-running the CLI.
What it can do
Drive the four documented activities (ngfx.exe --activity)
Activity
MCP tool (launched)
MCP tool (attached)
Graphics Capture
ngfx_graphics_capture_launched
ngfx_graphics_capture_attached
GPU Trace Profiler
ngfx_gputrace_launched
ngfx_gputrace_attached
Generate C++ Capture
ngfx_cpp_capture_launched
(use ngfx_raw with --attach-pid)
OpenGL Frame Debugger
ngfx_framedebugger_launched
(use ngfx_raw with --attach-pid)
Each one accepts the full set of activity-specific flags from ngfx --help-all — start triggers (--start-after-frames / --start-after-ms
/ --start-after-hotkey / --start-with-ngfx-sdk / …), stop triggers
(--limit-to-frames / --max-duration-ms / --stop-with-ngfx-sdk / …),
per-arch metric-set selection, GPU clock locking, shader-pipeline
collection toggles, and so on.
Pass background=True to keep ngfx.exe running so you can hit the
capture / trace hotkey in-app — the call returns a launch-session handle
you can poll with ngfx_launch_status and terminate with
ngfx_launch_stop.
Headless capture (ngfx-capture.exe) — no Nsight UI required
Tool
What it does
ngfx_capture_launched
Run ngfx-capture.exe directly. Produces a .ngfx-capture / .ngfx-gfxcap with a bundled replayer. Supports all triggers, compression, HVVM modes, delimiter modes, troubleshooting knobs, and ray-tracing options from ngfx-capture --help.
ngfx_capture_recapture
--recapture an existing capture with current format.
ngfx_capture_recompress
--recompress for higher compression / format upgrades.
Deep Nsight-only capture capability report
Tool
What it does
ngfx_deep_capture_capability_report
Inspect the selected Nsight install, SDK headers, relevant plugins, optional capture path, and CLI help to rank the deepest available Nsight-only path for shader/render debugging. It explicitly separates the current Graphics Capture replacement path from legacy/optional C++ Capture and returns the MCP tool chain to use next.
Index every API object recorded into a SQLite DB (categorised: pipeline / shader / resource / descriptor / sync / command / queue / surface / device / ray_tracing / other).
ngfx_query_objects
Filter by type_name / category / name_regex / api.
Every Buffer / Image / Sampler / DeviceMemory / Heap.
Protobuf schema reference (RE-derived)
The internal capture format is protobuf-encoded in the NV.* namespace.
The MCP extracts the schema directly from the Nsight binaries so the LLM
can navigate the format conceptually without re-running protoc.
Two layers are exposed:
Inventory only (fast) — string-scan for proto filenames and message
names. No protobuf decoder required.
Full FileDescriptorProto extraction — walks the embedded descriptor
blobs in ngfx-replay.exe, decodes them with
google.protobuf.descriptor_pb2, and builds a DescriptorPool so any
message can be looked up by FQN and dynamically instantiated. Recovers
all 22 .proto files + 648 messages including the critical
NV.EventParameters.Messages.PbFunctionCallDesc (which has the per-call
functionName + repeated PbArgument arguments that --metadata-functions
hides).
Tool
What it answers
ngfx_proto_schemas
Inventory of every .proto file (22+), Pb* message (~2000+), and FQN extracted from ngfx-replay.exe / ngfx-capture.exe / PylonReplay_PluginInterface.dll.
ngfx_proto_search
Regex-grep the inventory. E.g. pattern='RootParam' → PbRootParameter, PbRootDescriptor, PbRootParametersInfo, ...
ngfx_proto_describe
Full field-level schema for any message FQN (field name, number, type, repeated, nested). Backed by extracted FileDescriptorProto blobs.
ngfx_proto_list_messages
List every FQN in the decoded schema pool (including nested types), optionally regex-filtered.
ngfx_proto_extract_descriptors
Re-extract FileDescriptorProto blobs from a Nsight binary and rebuild the in-process schema registry. Call once after upgrading Nsight.
Magic check (nlypelif = "Pylon file"), SHA-256, tentative header field interpretation. See docs/CAPTURE_FORMAT.md.
ngfx_capture_lz4_decompress
Attempt LZ4-block decompression of a byte range from a capture file.
ngfx_decode_protobuf_wire
Generic protobuf-wire-format decoder over a byte range (returns top-level fields without needing the schema).
Direct .ngfx-gfxcap decoder (RE-derived, no UI required)
Decodes the capture wrapper format end-to-end — no ngfx-replay /
ngfx-ui roundtrip needed for the metadata layer. The wrapper is fully
reverse-engineered: nlyp file-magic, then a sequence of chunks each
prefixed by a 48-byte mini-header (elif magic + version + compression
flag + compressed/uncompressed sizes + chunk-id + self-offset), payload
either LZ4-block compressed or stored, 16-byte aligned. The file ends
with a TOC region of elif-magic records pointing back to chunk
offsets. One chunk holds a serialised NV.PbTableOfContents with the
UUID, frame counts, GPU info, primary API, and lists of
FunctionInfoChunkIds + ResourceInfoChunkIds.
Pull a single chunk and decompress its LZ4 payload to raw bytes.
ngfx_capture_search_payloads
Search decompressed chunk payloads for shader names, hashes, or raw hex bytes when metadata-objects is too shallow.
ngfx_capture_shader_chunks
Find embedded DXBC/DXIL shader chunks and compute hash candidates from a saved capture.
ngfx_capture_chunk_references
Search decompressed chunks for references to a shader chunk id, hash, PDB path, or name.
ngfx_capture_decode_events
Best-effort per-event decode (limited — see caveat below).
ngfx_capture_event_args
Single-event arg lookup. Same shape as the C++-Capture-derived ngfx_cpp_capture_event_args once the FunctionInfo binary layout is fully RE'd.
Caveat (work in progress). The chunks listed by
FunctionInfoChunkIds hold a binary fixed-stride table, not
PbFunctionCallDesc protobuf messages — Nsight stores the per-event
arg stream as packed C-style records, not protobuf. The wrapper +
TOC are fully decoded so the metadata layer works headless today; the
per-record layout of FunctionInfo is the remaining RE work for direct
arg extraction. Until that's done, use the C++-Capture roundtrip path
above for arg-level queries.
ngfx-rpc custom transport client (RE-derived, partial)
ngfx-rpc.exe is the "Replayer UI Server" — a long-running process the
Nsight UI connects to over TCP / named-pipe / domain-socket. It speaks
a custom length-prefixed protobuf protocol (not standard gRPC, even
though its 30 .proto files contain ~50 Request/Reply message pairs
that look gRPC-shaped). The transport layer is fully decoded; the
per-message header encoding is decoded statically but not yet verified
over a live round-trip (see caveat below).
Dispatch model:(category u32, method u32) keyed 2-D handler table.
Method enums (already in the proto pool) include BinaryReplayMethod
with 110 entries — MethodApiInspectorStateRequest=33,
MethodRootParametersRequest=67, etc. System category ids are pinned from
ngfx-rpc.exe::SystemCategories.proto; Pylon replay uses its own category
namespace where CategoryBinaryReplay=1. The remaining live blocker is the
private namespace/session/slot binding the UI performs before BinaryReplay
requests are accepted.
Tool
What it does
ngfx_rpc_protocol_info
Return the decoded transport spec + the in-process method-enum tables (no live connection needed).
ngfx_rpc_transport_connect
Open a TCP / named-pipe / domain-socket connection to a running ngfx-rpc.exe and return a session handle.
ngfx_rpc_send_raw_frame
Send an arbitrary framed message and read the reply — escape hatch for experimenting with the protocol.
ngfx_frame_debugger_rpc_schema
Describe the private BinaryReplay pixel/resource history methods, ids, request schemas, and handle shapes.
ngfx_pixel_history
Call MethodPixelHistoryRequest (70) for an image handle + pixel coordinate, or preview the exact protobuf body.
ngfx_resource_access_history
Call MethodResourceAccessHistoryRequest (53) for an API data handle, or preview the request body.
ngfx_resource_revision_at_event
Derive the resource revision at an event from access history, optionally reusing a persistent RPC session and fetching resource info or image subresource data.
Keep a private frame-debugger RPC connection open across MCP calls.
ngfx_rpc_call_binary_replay
Call an arbitrary BinaryReplay method on a persistent frame-debugger RPC session.
Caveat (live-round-trip work in progress). ngfx-rpc's TCP server is
one-shot: it exits the moment the first client session ends. That makes
iterative "guess header → observe reply" probing impractical (the first
attempt at the most-likely MessageHeader layout crashes the server,
and relaunching takes ~30s). The structural header layout was recovered
statically from IDA (is_valid u8@+2, category u32@+32, method u32@+36, ticket_id u64@+48, sertype u32@+56, 60 bytes total) but isn't yet
confirmed on-wire. The two remaining angles are:
pktmon capture of a real ngfx-ui ↔ ngfx-rpc exchange — the
schema pool decodes every observed message; recovers handshake +
real method calls by observation.
IDA on NV::TPS::ProtoBufMessage::Serialize — read the exact
serialiser bytes the C++ side emits.
Both are documented in docs/RPC_PROTOCOL.md.
RPC probing, transcripts, and live-event mapping
Helpers that sit one layer above the raw wire protocol — for resolving
endpoints, recording real ngfx-ui ↔ ngfx-rpc exchanges, replaying
those transcripts offline, and mapping a hook-side ordinal back to a
saved-capture event_index.
Tool
What it does
ngfx_rpc_endpoint_resolve
Resolve an ngfx-rpc process (or explicit args) to TCP / named-pipe endpoint info.
ngfx_rpc_endpoint_probe
Resolve and probe an endpoint, classifying BinaryReplay readiness.
ngfx_rpc_find_live_events
Scan live BinaryReplay EventDetails to map hook draw ordinals to saved event_index values.
ngfx_rpc_decode_frame
Decode one ngfx-rpc transport frame or raw message body from hex.
ngfx_rpc_transcript_import
Import and decode a JSON / NDJSON / plain-hex transcript.
ngfx_rpc_session_binding_report
Summarize BinaryReplay session/slot binding evidence from a frame transcript.
ngfx_rpc_capture_open_sequence_report
Structured digest of the known + observed capture-open sequence.
ngfx_rpc_direct_export_binding_candidate
Derive a direct saved-C++ RPC binding candidate from a transcript.
ngfx_cpp_capture_saved_direct_rpc_export
Future direct FrameDebugger serialize-RPC export entrypoint (gated on the binding candidate).
ETW kernel-file capture of ngfx-ui ↔ ngfx-rpc
A short-lived ETW session that watches kernel file / pipe I/O so the MCP
can observe the real bytes exchanged between the Nsight UI and
ngfx-rpc.exe for offline decoding. Wraps logman + tracerpt.
Tool
What it does
ngfx_rpc_etw_environment
Probe for logman / tracerpt and report whether ETW capture is usable.
ngfx_rpc_etw_capture_start
Start a kernel-file ETW session targeted at the UI ↔ RPC I/O.
ngfx_rpc_etw_capture_stop
Stop a previously-started ETW session.
ngfx_rpc_etw_capture_summary
Convert an .etl trace to XML / CSV via tracerpt and summarize event counts.
PE-patch planner for ngfx-rpc.exe
One of the three documented workarounds for the private-bridge wall: a
non-destructive patch plan that adds logger trampolines into
ngfx-rpc.exe so its private serializers emit byte-level evidence at
runtime. Plans are emitted, not applied — apply with an external patcher
or via the IDA script tool below.
Tool
What it does
ngfx_rpc_pe_patch_plan
Plan (do NOT apply) a logger-trampoline patch on ngfx-rpc.exe.
ngfx_rpc_pe_patch_ida_script
Emit an IDA Pro 9.0 headless Python script that implements the plan.
Pylon private-bridge RE — saved-capture → C++ export
PylonPlugin.dll runs the UI activity bridge that maps activity id 3 to
Generate C++ Capture. The full headless replacement still depends on
either re-entering Pylon's private activity manager or wiring the direct
FrameDebugger Core RPC. These tools preserve the current RE evidence and
let an LLM iterate on each path safely.
Tool
What it does
ngfx_pylon_private_bridge_re_report
Report what remains to build the private Pylon/BinaryReplay executor.
ngfx_pylon_bridge_probe_plan
Return a concrete probe plan for Pylon's private activity-manager bridge.
ngfx_pylon_activity_manager_static_binding_report
Extract the static activity-manager / direct-call binding from cached IDA facts.
ngfx_pylon_bridge_helper_scaffold
Write a Frida / native helper scaffold for pinning the private executor.
ngfx_pylon_bridge_probe_run
Run the Pylon Frida probe and analyze collected private-binding events.
ngfx_pylon_bridge_probe_log_analyze
Analyze Frida probe output into binding hypotheses without re-running.
ngfx_pylon_private_binding_from_probe
Convert probe output into a private bridge binding JSON.
ngfx_pylon_direct_call_binding_from_probe
Build the experimental direct-call binding for PylonPlugin!sub_180116CD0.
ngfx_pylon_frida_direct_call_run
Run the experimental Frida direct re-entry call into sub_180116CD0.
ngfx_pylon_private_bridge_invoke
Guarded entrypoint for invoking the future native Pylon bridge.
ngfx_pylon_saved_cpp_export
Package the private Pylon saved-capture C++ export inputs.
ngfx_private_executor_readiness_report
Report whether Pylon or direct-RPC private export is ready to invoke.
ngfx_private_executor_evidence_bundle
Bundle Pylon / RPC private-executor evidence into one artifact.
Saved-capture → C++ Capture autonomy + route picker
Pickers and one-shot orchestrators that turn the saved-capture export
into a chain you can drive end-to-end without the UI. Use
ngfx_deep_capture_capability_report (above) first to decide whether
this route is worth attempting on the current install.
Tool
What it does
ngfx_cpp_capture_pick_install
Pick the newest installed Nsight whose Generate C++ Capture can run against this capture.
ngfx_cpp_capture_compatibility_check
Check whether a saved capture is replayable by a given install.
ngfx_cpp_capture_route_probe
Probe the installed Nsight to decide which saved-capture → C++ route to try.
ngfx_cpp_capture_against_replay
Run Generate C++ Capture against ngfx-replay.exe replaying a saved capture.
ngfx_cpp_capture_recapture_plan
Emit the ngfx-capture.exe command that re-captures the original application.
ngfx_capture_recapture_with_install
Re-run the captured application via the picked install's ngfx-capture.exe.
ngfx_cpp_capture_full_autonomy
One-shot autonomous chain for saved-capture → C++ project → validation + indexing.
Tool
What it answers
ngfx_open_capture
Register a .ngfx-gfxcap and get a session handle.
ngfx_list_captures / ngfx_close_capture
Manage open capture handles.
ngfx_find_recent_captures
Search the default Nsight output dirs (and any extras) for recent capture / gputrace files. Newest first.
ngfx_list_captures_in_dir
Enumerate captures under any directory.
ngfx_capture_summary
Parsed ngfx-replay --metadata (cached per mtime).
ngfx_capture_objects
Full JSON of every API object recorded (--metadata-objects).
ngfx_capture_functions
Recorded function stream (--metadata-functions) — raw lines.
ngfx_capture_logs
Embedded application + driver log messages.
ngfx_capture_screenshot
Write the embedded final-present screenshot to PNG/TGA/BMP/JPG.
ngfx_capture_diff
Diff the parsed summaries of two captures.
Fine-grained event queries (built on a SQLite index of the function stream)
Tool
What it answers
ngfx_index_events
Build / refresh the per-capture function index.
ngfx_find_events
"All draws between events 2100 and 2480", "every vkCmdPipelineBarrier2", "every Dispatch* in the first 500 calls".
ngfx_get_event
Full per-call record by index.
ngfx_event_histogram
Histogram by name or kind (draw / dispatch / copy / barrier / present / ray_tracing / sync / set_state / other).
ngfx_find_calls_by_arg
"Every call that mentions this resource handle / name".
ngfx_event_query
Read-only SQL (SELECT / WITH) against the index.
Replay (ngfx-replay.exe)
Tool
What it does
ngfx_replay_run
Replay a capture with full control: loop count, perf-report-dir, device selection (name / vendor / index), present mode, vsync, multibuffering, reset mode, …
ngfx_replay_screenshot
Dump per-frame rendered output during replay (uses RE-discovered --replay-screenshot* flags). No UI required.
Some Nsight builds emit GPU Trace as a binary WRPV container rather than
the documented zip. These tools probe that format directly without
needing to extract it first.
Tool
What it does
ngfx_gputrace_wrpv_search
Search a binary WRPV .ngfx-gputrace for needles (strings or hex).
ngfx_gputrace_wrpv_strings
Extract printable strings from a WRPV report with byte offsets.
ngfx_gputrace_wrpv_sections
Best-effort listing of header-like fields in a WRPV report.
ngfx_gputrace_wrpv_table_preview
Hex + ASCII preview of length bytes at offset inside a WRPV report.
ngfx_gputrace_shader_bindings
Search a WRPV report for shader binding evidence (pipeline, root params, descriptor heaps).
Generate C++ Capture → build → run
Nsight 2026's durable replacement path for D3D12/Vulkan persistence is
Graphics Capture (ngfx-capture / ngfx-replay) plus Graphics Debugger live
replay. C++ Capture is still useful when it emits a project because the MCP
can index generated source for per-call arguments, but the saved-capture
exporter is private UI/plugin code and some Nsight builds can refuse D3D11/D3D12
C++ serialization with guidance to migrate to Graphics Capture. Use
ngfx_deep_capture_capability_report first when deciding whether C++ export,
live replay RPC, GPU Trace-on-replay, or raw .ngfx-capture decoding is the
right next step.
The CLI activity (ngfx --activity 'Generate C++ Capture') requires the
original application to launch — it can't run against a saved capture.
The MCP also exposes the UI-driven path for that case (see next section).
Tool
What it does
ngfx_cpp_capture_launched
Run the Generate-C++-Capture activity (CLI; relaunches the app).
ngfx_cpp_capture_dump
One-stop C++ capture dump helper: live app via CLI, or saved .ngfx-gfxcap via UI-assisted export, then optional call/PSO indexing.
ngfx_cpp_capture_saved_bridge_re_analyze
Run targeted IDA passes over Nsight's private saved-capture C++ export plugins.
ngfx_cpp_capture_saved_bridge_re_report
Summarize the recovered private serialize protocol, Pylon activity bridge, and remaining headless gap.
ngfx_cpp_capture_saved_pylon_handoff_preview
Emit the pinned Pylon platform-launcher map for saved-capture Generate C++ Capture: ngfx-replay.exe, quoted capture argv, extra replay args, environment string, and JsonProject['launcher'] settings.
ngfx_cpp_capture_saved_direct_rpc_plan
Emit the recovered FrameDebugger serialize request + file-transfer callback plan for the direct RPC route.
ngfx_cpp_capture_saved_file_transfer_apply
Apply one decoded FrameDebugger open/append/close file-transfer notification to disk for the direct RPC executor.
ngfx_cpp_capture_saved_output_dir_setting
Preview or write the candidate Qt/QSettings Serialization Save Directory value used by BattlePlugin.
ngfx_cpp_capture_saved_ui_automation_attempt
Best-effort pywinauto UI fallback for the Generate C++ Capture dialog, with structured blockers if automation is unavailable.
ngfx_cpp_capture_saved_headless_attempt
One entrypoint that tries the pinned Pylon bridge, direct RPC route, and UI fallback, then validates/indexes any project that appears.
ngfx_cpp_capture_saved_export_validate
Validate an emitted C++ Capture project, compare against capture metadata when available, and build call/PSO indexes.
ngfx_cpp_capture_saved_artifact_bundle
Bundle capture/export validation/project artifacts into a zip for autonomous handoff and review.
ngfx_cpp_capture_find_solution
Locate the produced .sln.
ngfx_cpp_capture_build
MSBuild the project (auto-discovers MSBuild via vswhere).
ngfx_cpp_capture_run
Run the produced exe and capture its output.
The saved-capture → C++ path is still private NVIDIA plugin code. The RE
tools above preserve the current evidence: BattlePlugin sends
PbSerializeRequestMessage through the FrameDebugger service and handles file
transfer notifications, while PylonPlugin exposes the UI activity bridge
that maps activity id 3 to Generate C++ Capture. The Pylon argv/config
handoff is pinned now: the bridge uses ngfx-replay.exe, passes the saved
capture as the first quoted argument, appends flattened replay-option args,
passes a semicolon-joined environment string, and persists the platform map
under JsonProject['launcher']. The remaining fully-headless gap is invoking
Pylon's private activity manager outside the UI process, or completing the
direct FrameDebugger Core RPC namespace/session binding.
Nsight's CLI (ngfx-replay --metadata-functions) returns function NAMES
per event but no argument values — it's a deliberate design choice.
To answer "what's bound at root parameter N of event G?" or "which CBV
did this draw use?" you need argument values.
The workflow these tools enable:
Open a saved capture in the Nsight UI (which CAN run Generate C++
Capture on saved captures, unlike the CLI activity).
Click File → Activity → Generate C++ Capture, pick an output dir.
The MCP parses the emitted .cpp files and indexes every command-list
/ command-buffer call into SQLite, keyed by a synthetic event_index
that matches --metadata-functions order.
Per-event queries — full structured args for ~25 common
D3D12/Vulkan/OpenGL descriptor / draw / dispatch calls.
ngfx_cpp_capture_descriptor_bindings walks backwards from any
draw/dispatch to reconstruct the full root-param + descriptor heap +
CBV/SRV/UAV + VBV/IBV + RT state in effect at that event — the
missing-piece answer for "what's bound here?"
Tool
What it does
ngfx_cpp_capture_open_in_ui
Open a saved capture in ngfx-ui.exe with step-by-step prompts for the human.
ngfx_cpp_capture_wait_for_project
Poll a directory until the generated .sln lands and its size stabilises.
ngfx_cpp_capture_index_calls
Walk all .cpp files in a generated project, parse command-list calls, write a SQLite index to <project>/.ngfxmcp_cpp_calls.db.
ngfx_cpp_capture_event_args
Single-event lookup (function name, raw + structured args, source file:line).
ngfx_cpp_capture_query_calls
Filtered query: kind / api / name / regex / contains / event range.
ngfx_cpp_capture_descriptor_bindings
Reconstruct full bound state at an event by scanning backwards (D3D12 root params + descriptor heaps + IA/OM/RTs; Vulkan pipeline + descriptor sets per first_set + VB/IB/push constants).
ngfx_cpp_capture_sql
Read-only SELECT/WITH escape hatch against the index.
ngfx_capture_descriptor_heap_timeline
Per-heap timeline of descriptor-related D3D12 calls in event order.
ngfx_capture_root_signature_ranges
Parse every D3D12 root-signature blob referenced by the C++ project (root params + descriptor-table ranges).
ngfx_capture_root_signature_lookup
Resolve a shader register (e.g. t0 in space 0) to the root-parameter index that satisfies it.
The same parser is used by ngfx_find_calls_by_arg and by
ngfx_resolve_handle when a sibling C++-Capture index is present.
Capture-stream diff (event-level)
Tool
What it does
ngfx_capture_diff
Diff the parsed --metadata summaries of two captures (high-level: device, frame counts, version).
ngfx_event_stream_diff
Deeper: diff the per-event function streams via LCS. Returns per-function histogram delta, per-kind histogram delta, contiguous insert/delete/replace clusters, and (if both captures have a C++-Capture index) per-event arg diffs.
ngfx_function_stream_diff
Lightweight name-only diff over raw --metadata-functions output.
PSO → DXBC / SPIR-V hash mapping
Nsight's CLI does not expose the link between a PSO (D3D12 pipeline /
Vulkan VkPipeline) and the shader bytecode hashes it uses. The protobuf
schema does have it (NV.Pylon.Replay.PbPipelineShaderStageInfo —
fields pipeline, driverAppHash, stage) but extracting it from a
saved .ngfx-gfxcap is part of the in-progress capture decoder.
The path that works today: parse the Generate C++ Capture emitted
source. Shader bytecode is emitted as flat static const unsigned char
arrays — DXBC blobs have the Microsoft compiler's 128-bit MD5 hash baked
in at bytes 4..20 of the container (the exact bytes Nsight / PIX /
RenderDoc display as the shader identity). For SPIR-V we compute SHA-1
of the blob so Vulkan shaders still get a stable identity. We also compute
ShaderToggler's hash for every blob: CRC32 over the full raw shader
bytecode, reported as both 8 hex digits and unsigned decimal.
PSO creation calls (CreateGraphicsPipelineState /
CreateComputePipelineState / vkCreateGraphicsPipelines /
vkCreateComputePipelines / vkCreateRayTracingPipelinesKHR) reference
those byte-array symbols (D3D12) or vkCreateShaderModule handles
(Vulkan). The indexer matches them up.
Tool
What it answers
ngfx_pso_index
Walk a C++-Capture project, parse every shader byte-array + every PSO creation call, write shader_blobs + pso_shaders tables to the existing C++-Capture index DB.
ngfx_pso_get
Look up one PSO's full stage map: each stage → {shader_symbol, format (dxbc/dxil/spirv), hash_hex, hash_source, shader_toggler_crc32, declared_byte_count, head_hex}.
ngfx_pso_list
Enumerate every indexed PSO with a one-line stage summary (VS:g_VS_xxx, PS:g_PS_yyy).
ngfx_pso_find_by_shader
Reverse lookup: given a shader symbol, DXBC/SPIR-V hash, or ShaderToggler CRC32, which PSOs use it (and as which stage)?
ngfx_shader_blobs_list
Enumerate every indexed shader byte-array (filterable by format, DXBC/SPIR-V hash, or ShaderToggler CRC32).
ngfx_shader_blobs_find_crc32
Find shader byte-arrays by ShaderToggler CRC32, accepting either hex (1cf439e7) or decimal.
ngfx_shader_blob_dump
Write a matched generated-C++ shader byte-array back to disk as raw DXBC/DXIL/SPIR-V bytes.
Shader visual-bug triage
These tools compose C++-Capture event args, PSO identity, descriptor state,
and IDA-derived Nsight RE facts into reports an LLM can use to localise a
visual bug before patching shaders.
Tool
What it answers
ngfx_shader_triage_plan
Concrete capture/index/compare/probe plan for a visual bug handoff.
ngfx_eye_issue_dump_report
Nsight-only dump report for the right-eye issue: capture TOC, sidecar status, dump-only blockers, and next actions.
ngfx_eye_issue_event_signatures
Candidate left/right event pairs from saved metadata-functions when only the .ngfx-capture dump exists.
ngfx_eye_event_index
Classify C++-Capture events as left/right/both/unknown using stereo regexes, viewport/scissor half hints, and inherited state.
ngfx_compare_eye_passes
Left/right count deltas for draws, dispatches, copies, and ray-tracing work.
ngfx_find_missing_eye_dispatches
Dispatch/ray-tracing asymmetries, useful for missing producer work before a bad draw.
ngfx_event_state
One event plus surrounding calls, descriptor/root state, render targets, recent writes, and PSO details.
ngfx_trace_resource_lineage
Every indexed call mentioning a resource/symbol, bucketed by create/bind/write/copy/dispatch/draw/barrier role.
ngfx_pso_bind_trace
SetPipelineState / vkCmdBindPipeline binds and the following draw/dispatch work, even when creation hooks missed the PSO.
ngfx_pso_swap_harness_plan
Generate a D3D12 draw-time PSO swap harness plan and optional C++ snippet files for right-eye-only shader patch trials.
ngfx_shader_probe_plan
Probe variants for terms such as t5, t8, t9, screenTile, SV_Position, View[148], and volumeUV.
ngfx_shader_bug_triage
Single LLM-ready report from handoff, capture path, C++ index, suspect PSO/hash/CRC, and ROI.
Autonomous shader-fix loop helpers
Tool
What it answers
ngfx_sn2_repro_plan / ngfx_sn2_repro_run
Build or run the Subnautica 2 launch-script repro with the expected capture/log artifacts.
ngfx_cpp_capture_from_saved_capture
Saved-capture C++ export wrapper around the best available UI-assisted path.
ngfx_pair_eye_events
Pair classified left-eye and right-eye events and report missing counterparts.
ngfx_resolve_shader_slots
Resolve shader slots such as t5/t8/t9 to root-param evidence when a slot map or descriptor state is available.
ngfx_descriptor_resource_candidates
Score likely resource handles for shader slots from a private descriptor-state RPC reply.
ngfx_trace_roi_history
Generate or execute a grid of private pixel-history requests over a bad ROI.
ngfx_resource_producer_graph
Build a best-effort read/write producer graph for named resources.
ngfx_import_uevr_trace
Import NDJSON/JSON/CSV UEVR runtime hook traces into a summary or SQLite DB.
ngfx_pso_rehydration_plan
Generate a C++ plan/snippet for cloning a graphics PSO with patched shader bytecode.
ngfx_shader_probe_execution_plan
Emit the closed-loop run steps for a specific shader probe.
ngfx_diff_hdr_roi
Diff PFM/raw-float HDR ROI data without clamping to 8-bit.
ngfx_autofix_loop_plan
Return the autonomous patch/test/scoring loop.
ngfx_validate_fix_claim
Evidence gate for accepting/rejecting an automated visual-fix claim.
ngfx_shader_fix_regression_score
Score before/after fix metrics with repeatability, left-eye drift, event-sequence, and PSO coverage gates.
ngfx_fix_attempt_log
Append-only JSONL log of fix attempts (inputs, scores, verdicts).
ngfx_fix_claim_evidence_bundle
Bundle a fix-claim's evidence into a single zip for review.
Resource write history & producer lineage
Static, event-order analyses built on the C++-Capture index, useful for
"who wrote to this render target before the bad draw?" and for diffing
left/right eye resource histories.
Tool
What it does
ngfx_resource_write_history
Every write to a named resource in event order — render targets, dispatches, copies, barriers.
ngfx_resource_write_history_pair_diff
Diff the write timelines for a LEFT/RIGHT resource pair.
ngfx_resource_producer_lineage
Recursively trace which draws produced a given render-target resource.
ngfx_producer_lineage_pair_diff
Trace LEFT and RIGHT producer lineages and diff them level-by-level.
ngfx_copyrect_t0_resolution_report
Resolve actual sampled state for paired left/right CopyRectPS draws.
Subnautica 2 fog & CopyRectPS automation (worked-example shader-fix harness)
A concrete, end-to-end shader-fix harness for the SN2 right-eye fog and
CopyRectPS bugs. These tools double as a reference template for wiring
a fix loop against any specific game.
SN2 fog (VoxelizePS / VoxelizeGS)
Tool
What it does
ngfx_sn2_fog_artifacts
Locate the latest clean r.Fog on/off and VoxelizePS/VoxelizeGS artifacts.
ngfx_sn2_fog_signal_report
Evaluate the clean r.Fog differential for the VoxelizePS/VoxelizeGS bug.
ngfx_sn2_fog_fix_plan
Return the autonomous shader/runtime plan for fixing the SN2 fog signal.
ngfx_sn2_fog_descriptor_probe_plan
Build live BinaryReplay requests for resolving fog descriptor / resource state.
ngfx_sn2_fog_slot_candidates
Resolve VoxelizeGS/VoxelizePS slots from a live descriptor-state reply.
ngfx_sn2_fog_probe_manifest
Write or return the GS-first SN2 fog probe manifest for the fix loop.
ngfx_sn2_fog_live_state_probe
Collect live Nsight state for one SN2 fog lead-draw BinaryReplay event.
SN2 CopyRectPS (right-eye texture copy)
Tool
What it does
ngfx_sn2_copyrect_artifacts
Locate SN2 CopyRectPS trace and shader-inspection artifacts.
ngfx_sn2_copyrect_signal_report
Trace CopyRectPS source texture, destination target, and producer evidence.
ngfx_sn2_copyrect_fix_plan
Return the Nsight-driven fix plan for the SN2 CopyRectPS path.
ngfx_sn2_copyrect_descriptor_probe_plan
Build live BinaryReplay requests for resolving CopyRectPS t0/s0 and target state.
ngfx_sn2_copyrect_slot_candidates
Resolve CopyRectPS t0/s0 slots from a live descriptor-state reply.
ngfx_sn2_copyrect_t0_source_compare
Compare live left/right CopyRectPS PS t0 resources after descriptor-state resolution.
ngfx_sn2_copyrect_pair_analysis
Compare left/right CopyRectPS draws and emit live-probe targets.
ngfx_sn2_copyrect_right_eye_issue_report
Report the strongest same-frame CopyRectPS evidence for the right-eye bug.
ngfx_sn2_copyrect_source_lineage_report
Mine saved CopyRectPS resource lineage while preserving the table-scan descriptor caveat.
ngfx_sn2_copyrect_runtime_instrumentation_plan
Runtime hook manifest for proving CopyRectPS t0 and rect state.
ngfx_sn2_copyrect_live_state_probe
Collect live Nsight state for one CopyRectPS BinaryReplay event.
ngfx_sn2_copyrect_live_pair_probe
Probe paired left/right CopyRectPS events and resolve whether actual PS t0 matches.
Object handle / UID resolver
"What wrote to this buffer?" without the GUI. Given a uid or canonical
name (e.g. Buffer_91), cross-references the objects index, the events
index, and (when present) the C++-Capture index.
Tool
What it does
ngfx_resolve_handle
Find an object's create call + every event that mentions it, bucketed by role (create / write / bind / draw / dispatch / barrier / destroy / other). Degrades to "create call only" when a C++-Capture index isn't built for the capture.
Frame cost analysis (top-N expensive actions)
Tool
What it does
ngfx_top_n_costs
Top-N rows by GPU time across all CSVs in a ngfx-replay --perf-report-dir output, or a .nsight-gputrace archive (auto-unzips). Sniffs column names (no hardcoded schema) and normalises units (ns/µs/ms/s). Filters: kind_filter, name_regex, csv_basename_hint.
Aftermath / Remote / RPC
Tool
What it does
ngfx_aftermath_control
Configure Aftermath crash-dump generation.
ngfx_aftermath_monitor_start
Watch for GPU crashes/hangs in the background.
ngfx_aftermath_format
Format an existing crash dump.
ngfx_remote_monitor_start
Start nv-nsight-remote-monitor headless for remote UI debugging.
ngfx_rpc_start
Start ngfx-rpc.exe (replayer RPC server) on TCP / named pipe / domain socket.
Layer (un)install for Vulkan / VulkanSC / OpenXR
Tool
What it does
ngfx_layer_list
List every layer-install batch script shipped with Nsight Graphics and whether each is present.
ngfx_layer_install
Run a layer (un)install script. Supports per-user + system-wide (global_install=True).
NGFX in-app SDK (header-only C/C++ runtime)
Tool
What it does
ngfx_sdk_reference
Enumerate every header in the SDK and its parsed NGFX_* function declarations + briefs.
ngfx_sdk_grep
Regex search across the NGFX include tree.
ngfx_sdk_header_text
Return the raw text of any SDK header (e.g. NGFX_GPUTrace_D3D12.h).
ngfx_sdk_snippet
Codegen a ready-to-paste C++ snippet for (activity, api) — e.g. (GPUTrace, Vulkan) → an init + start/stop pair.
IDA Pro headless RE bridge
The shipped headers cover in-app capture/trace control, but saved-capture
frame-debugger state, pixel history, resource history, and several replay/RPC
paths live behind Nsight's internal binaries. The MCP can drive IDA Pro
headless to cache compact JSON facts for those gaps.
Tool
What it does
ngfx_ida_environment
Discover IDA Pro/Home/Free installs and list known Nsight RE targets. Override with NSIGHT_GRAPHICS_MCP_IDA.
ngfx_ida_analyze_binary
Run IDA headless over a target such as ngfx_rpc, ngfx_replay, frame_debugger_native, frame_debugger_d3d12, or frame_debugger_vulkan; exports strings, xrefs, selected functions, and bounded Hex-Rays pseudocode into the MCP cache.
ngfx_ida_search_facts
Regex-search cached IDA facts without re-running IDA.
ngfx_ida_fact_summary
Summarize a facts JSON.
ngfx_ida_command_preview
Show the exact headless command shape without running it.
ngfx_shader_debug_re_status
Check whether the RE facts needed for shader-debug automation are cached and show the implementation sequence for pixel history, resource history, event state, and shader variant testing.
Manage long-running background processes spawned by any of the tools above.
ngfx_raw
Invoke any of the Nsight tools (ngfx, ngfx_capture, ngfx_replay, ngfx_rpc, ngfx_ui, aftermath_*, remote_monitor, shaderdebugger_configurator, glslang) with arbitrary argv. The exe path is prepended automatically.
How big is the surface?
252 MCP tools (+ 4 prompts) as of this writing, grouped by the sections below.
Run nsight-graphics-mcp --list-tools (or import the package and inspect
server) for an up-to-date enumeration.
(Set NSIGHT_GRAPHICS_MCP_INSTALL_ROOT only if auto-discovery isn't
finding the right install — pass the directory that contains
host/windows-desktop-nomad-x64/.)
7. Enable Vulkan capture layer for the current user
ngfx_layer_list()
ngfx_layer_install(layer="vk_ngfx_capture")
# ... run your Vulkan app, capture via F11, then:
ngfx_layer_install(layer="vk_ngfx_capture", uninstall=True)
and writes both the dump and a SQLite DB (<capture>.ngfxmcp/functions.db)
next to the capture. Schema:
calls(
idx INTEGER PRIMARY KEY,
name TEXT,
args TEXT,
ret TEXT,
kind TEXT, -- draw|dispatch|copy|barrier|present|ray_tracing|sync|set_state|other
line INTEGER,
raw TEXT
);
The index is keyed by the capture's mtime, so subsequent re-captures
auto-invalidate it.
Caveats
Windows only. The Nsight Graphics CLIs are Win32-native (Windows
10 / 11 x64).
Nsight Graphics must be installed. Set
NSIGHT_GRAPHICS_MCP_INSTALL_ROOT if auto-discovery doesn't pick the
right version.
The function-stream parser is regex-based against ngfx-replay's
human-readable output. Lines that don't match the Name(args) shape
are bucketed under unrecognised_lines and remain accessible via
ngfx_capture_functions (raw passthrough).
Some interactive UI features — the per-shader source profiler scroll,
PSO browser, screenshot scrubber, frame-debugger pixel history — are
not fully replicable headless. Use ngfx_open_in_ui for those.
System-wide layer install (global_install=True) requires running the
MCP host elevated.
The DirectX Shader Compiler (dxc.exe) is not always shipped with
Nsight Graphics; install it separately if ngfx_dxc_compile reports it
missing.
Layout
src/nsight_graphics_mcp/
config.py # install / SDK / per-tool discovery + cache paths
cli.py # generic subprocess wrappers (sync + async + background)
session.py # capture / gputrace / launch session registries
capture_info.py # ngfx-replay --metadata* parsers
captures.py # capture-dir discovery + diff (Recent Captures parity)
capture_diff.py # event-stream LCS diff between two captures
capture_format.py # low-level .ngfx-gfxcap inspection (RE-derived)
capture_decoder.py # direct .ngfx-gfxcap header/chunk/TOC decoder
deep_capture.py # capability report for deep Nsight-only capture analysis
events.py # function-stream indexer (Event List parity)
gputrace.py # .nsight-gputrace zip + WRPV binary inspection
cpp_capture.py # MSBuild + run for Generate-C++-Capture output
cpp_capture_parser.py # walk emitted .cpp, index per-call args into SQLite
cpp_bridge_re.py # saved-capture → C++ export private-bridge RE helpers
proto_schemas.py # name-only protobuf schema inventory
proto_descriptors.py # full FileDescriptorProto extraction → DescriptorPool
rpc_client.py # ngfx-rpc.exe custom transport client (RE-derived)
rpc_trace.py # offline ngfx-rpc frame transcript decoder
frame_debugger_rpc.py # persistent private frame-debugger RPC sessions
etw_capture.py # logman/tracerpt ETW kernel-file capture wrappers
pe_patch_planner.py # PE-patch planner for ngfx-rpc.exe logger trampolines
ida_re.py # IDA Pro headless RE helpers
handle_resolver.py # object handle → create call + role-bucketed mentions
pso_resolver.py # PSO → DXBC/SPIR-V hash mapping (Nsight CLI gap)
frame_costs.py # Top-N by GPU time from perf-report dirs / gputrace zips
objects.py # object index (Resources / Pipelines pane parity)
project.py # .nsight-gfxproj XML authoring
shaders.py # glslang + DXC + shaderdebugger configurator wrappers
shader_debug.py # shader-debug orchestration (RE-cache gating + plans)
shader_triage.py # shader visual-bug triage composition layer
eye_issue.py # saved-capture stereo eye-issue triage
autonomous_shader_fix.py # deterministic helpers for an LLM-driven fix loop
layers.py # Vulkan/VKSC/XR layer (un)install scripts
sdk.py # NGFX in-app SDK header reference + codegen
ui.py # ngfx-ui.exe hand-off
watch.py # capture-dir watcher (for hotkey-driven flows)
redist.py # bundled D3D12 Agility SDK / DXC / DLSS / etc. inventory
doctor.py # one-shot health check
server.py # FastMCP server registering every tool
__main__.py # console entry point
tests/ # pytest suite — synthetic data for the parsers,
# real-binary tests for proto_descriptors when
# Nsight Graphics is installed locally.
docs/
CAPTURE_FORMAT.md # RE notes on the .ngfx-gfxcap wrapper
RPC_PROTOCOL.md # RE notes on ngfx-rpc.exe transport
NSIGHT_SHADER_DEBUG_AUTONOMY.md # current shader-debugging status/plan
License
MIT.
Full tool reference
Auto-generated from server.py docstrings. 252 tools organised by
the section comments in server.py — the order matches what you'd
discover scrolling the file.
ngfx_list_installs — List every Nsight Graphics install detected on this machine.
ngfx_deep_capture_capability_report — Rank Graphics Capture, live replay RPC, GPU Trace-on-replay, C++ Capture, and raw capture decoding for deep shader/render debugging from a saved dump.
ngfx_version — Return the version reported by ngfx.exe --version.
ngfx_list_activities — List the activity names that ngfx.exe accepts (parsed from --help).
Graphics Capture activity (via ngfx.exe)
ngfx_graphics_capture_launched — Run ngfx --activity 'Graphics Capture' --exe <exe> ....
ngfx_graphics_capture_attached — Same as ngfx_graphics_capture_launched but attaches to a running PID.
Headless Graphics Capture via ngfx-capture.exe
ngfx_capture_launched — Run ngfx-capture.exe directly (no Nsight UI required).
ngfx_capture_recapture — Recapture / recompress an existing .ngfx-capture / .ngfx-gfxcap with the current format.
ngfx_capture_recompress — Recompress an existing capture without re-running the application.
Capture session management + metadata
ngfx_open_capture — Register a capture file path as a session handle.
ngfx_list_captures — List all opened capture sessions.
ngfx_close_capture — (no docstring)
ngfx_capture_summary — High-level summary of a capture (runs ngfx-replay --metadata).
ngfx_capture_objects — Run ngfx-replay --metadata-objects: full JSON list of every API object recorded in the capture (devices, queues, pipelines, resources...).
ngfx_capture_functions — Dump the recorded function stream (ngfx-replay --metadata-functions).
ngfx_capture_logs — Dump captured application/driver log messages embedded in the capture.
ngfx_capture_screenshot — Write the embedded final-present screenshot to a file.
Replay (ngfx-replay.exe)
ngfx_replay_run — Replay a capture with ngfx-replay.exe and return its output.
ngfx_replay_bundle_extract — Extract a bundled-replayer capture's contents to a directory without running the replay.
ngfx_replay_metadata — Direct passthrough to ngfx-replay --metadata (parsed key/value).
GPU Trace Profiler
ngfx_gputrace_archs — Return the list of GPU architectures accepted by --architecture.
ngfx_gputrace_attached — Attach GPU Trace to a running process by PID. Defaults to hotkey-driven.
ngfx_gputrace_capture_replay — Run GPU Trace Profiler against ngfx-replay.exe for a saved Graphics Capture, using replay-begin/replay-end triggers.
GPU Trace report session management
ngfx_open_gputrace — Register a .nsight-gputrace path as a session handle.
ngfx_list_gputraces — (no docstring)
ngfx_close_gputrace — (no docstring)
ngfx_gputrace_inspect — Best-effort inspection of a .nsight-gputrace file.
ngfx_gputrace_shader_pipeline_search — Search shader/pipeline GPU Trace data for a shader hash, name, or entry point.
Generate C++ Capture activity
ngfx_cpp_capture_launched — Run ngfx --activity 'Generate C++ Capture' ....
ngfx_cpp_capture_saved_bridge_re_analyze — Run the targeted IDA passes for the private saved-capture -> C++ bridge.
ngfx_cpp_capture_saved_bridge_re_report — Summarize current RE evidence for fully headless saved C++ export.
ngfx_cpp_capture_saved_pylon_handoff_preview — Preview the pinned Pylon launcher settings for saved-capture Generate C++ Capture.
ngfx_cpp_capture_saved_direct_rpc_plan — Preview the direct FrameDebugger serialize-RPC request/callback plan.
ngfx_cpp_capture_saved_file_transfer_apply — Apply one FrameDebugger serialize file-transfer notification to disk.
ngfx_cpp_capture_saved_output_dir_setting — Preview or write the candidate QSettings output-dir value for C++ export.
ngfx_cpp_capture_saved_export_validate — Validate and index a saved-capture Generate-C++-Capture export.
ngfx_cpp_capture_saved_ui_automation_attempt — Best-effort pywinauto UI fallback for saved-capture C++ export.
ngfx_cpp_capture_saved_headless_attempt — Try all known saved-capture -> C++ export routes, then validate output.
ngfx_cpp_capture_saved_artifact_bundle — Bundle capture/export validation artifacts into one zip.
OpenGL Frame Debugger
ngfx_framedebugger_launched — Run ngfx --activity 'OpenGL Frame Debugger' ....
Launch / background process management
ngfx_launch_status — Status + recent stdout/stderr of a background launch.
ngfx_list_launches — (no docstring)
ngfx_launch_stop — (no docstring)
Remote monitor / RPC
ngfx_remote_monitor_start — Start nv-nsight-remote-monitor.exe headless on this machine so a remote Nsight UI can connect. Returns a launch handle — call ngfx_launch_stop to terminate it.
ngfx_rpc_start — Start ngfx-rpc.exe (the replayer UI server) headless.
ngfx_rpc_protocol_info — Return everything we know about the ngfx-rpc.exe custom wire protocol — handy as a self-describing reference for callers writing their own clients. The full derivation lives in docs/RPC_PROTOCOL.md (in this repo).
ngfx_rpc_transport_connect — Open one TCP transport connection to a running ngfx-rpc.exe and immediately close it. Useful as a smoke test: it verifies the server is reachable and that the 8-byte frame magic checks out.
ngfx_rpc_send_raw_frame — Low-level escape hatch: send one transport frame and (optionally) await one reply frame. Useful for protocol RE work.
ngfx_frame_debugger_rpc_schema — Describe the private BinaryReplay RPC methods used for pixel/resource history.
ngfx_pixel_history — Call Nsight's private BinaryReplay pixel-history method or preview the exact protobuf request.
ngfx_resource_access_history — Call Nsight's private resource-access-history method for one API handle.
ngfx_resource_revision_at_event — Derive a resource revision at an event from private resource history, with optional persistent-session reuse.
ngfx_rpc_open_capture_session — Open a persistent frame-debugger RPC session and optionally launch a capture.
ngfx_rpc_capture_session_status — List persistent frame-debugger RPC sessions, or summarize one handle.
ngfx_rpc_close_capture_session — Close a persistent frame-debugger RPC session.
ngfx_rpc_call_binary_replay — Call an arbitrary BinaryReplay method on an open frame-debugger RPC session.
Aftermath (crash-dump tools)
ngfx_aftermath_control — Run nv-aftermath-control.exe with the provided args.
ngfx_aftermath_monitor_start — Start nv-aftermath-monitor.exe in the background to watch for GPU crashes / hangs and write dump files.
ngfx_aftermath_format — Run nv-aftermath-format.exe against an existing crash dump.
Layer install helpers
ngfx_layer_list — List the Vulkan / VulkanSC / OpenXR layer install scripts shipped with the Nsight Graphics install, and whether each one is present.
ngfx_layer_install — Run a Nsight Graphics layer install script.
NGFX SDK helpers (in-app integration)
ngfx_sdk_reference — Enumerate every header in the NGFX in-app SDK, with parsed function declarations (name, params, brief) for each.
ngfx_sdk_grep — Regex-search across the NGFX header tree (returns matched filename, line number, and matched line text).
ngfx_sdk_snippet — Generate a C++ integration snippet for an (activity, API) pair.
ngfx_sdk_header_text — Return the raw text of an NGFX SDK header.
Escape hatch
ngfx_raw — Escape hatch — invoke any supported Nsight tool with arbitrary argv.
Capture-directory discovery + diff (parity with GUI 'Recent Captures')
ngfx_find_recent_captures — Look in the standard Nsight output directories (and optionally extra dirs) for recent capture / GPU-trace files. Newest first.
ngfx_list_captures_in_dir — Enumerate every capture / gputrace file under a directory.
ngfx_capture_diff — Diff the parsed --metadata summaries of two captures.
Function-stream indexer (Event List parity)
ngfx_index_events — Index a capture's function stream into a SQLite DB next to it.
ngfx_find_events — Filtered search over the indexed function stream.
ngfx_get_event — Look up a single call by index in the indexed function stream.
ngfx_event_histogram — Histogram of recorded calls grouped by name or kind.
ngfx_find_calls_by_arg — Search recorded calls by argument substring.
ngfx_gputrace_export_search — Search exported GPU Trace text/XLS files for shader names, hashes, or event text.
Nsight project file authoring
ngfx_project_create — Write a minimal Nsight project XML at path.
ngfx_project_read — Read an existing Nsight project XML.
ngfx_project_update — Mutate fields of an existing Nsight project file in-place.
C++ Capture build + run
ngfx_cpp_capture_find_solution — Locate the .sln produced by a Generate-C++-Capture run.
ngfx_cpp_capture_build — Invoke MSBuild on a Generate-C++-Capture output directory or .sln.
ngfx_cpp_capture_run — Run a Generate-C++-Capture exe to verify the repro still works.
ngfx_cpp_capture_dump — One-stop helper for producing a C++ Capture dump and indexing it. Uses the headless CLI for live app launches and the UI-assisted path for saved captures.
ngfx_cpp_capture_open_in_ui — Open a saved capture in ngfx-ui.exe so the human can run the UI's Generate C++ Capture activity against it (the CLI activity can't, it requires the original application to re-launch).
ngfx_cpp_capture_wait_for_project — Poll watch_dir until a Generate-C++-Capture project lands and its .sln stops growing. Returns the project root + the solution path.
ngfx_cpp_capture_index_calls — Walk a Generate-C++-Capture project, parse every command-list / command-buffer call, and index them into SQLite for per-event queries.
ngfx_cpp_capture_event_args — Look up one C++-capture event by its synthetic event_index.
ngfx_cpp_capture_query_calls — Filtered query against the indexed C++ call stream.
ngfx_cpp_capture_descriptor_bindings — Reconstruct the descriptor / root-parameter / vertex+index buffer / render-target binding state in effect at event_index by scanning backwards through the indexed C++ call stream.
ngfx_cpp_capture_sql — Read-only SELECT/WITH query against the C++ call index DB.
Shader compilation + Shader Debugger
ngfx_glslang_compile — Compile a GLSL / SPIR-V shader using glslang.exe (bundled).
ngfx_dxc_compile — Compile an HLSL shader via DXC.
ngfx_shaderdebugger_configure — Run nv-shaderdebugger-configurator.exe (use extra_args=['--help'] to discover flags).
UI hand-off
ngfx_open_in_ui — Spawn ngfx-ui.exe to open a capture / gputrace / project file in the full Nsight Graphics UI.
Capture watcher / wait-for-new-capture
ngfx_wait_for_new_capture — Poll one or more directories until a new capture (or GPU trace) lands, its size stabilises, then return its path.
Doctor / health check + tool-help introspection
ngfx_doctor — One-shot health check: install discovery, every tool path, layer scripts, output-dir writability, nvidia-smi driver/GPU info, and the Vulkan implicit/explicit-layer registry. Reports a list of issues you should fix before running captures.
ngfx_tool_help — Run <tool> --help (or --help-all for ngfx) to discover the exact flags supported by your installed version of any Nsight binary.
Function-stream raw sample + cross-capture diff
ngfx_function_stream_sample — Return the first head (and optionally last tail) raw lines of the recorded function stream.
ngfx_function_stream_diff — Diff the indexed function streams of two captures.
Triage macro
ngfx_capture_quick_triage — Run the full 'first look' pipeline on a capture in one call:
Redistributables + registry
ngfx_list_d3d12_redist — List the bundled D3D12 Agility SDK redistributable shipped with Nsight Graphics. Pass preview=True for the preview SDK.
ngfx_list_runtime_dlls — List the runtime DLLs (DXC, DXIL, Aftermath, WinPixEventRuntime, DirectStorage, NGX/DLSS) bundled in the Nsight Graphics host bin dir.
ngfx_registry_restore — Run the bundled RegistryRestore.ps1 to restore Nsight Graphics' registry keys to defaults.
Proto schema reference (extracted from ngfx-replay binary)
ngfx_proto_schemas — Return the protobuf schema inventory extracted from the Nsight binaries.
ngfx_proto_search — Regex-search the extracted protobuf schema for a name or FQN.
ngfx_proto_describe — Return the full field-level schema for a protobuf message extracted from Nsight's binaries.
ngfx_proto_list_messages — List every fully-qualified message name in the decoded schema pool.
ngfx_proto_extract_descriptors — Re-extract FileDescriptorProto blobs from a Nsight binary and rebuild the in-process schema registry.
Capture diff — "git diff for captures"
ngfx_event_stream_diff — Diff the per-event function streams of two captures (deeper than ngfx_capture_diff which only diffs the metadata summaries).
Object handle / UID resolver
ngfx_resolve_handle — Look up an API object by uid or name, find its create call, and enumerate every C++-capture event that mentions it — bucketed by role (create / write / bind / draw / dispatch / barrier / destroy / other).
PSO → DXBC / SPIR-V hash mapping
ngfx_pso_index — Walk a Generate-C++-Capture project and index PSO → shader-hash mappings into SQLite.
ngfx_pso_get — Look up one PSO's shader stages: each entry is {shader_symbol, format (dxbc/dxil/spirv), hash_hex, hash_source, shader_toggler_crc32, declared_byte_count, head_hex}.
ngfx_pso_list — List every indexed PSO with a one-line stage summary (VS:g_VS_xxx, PS:g_PS_yyy). Filter by api (d3d12/ vulkan).
ngfx_pso_find_by_shader — Reverse lookup: which PSOs use a given shader? Supply the C-level shader symbol (e.g. g_VS_0x1234), a DXBC/SPIR-V hash, or a ShaderToggler CRC32.
ngfx_shader_blobs_list — List indexed shader bytecode blobs from a C++-Capture project. Filter by format (dxbc/dxil/spirv/unknown), hash_hex (exact match), and/or shader_toggler_crc32.
ngfx_shader_blobs_find_crc32 — Find shader bytecode blobs by ShaderToggler CRC32, accepting either hex or decimal.
ngfx_shader_blob_dump — Dump one indexed shader bytecode blob to disk by shader symbol or ShaderToggler CRC32.
Shader visual-bug triage orchestration
ngfx_shader_triage_plan — Return the concrete MCP workflow for localising and fixing a shader visual bug.
ngfx_eye_issue_dump_report — Summarize saved-capture evidence, dump-only blockers, and the next Nsight-only actions for the right-eye issue.
ngfx_eye_issue_event_signatures — Build candidate left/right event pairs from name-only saved function metadata.
ngfx_eye_event_index — Classify C++-Capture events as left/right/both/unknown using stereo regexes, viewport/scissor half hints, and inherited state.
ngfx_compare_eye_passes — Compare left/right draw/dispatch/copy counts from a C++-Capture index.
ngfx_find_missing_eye_dispatches — Find dispatch/ray-tracing asymmetries between classified eyes.
ngfx_event_state — Return a draw/dispatch event, nearby calls, bound descriptors, and PSO info.
ngfx_trace_resource_lineage — Find C++-Capture calls that mention a resource/symbol and bucket by role.
ngfx_pso_bind_trace — Trace SetPipelineState/vkCmdBindPipeline and following draw/dispatch work.
ngfx_pso_swap_harness_plan — Generate a D3D12 draw-time PSO swap harness plan and optional C++ files.
ngfx_shader_probe_plan — Generate a targeted shader-probe plan for suspect terms such as t5/t8/t9.
ngfx_shader_bug_triage — Produce one LLM-ready shader-bug report from capture/index/handoff evidence.
ngfx_sn2_repro_plan — Build the exact Subnautica 2 launch-script repro command and expected artifacts.
ngfx_sn2_repro_run — Dry-run or execute the Subnautica 2 repro launch script with capture-friendly environment.
ngfx_cpp_capture_from_saved_capture — Export Generate-C++-Capture output from a saved capture via the available Nsight path.
ngfx_pair_eye_events — Pair left/right draw, dispatch, copy, and ray-tracing events and report missing counterparts.
ngfx_resolve_shader_slots — Resolve shader resource slots such as t5, t8, and t9 to root/descriptor evidence where available.
ngfx_descriptor_resource_candidates — Score likely resource handles for shader slots from a private descriptor-state RPC reply.
ngfx_trace_roi_history — Generate or execute private pixel-history requests for a grid over a suspect ROI.
ngfx_resource_producer_graph — Build a best-effort graph of resource producers/readers from a C++-Capture index.
ngfx_import_uevr_trace — Import UEVR hook traces from JSON, NDJSON, CSV, or key/value logs into summaries or SQLite.
ngfx_pso_rehydration_plan — Generate a C++ clone/recreate plan for testing patched shader bytecode in a graphics PSO.
ngfx_shader_probe_execution_plan — Emit the closed-loop steps for a concrete shader probe trial.
ngfx_diff_hdr_roi — Compare raw/PFM float image ROI data without 8-bit clamping.
ngfx_autofix_loop_plan — Return the autonomous patch/test/score loop used to drive repeated fix trials.
ngfx_validate_fix_claim — Reject or accept fix claims using improvement, repeatability, left-eye drift, and causality gates.
ngfx_shader_fix_regression_score — Score whether a shader-fix run is acceptable or regressed.
ngfx_top_n_costs — Return the top-N most expensive actions by GPU time across all CSVs in a ngfx-replay --perf-report-dir output, or a .nsight-gputrace archive.
Low-level capture-file inspection (RE-derived)
ngfx_capture_format_info — Structural inspection of a .ngfx-gfxcap file.
ngfx_capture_lz4_decompress — Experimental: attempt LZ4-block decompression of a byte range from a capture file. Useful for probing the chunk layout. Returns a hex preview of the decompressed bytes plus sizes; for unknown blocks, pass a generous uncompressed_size_hint (defaults to len(data) * 8).
ngfx_decode_protobuf_wire — Experimental: decode a byte range as generic protobuf wire format.
Direct capture-file decoder (header / chunks / TOC / events)
ngfx_capture_decode_header — Decode the wrapper header of a .ngfx-capture / .ngfx-gfxcap.
ngfx_capture_decode_chunks — List the first max_chunks chunks of a capture file.
ngfx_capture_decode_toc — Decode the NV.PbTableOfContents chunk of a capture file.
ngfx_capture_decompress_chunk_by_id — Locate the chunk whose kind (chunk-id) equals chunk_id and decompress it.
ngfx_capture_search_payloads — Search decompressed capture chunks for shader names, hashes, or raw hex bytes.
ngfx_capture_shader_chunks — Find embedded DXBC/DXIL shader blobs in a saved capture and return chunk IDs, strings, and hash candidates.
ngfx_capture_chunk_references — Search decompressed capture chunks for references to a chunk id or arbitrary byte/string needles.
ngfx_capture_decode_events — Best-effort scan for serialised PbFunctionCallDesc records.
ngfx_capture_event_args — Look up the per-event arguments at event_index via direct capture decoding.
Extra replay flags
N
Nsight Graphics
elliotttate·12 个星标·
MCP server for NVIDIA Nsight Graphics — wraps the full CLI surface (ngfx / ngfx-capture / ngfx-replay / Aftermath / NGFX SDK) and indexes captures into SQLite for fast LLM-driven analysis. 105 tools.
上次检查时间:2026-10-28。 MCP server for NVIDIA Nsight Graphics — wraps the full CLI surface (ngfx / ngfx-capture / ngfx-replay / Aftermath / NGFX SDK) and indexes captures into SQLite for fast LLM-driven analysis. 105 tools.