English | 简体中文

wpa-mcp

A C# MCP server that exposes Windows ETW (.etl) trace analyzers — CPU, wait, image-load, file / disk / mmap I/O — over any MCP-compatible client (Claude Code, Claude Desktop, Codex, Cursor). Domain-neutral: works on any Windows trace; commonly used to debug app startup, slow forks, AV-induced stalls, and disk-bound regressions.

Status — PoC. 54 tools live. Windows-only (TraceEvent kernel parsers are not portable). Apache-2.0.

See it in action: a real investigation — process creation 50× slower than baseline, root-caused via wpa-mcp's tools to multiple EDR stacks colliding on PsSetCreateProcessNotifyRoutineEx. Reproduced independently by two different LLM agents on the same trace.

Quickstart

Once installed (one-liner below), ask the agent in plain language and it picks the matching tools:

> Load this trace: C:\path\to\trace.etl
(load_trace; first call 30 s – 3 min as .etlx index is built; subsequent are
 instant.  Response includes a Capabilities map so you know upfront which
 keywords are present in the trace.)

> Which processes have the highest wait ratio?
(list_processes orderBy=wait_ratio — trace-resident processes auto-filtered out)

> For parent PID <X>, what was each fork's kernel-side gap?
(process_create_timing — one call gives kernel-window distribution across all
 children of one parent)

> Top wait stacks for PID <X> between <t0> and <t1>, with 20-bucket histogram
(wait_top_stacks — shows the Filter Manager / driver chain blocking the thread)

> Drill into "<frame!?>": who calls it?
(wait_caller_callee — caller / callee neighbours of the focus frame)

The same pattern works for CPU (cpu_top_functions → cpu_caller_callee), file / disk / mmap I/O, image loads, etc. Each "top" view has a matching "caller-callee" drill-down that takes a focus frame.

For an end-to-end walkthrough — symptoms, tool chain, evidence, root cause, recommendations — see docs/CASE_STUDIES.md.

Install

One-liner (no clone, no build)

PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/tooluse-labs/wpa-mcp/main/scripts/install.ps1) }"

Git Bash on Windows:

curl -fsSL https://raw.githubusercontent.com/tooluse-labs/wpa-mcp/main/scripts/install.sh | bash

Both routes do the same thing: download the latest GitHub Release zip (pre-built DLL), cache under %LOCALAPPDATA%\wpa-mcp\releases\<tag>\, and run the bundled setup.ps1. Auto-detects every MCP client on the machine (Claude Code / Codex / Claude Desktop) and registers wpa-mcp against each. .NET 8 runtime is auto-installed user-scope if missing. Subsequent runs are instant (cache hit).

Forward extra flags through the one-liner:

# PowerShell — pin tag, force a single client, set custom symbol path
iex "& { $(irm https://raw.githubusercontent.com/tooluse-labs/wpa-mcp/main/scripts/install.ps1) } -Tag v0.2.0 -InstallArgs @('-Client','claude-desktop','-SymbolPath','SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols')"

# Bash — flags after `bash -s --` go to install.ps1
curl -fsSL https://raw.githubusercontent.com/tooluse-labs/wpa-mcp/main/scripts/install.sh | bash -s -- -Tag v0.2.0

Uninstall (one-liner, symmetric)

Web-invokable, edits the same client configs in reverse. No download / cache touched.

iex "& { $(irm https://raw.githubusercontent.com/tooluse-labs/wpa-mcp/main/scripts/uninstall.ps1) }"

curl -fsSL https://raw.githubusercontent.com/tooluse-labs/wpa-mcp/main/scripts/uninstall.sh | bash

This removes the wpa-mcp entry from every detected MCP client. The cached release zip and symbol cache stay (delete %LOCALAPPDATA%\wpa-mcp\ and %LocalAppData%\WprMcp\Symbols\ to remove those).

Requirements

• Windows 10 / 11 (TraceEvent kernel APIs are Windows-only)
• .NET 8 — auto-installed user-scope by the installer if missing (uses Microsoft's official dotnet-install.ps1; no admin needed). Pass -SkipDotNetInstall to opt out.
• For symbol resolution: _NT_SYMBOL_PATH set, or use the symbol tools at runtime (see Configuration → Symbols).

git clone https://github.com/tooluse-labs/wpa-mcp
cd wpa-mcp
.\scripts\setup.ps1

git clone https://github.com/tooluse-labs/wpa-mcp
cd wpa-mcp
./scripts/setup.sh

Builds (Release) and registers wpa-mcp with every detected MCP client. Idempotent — re-run to update.

Common flags:

.\scripts\setup.ps1 -Client claude-desktop                    # force a specific client
.\scripts\setup.ps1 -SymbolPath "SRV*C:\Symbols*https://..." # custom _NT_SYMBOL_PATH
.\scripts\setup.ps1 -SkipBuild                                # use existing DLL

Uninstall from clone (also -CleanBuild to wipe bin/ obj/):

.\scripts\uninstall.ps1
.\scripts\uninstall.ps1 -CleanBuild

./scripts/uninstall.sh
./scripts/uninstall.sh -CleanBuild

Build:

git clone https://github.com/tooluse-labs/wpa-mcp
cd wpa-mcp
dotnet build -c Release
# DLL: src\WprMcp\bin\Release\net8.0\WprMcp.dll

Smoke-check:

dotnet src\WprMcp\bin\Release\net8.0\WprMcp.dll --version    # prints "WprMcp 0.1.0-poc"
dotnet test                                                   # runs the xUnit suite (needs fixtures, see CONTRIBUTING.md)

Then register with your MCP client. The DLL path must be absolute.

Claude Code — per-project (<project>/.mcp.json) or global (~/.claude.json):

{
  "mcpServers": {
    "wpa-mcp": {
      "command": "dotnet",
      "args": ["C:/Users/me/Dev/wpa-mcp/src/WprMcp/bin/Release/net8.0/WprMcp.dll"],
      "env": {
        "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols",
        "WPRMCP_CACHE_SIZE": "2"
      }
    }
  }
}

Or via the CLI helper:

claude mcp add wpa-mcp --scope user -- dotnet C:/Users/me/Dev/wpa-mcp/src/WprMcp/bin/Release/net8.0/WprMcp.dll

(Add -e _NT_SYMBOL_PATH=... for env vars.)

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json, same shape as above.

Codex / Cursor / other MCP-compatible clients — the server speaks stdio MCP; any client that accepts a command + args config works. Use the same JSON snippet.

Verify — after restart, the client exposes the tools as mcp__wpa-mcp__load_trace, etc. First call to load_trace on a fresh .etl takes 30 s – 3 min while the .etlx index is built (logged to stderr).

Tools

54 tools across 15 groups. All built on the same Microsoft.Diagnostics.Tracing.TraceEvent library PerfView uses, so the underlying analysis quality is identical — what changes is the surface (stdio MCP + JSON instead of a Windows GUI) and the addition of composite tools that package multi-step PerfView workflows into one call.

What wpa-mcp adds vs PerfView

• Agent-driven, not UI-driven. PerfView is a Windows GUI you click through; wpa-mcp is a stdio MCP server you talk to in plain language. Same data, no UI fatigue, easy to compose into a CI / regression script.
• Composite tools. diagnose_slow_startup, process_create_timing, image_load_top_gaps package multi-step PerfView workflows into one call.
• Capabilities-aware. Every tool's "won't return data" state maps to a single keyword bit in load_trace's Capabilities map — no more "why is this view empty" detective work in PerfView.
• Per-trace symbol recommendations. load_trace inspects modules in the trace and recommends which symbol servers to add. PerfView leaves symbol setup to the user.

Pattern

Always call load_trace first. It opens the .etl, builds (or reuses) the .etlx index, and returns a Capabilities map — a per-keyword presence check (HasCpuSamples, HasCSwitch, HasFileIo, HasDiskIo, HasImageLoad, HasHardFaults, HasStackWalks, HasVirtualAlloc, HasNetIo, HasRegistry, HasReadyThread, HasInterrupt, HasAlpc, HasThreadEvents, HasClrGc, HasClrJit, HasClrAlloc, HasClrException, HasClrContention, HasNtHeap). Every other tool's behaviour depends on those keywords.

Most groups follow the same three-tool shape: a summary (top-N flat rows), a stacks view (top-N call stacks weighted by the metric), and a caller-callee drill-down (given a focus frame, returns its caller / callee neighbours weighted by the same metric — same shape as PerfView's "Callers" / "Callees" tabs).

In the tables below, "PerfView equivalent" is the matching view in PerfView's GUI; entries tagged [Composite] combine multiple PerfView views into one call, [Manual filter] use raw events that PerfView's Events view exposes but doesn't pre-aggregate, and [Programmatic] replace a GUI dialog with structured JSON. The other ~45 tools are 1:1 mappings of PerfView views.

Meta

CPU stacks

Wait / blocked time (CSwitch-derived)

Requires the CSwitch kernel keyword (default WPR CPU profiles include it).

Image / DLL load

File / disk / mmap I/O

The three layers cover different parts of the I/O stack — diff them to localise where time actually goes.

Virtual memory

Network I/O

Registry

ReadyThread (causality)

Interrupts (DPC / ISR)

ALPC (cross-process IPC)

CLR (.NET runtime)

Requires the Microsoft-Windows-DotNETRuntime ETW provider in the capture profile (WPR .wprp files need an explicit <EventCollectorId> for it).

Markers / generic ETW events

Composite diagnostics

Symbols

Configuration

Trace cache

LRU, default capacity 2 traces. Override with WPRMCP_CACHE_SIZE=N. First load builds .etlx (slow); cached calls are instant. Capabilities and TraceLog are both cached per (path, mtime) — re-loading the same .etl is free.

Capturing your own traces

See docs/WPR_PROFILE.md for a recommended .wprp that captures CPU + CSwitch + FileIO + DiskIO + HardFaults + Loader stacks. Quick canonical capture:

wpr.exe -start tests\WprMcp.Tests\fixtures\MmapCapture.wprp -filemode
# … reproduce the slow case …
wpr.exe -stop C:\path\to\my_capture.etl

Symbols

If cpu_top_functions shows module!? everywhere and Stats.ResolutionRate < 0.8, your symbols are not working. This is the single biggest source of "garbage output".

Where to set the path

_NT_SYMBOL_PATH accepts semicolon-separated entries: SRV*<cache>*<url> for symbol servers, bare folder paths for local PDBs, mix and match. Three setup paths (any one suffices — they all set the same env var):

1. Pre-launch env var (cleanest, survives restarts):

   [Environment]::SetEnvironmentVariable("_NT_SYMBOL_PATH",
       "SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols", "User")
   

2. Per-MCP-server env block in the config JSON (see manual install above). Easiest to share between teammates.
3. Runtime via tool calls — ask the agent: "set the symbol path to SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols, then run diagnose_symbols on this trace."

Symbol cache defaults to %LocalAppData%\WprMcp\Symbols (separate from PerfView's C:\Symbols to avoid PDB-lock contention). Per-trace recommendations come back inside load_trace's SymbolStatus.Recommendations field, telling you which servers to add for the modules actually present in this trace.

Beyond Microsoft modules

The auto-recommendation in load_trace only knows the public servers it has patterns for (Microsoft, Chromium). For your own DLLs, third-party SDKs, or internal builds, append entries explicitly — common shapes:

Order matters — entries are tried left-to-right, first signature match wins. Put the local dev folder first when iterating on a build so your fresh PDB beats the public one.

Build prerequisites for your own DLLs

A symbol server doesn't help if the build never produced a PDB, or if PDB and deployed DLL are from different builds.

• .NET / C#: <DebugType>portable</DebugType> + <DebugSymbols>true</DebugSymbols>. Check that Release configurations don't disable PDB output.
• C++ (MSVC): /Zi + /DEBUG:FULL, even in Release. Keep PDB next to DLL.
• PDB and DLL must share the same signature (GUID + age) — re-link → new signature → old PDB no longer resolves.

Verifying it worked

> load_trace C:\my\trace.etl
> diagnose_symbols C:\my\trace.etl
> cpu_top_functions C:\my\trace.etl

diagnose_symbols lists per-module status with hints for unresolved ones; cpu_top_functions's Stats.ResolutionRate should be ≥ 0.8 for actionable output. After changing the symbol path mid-session, unload_trace + load_trace to force re-resolution — LookupWarmSymbols is cached per loaded trace.

For full recipes (UNC paths, private vendors, Chromium-family browsers, cache management, troubleshooting), see docs/SYMBOL_RECIPES.md (中文). Architecture overview and contribution invariants live in docs/ARCHITECTURE.md and CONTRIBUTING.md.