Content
# wpa-mcp
> An **MCP (Model Context Protocol) server** that turns Windows **WPR `.etl`** traces into structured, LLM-friendly performance insights — using **WPAExporter** + **xperf** under the hood, and optionally emitting **flamegraph-ready folded stacks**.
`wpa-mcp` bridges two worlds:
- **Windows Performance Analyzer (WPA)** — the gold standard for analyzing ETW / WPR traces, but GUI-heavy and hard to automate.
- **LLMs (Claude, Copilot, GPT, …)** — great at reasoning across evidence, but blind to `.etl` files.
This server exposes a small set of MCP tools so an LLM can:
1. **Validate** a trace (does it actually contain the events needed for analysis?)
2. **Export** the right WPA tables to CSV via predefined profiles
3. **Summarize** the CSVs into a compact JSON (Top N processes, hot stacks, ready-thread latency, DPC/ISR offenders, UI jank)
4. **Render** a Brendan-Gregg-style **folded stack** file for flamegraphs — or for the LLM to read directly
---
## Table of contents
- [Architecture](#architecture)
- [Prerequisites](#prerequisites)
- [Install](#install)
- [Capture a trace](#capture-a-trace)
- [MCP tools](#mcp-tools)
- [Built-in WPA profiles](#built-in-wpa-profiles)
- [Analysis examples](#analysis-examples)
- [Example 1: Runaway CPU](#example-1-runaway-cpu)
- [Example 2: UI hang / "not responding"](#example-2-ui-hang--not-responding)
- [Example 3: Audio/mouse glitch caused by a driver](#example-3-audiomouse-glitch-caused-by-a-driver)
- [Example 4: Feeding folded stacks to the LLM](#example-4-feeding-folded-stacks-to-the-llm)
- [Client configuration](#client-configuration)
- [Release process](#release-process)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
---
## Architecture
```
+------------------+ stdio (MCP) +--------------------+
| LLM / MCP host | <--------------------> | wpa-mcp server |
| (Claude, VSCode) | | (this repo) |
+------------------+ +----------+---------+
|
subprocess |
v
+---------------------+---------------------+
| xperf.exe | wpaexporter.exe |
| (validate / stats) | (+ .wpaProfile) |
+---------------------+---------------------+
|
v
CSV tables (per profile)
|
v
summarizer -> JSON / flamegraph -> .folded
```
Everything that the LLM sees is **structured JSON** or **compact folded-stack text** — never raw gigabyte CSVs.
---
## Prerequisites
- **Windows 10/11** (required; the analysis tools are Windows-only)
- **Windows Performance Toolkit (WPT)** installed (ships with Windows ADK / Windows SDK)
- `wpaexporter.exe`
- `xperf.exe`
- **Python 3.10+**
If WPT is installed to a non-default path, set:
```powershell
setx WPAEXPORTER_PATH \"C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\wpaexporter.exe\"
setx XPERF_PATH \"C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\xperf.exe\"
```
---
## Install
### Via pipx (recommended — works once published to PyPI)
```powershell
pipx install wpa-mcp
wpa-mcp # starts the MCP stdio server
```
### From source
```powershell
git clone https://github.com/Jialong-zhong/wpr-xperf-mcp-server.git
cd wpr-xperf-mcp-server
pip install -e .
wpa-mcp
```
---
## Capture a trace
The server's analyses are only as good as the providers you captured. Recommended capture for the four problem classes this server targets:
```powershell
# Run as Administrator
wpr -start CPU ^
-start GeneralProfile ^
-start DesktopComposition ^
-start Registry ^
-filemode
# ... reproduce the issue ...
wpr -stop C:\traces\case01.etl \"repro notes here\"
```
| WPR profile | What it adds that wpa-mcp uses |
|------------------------|-----------------------------------------------------------|
| `CPU` | Sampled CPU, CSwitch, ReadyThread, StackWalk |
| `GeneralProfile` | Processes, images, DPC/ISR |
| `DesktopComposition` | DWM frame timing, Window-in-focus (UI hang evidence) |
| `Registry` | Registry activity (optional; useful for startup/UI hangs) |
> If you skip `CPU`, the most valuable analyses (hot stacks, scheduling latency) won't work — `validate_trace` will tell you so.
---
## MCP tools
| Tool | Purpose | Typical caller |
|------|---------|----------------|
| `validate_trace(etl_path)` | Run `xperf -a stats` and report which providers / stacks exist | LLM, always first |
| `export_tables(etl_path, profile)` | Run **one** WPA profile via `wpaexporter` and return CSV paths | Advanced / targeted |
| `analyze_etl(etl_path, focus)` | Validate → export (by focus) → summarize. Returns one structured JSON | LLM, default entry point |
| `analyze_audio_glitch(etl_path)` | MXA-style audio glitch analysis: long DPC/ISR buckets, dispatch-level suspects, and pipeline risk | LLM, audio crackle/skip triage |
| `analyze_audio_glitch_ex4(etl_path)` | Executable MXA Exercise 4 method: long DPC/ISR, dispatch blocking, I/O starvation, decoder realtime checks | LLM, root-cause oriented audio triage |
| `render_flamegraph(out_dir)` | Aggregate `CPU Usage (Sampled)` stacks into Brendan-Gregg folded format | After `analyze_etl` with CPU focus |
### `analyze_etl` input schema
```json
{
\"etl_path\": \"C:\\traces\\case01.etl\",
\"focus\": \"cpu | latency | ui | dpc_isr | all\",
\"out_dir\": \"optional override\",
\"top_n\": 20
}
```
### `analyze_etl` output shape (abbreviated)
```json
{
\"etl\": \"C:\\traces\\case01.etl\",
\"focus\": \"all\",
\"validation\": {
\"duration_sec\": 42.7,
\"has_cpu_sampling\": true,
\"has_cswitch\": true,
\"has_readythread\": true,
\"has_stacks\": true,
\"has_dpc_isr\": true,
\"has_dwm\": true,
\"warnings\": []
},
\"exports\": [\"...\\cpu\\CPU Usage (Sampled)_...csv\", \"...\"],
\"summary\": {
\"cpu_top_processes\": [{\"process\": \"chrome.exe\", \"weight_ms\": 8421.3}],
\"cpu_top_modules\": [{\"module\": \"ntdll.dll\", \"weight_ms\": 2310.0}],
\"cpu_hot_stacks\": [{\"stack\": \"ntdll!... ; app!hot_fn\", \"weight_ms\": 1240.0}],
\"ready_latency_top\": [{\"process\": \"explorer.exe\", \"tid\": 1234, \"p95_ms\": 187.0}],
\"dpc_isr_top\": [{\"driver\": \"ndis.sys\", \"total_ms\": 95.2, \"max_us\": 820}],
\"ui_focus_top\": [{\"process\": \"myapp.exe\", \"focus_ms\": 5400.0}],
\"dwm_slow_frames\": {\"count\": 38, \"p95_ms\": 41.7, \"max_ms\": 128.0}
}
}
```
### `analyze_audio_glitch` input schema
```json
{
\"etl_path\": \"C:\\traces\\AudioGlitches_ThreadsAtDispatchLevel.etl\",
\"top_n\": 20,
\"dispatch_threshold_us\": 1000,
\"exclude_idle\": true
}
```
### `analyze_audio_glitch` output shape (abbreviated)
```json
{
\"etl\": \"C:\\traces\\AudioGlitches_ThreadsAtDispatchLevel.etl\",
\"validation\": { \"duration_sec\": 69.5, \"has_dpc_isr\": true },
\"analysis\": {
\"mxa_criteria\": { \"long_dpc_or_isr_threshold_us\": 1000 },
\"audio_glitch_assessment\": {
\"risk\": \"medium\",
\"long_running_dpc\": { \"total_count\": 43808, \"over_threshold_count\": 0 },
\"long_running_isr\": { \"total_count\": 23838, \"over_threshold_count\": 0 },
\"audio_related_drivers_in_dpc_top\": [{ \"driver\": \"portcls.sys\", \"total_ms\": 116.7 }],
\"audio_pipeline_processes\": [{ \"process\": \"audiodg.exe\", \"weight_ms\": 244.7 }]
},
\"base_summary\": { \"dpc_isr_top\": [], \"cpu_business_processes\": [] }
}
}
```
### `analyze_audio_glitch_ex4` output shape (abbreviated)
```json
{
"etl": "C:\\traces\\AudioGlitches_ThreadsAtDispatchLevel.etl",
"validation": { "duration_sec": 69.5, "has_dpc_isr": true },
"analysis": {
"method": {
"name": "mxa_exercise4_audio_glitch_method",
"version": "1.0"
},
"checks": [
{ "id": "long_dpc_isr", "status": "pass|warn|fail" },
{ "id": "dispatch_level_blocking", "status": "pass|warn" },
{ "id": "io_delivery_pressure", "status": "pass|warn" },
{ "id": "decoder_realtime_capacity", "status": "pass|warn" }
],
"glitch_likelihood": "low|medium|high",
"most_likely_causes": ["..."],
"actions": ["..."]
}
}
```
---
## Built-in WPA profiles
Each profile is a `.wpaProfile` XML that tells `wpaexporter` which WPA tables + columns to dump.
| Focus key | File | Tables exported |
|-----------|------|-----------------|
| `cpu` | `wpa/profiles/cpu_hotpath.wpaProfile` | CPU Usage (Sampled) |
| `latency` | `wpa/profiles/scheduling_latency.wpaProfile` | CPU Usage (Precise), Ready Thread |
| `ui` | `wpa/profiles/ui_hang.wpaProfile` | Window In Focus, DWM Frame Details |
| `dpc_isr` | `wpa/profiles/dpc_isr.wpaProfile` | DPC/ISR Duration |
Column sets are deliberately minimal to keep CSVs small and summarizer-friendly.
---
## Analysis examples
These are end-to-end, copy-pasteable walkthroughs. Each shows the **user prompt**, the **tool calls the LLM should make**, the **JSON shape you can expect**, and the **conclusions a well-prompted LLM should draw**.
### Example 1: Runaway CPU
**User:** *\"`C:\traces\cpu_spike.etl` — some process is pinning my CPU at 100%. Find it and tell me which function.\"*
**LLM tool calls:**
```jsonc
// 1) validate
validate_trace({ \"etl_path\": \"C:\\traces\\cpu_spike.etl\" })
// 2) analyze focused on CPU
analyze_etl({ \"etl_path\": \"C:\\traces\\cpu_spike.etl\", \"focus\": \"cpu\", \"top_n\": 10 })
// 3) (optional) generate folded stacks for the hottest paths
render_flamegraph({
\"out_dir\": \"C:\\traces\\cpu_spike_wpa_out\\cpu\",
\"top_n\": 200,
\"min_weight_ms\": 5
})
```
**Typical `summary` returned:**
```json
{
\"cpu_top_processes\": [
{ \"process\": \"myapp.exe\", \"weight_ms\": 38210.0 },
{ \"process\": \"chrome.exe\", \"weight_ms\": 2100.0 }
],
\"cpu_top_modules\": [
{ \"module\": \"myapp.exe\", \"weight_ms\": 31020.0 },
{ \"module\": \"ucrtbase.dll\", \"weight_ms\": 4100.0 }
],
\"cpu_hot_stacks\": [
{ \"stack\": \"ntdll!RtlUserThreadStart;kernel32!BaseThreadInitThunk;myapp!worker_loop;myapp!compress_chunk\",
\"weight_ms\": 27800.0 }
]
}
```
**What the LLM should conclude:**
- Trace duration 42 s, `myapp.exe` consumed ~38 s of CPU ≈ **~90% of wall time on a single core equivalent.**
- Nearly all weight is in `myapp!compress_chunk` via `worker_loop` → this is a **hot loop in the app itself**, not the runtime or OS.
- Recommend: inspect `compress_chunk`, consider SIMD / chunking, and capture a second trace with `-start CPU -start FileIO` to see if the loop is also I/O-bound.
---
### Example 2: UI hang / \"not responding\"
**User:** *\"When the user clicks **Save**, the window freezes for ~2 seconds. Trace at `C:\traces\save_hang.etl`.\"*
**LLM tool calls:**
```jsonc
validate_trace({ \"etl_path\": \"C:\\traces\\save_hang.etl\" })
analyze_etl({ \"etl_path\": \"C:\\traces\\save_hang.etl\", \"focus\": \"ui\" })
analyze_etl({ \"etl_path\": \"C:\\traces\\save_hang.etl\", \"focus\": \"latency\" })
```
**Expected signals:**
```json
{
\"ui_focus_top\": [{ \"process\": \"myapp.exe\", \"focus_ms\": 5400 }],
\"dwm_slow_frames\": { \"count\": 42, \"p95_ms\": 58.0, \"max_ms\": 1980.0 },
\"ready_latency_top\": [
{ \"process\": \"myapp.exe\", \"tid\": 7321, \"p95_ms\": 14.0 }
]
}
```
**Reasoning rubric the LLM should apply:**
- `dwm_slow_frames.max_ms ≈ 1980` while the app is in focus → **the hang is real and UI-thread-bound.**
- `ready_latency_top` for the UI thread is low (≈14 ms p95) → the thread **wasn't starved for CPU**; it was **busy on its own work** (otherwise we'd see hundreds of ms of ready-wait).
- Therefore the UI thread is doing synchronous work during Save. Likely culprits: synchronous disk/network I/O, lock contention, or a heavy compute path on the UI thread.
- Next step: re-capture with `-start CPU -start FileIO -start DiskIO` and focus on the UI thread's stacks with `render_flamegraph` to see **exactly what** it's doing during those 2 seconds.
> Contrast: if `ready_latency_top` had been, say, `p95_ms: 900` — then the UI thread **was ready but not scheduled**. That's a scheduling/contention story, not a "heavy work on UI thread" story.
---
### Example 3: Audio/mouse glitch caused by a driver
**User:** *\"Audio crackles and the mouse skips for a split second every few minutes. `C:\traces\glitch.etl`.\"*
**LLM tool calls:**
```jsonc
validate_trace({ \"etl_path\": \"C:\\traces\\glitch.etl\" })
analyze_audio_glitch_ex4({ \"etl_path\": \"C:\\traces\\glitch.etl\", \"dispatch_threshold_us\": 1000 })
```
**Expected signal:**
```json
{
\"glitch_likelihood\": \"high\",
\"checks\": [
{ \"id\": \"long_dpc_isr\", \"status\": \"fail\" },
{ \"id\": \"dispatch_level_blocking\", \"status\": \"warn\" },
{ \"id\": \"io_delivery_pressure\", \"status\": \"warn\" },
{ \"id\": \"decoder_realtime_capacity\", \"status\": \"pass\" }
],
\"top_dpc_drivers\": [
{ \"driver\": \"Netwtw10.sys\", \"total_ms\": 312.4, \"count\": 1820 },
{ \"driver\": \"ndis.sys\", \"total_ms\": 95.1, \"count\": 4300 }
]
}
```
**What the LLM should conclude:**
- `Netwtw10.sys` (Intel Wi-Fi driver) has a **single DPC over 4 ms** — that's well above the ~1 ms \"don't cause audio glitches\" rule of thumb.
- Correlation with symptom: Wi-Fi DPC storms typically line up with mouse/audio skips because DPCs run at elevated IRQL and block the audio/HID stack.
- Recommend: update the Wi-Fi driver; if the problem persists, disable power-saving for the Wi-Fi adapter and re-capture.
> Quality rules wpa-mcp's prompting guide bakes in: any driver with `max_us > 1000` is suspicious, `>= 500` worth mentioning.
### Example 3B: Exercise 4 workflow (Chinese quick-start)
**用户：**“`C:\\traces\\audio_noise.etl` 分析是否有音频噪点，并给出最可能原因和修复优先级。”
**推荐调用顺序：**
```jsonc
validate_trace({ \"etl_path\": \"C:\\traces\\audio_noise.etl\" })
analyze_audio_glitch_ex4({
\"etl_path\": \"C:\\traces\\audio_noise.etl\",
\"dispatch_threshold_us\": 1000,
\"top_n\": 20,
\"exclude_idle\": true
})
```
**建议输出模板：**
```text
结论：confirmed | suspected | not_observed
噪点风险：low | medium | high
证据：
1) long_dpc_isr：<status>，关键数值：<dpc/isr over-threshold count>
2) dispatch_level_blocking：<status>，关键模块：<top .sys suspects>
3) io_delivery_pressure：<status>，关键数值：<disk/network weight>
4) decoder_realtime_capacity：<status>，关键数值：<decoder+audiodg weight>
最可能原因（按优先级）：
1) <cause #1>
2) <cause #2>
3) <cause #3>
建议动作：
1) 立即动作：<driver update/rollback, power policy>
2) 复现验证：<same scenario recapture>
3) 深挖采集：<CPU + DPC/ISR + CSwitch + ReadyThread + StackWalk>
```
**判读提示：**
- `long_dpc_isr=fail` 基本可判为强噪点证据。
- `glitch_likelihood=medium/high` 且前 2 项存在 `warn/fail` 时，应优先处理驱动与调度干扰。
- 若 `has_stacks=false` 或 `has_readythread=false`，结论需降级为“疑似”，并建议补采集。
---
### Example 4: Feeding folded stacks to the LLM
After `analyze_etl` with `focus="cpu"`, you can ask the LLM to drill deeper:
```jsonc
render_flamegraph({
\"out_dir\": \"C:\\traces\\cpu_spike_wpa_out\\cpu\",
\"output_path\": \"C:\\traces\\cpu_spike.folded\",
\"top_n\": 300,
\"min_weight_ms\": 2
})
```
Returns:
```json
{
\"folded_file\": \"C:\\traces\\cpu_spike.folded\",
\"source_csv\": \"C:\\traces\\cpu_spike_wpa_out\\cpu\\CPU Usage (Sampled)_....csv\",
\"line_count\": 287,
\"total_weight_ms\": 39120.0,
\"preview\": \"ntdll!RtlUserThreadStart;kernel32!BaseThreadInitThunk;myapp!worker_loop;myapp!compress_chunk 27800\\nntdll!... ; myapp!parse_header 410\\n...\"
}
```
You can now either:
- **Render an SVG** flamegraph (requires Perl + Brendan Gregg's script):
```bash
flamegraph.pl C:\traces\cpu_spike.folded > C:\traces\cpu_spike.svg
```
- **Or just let the LLM read the `preview`** — the folded format is already *much* easier for an LLM than raw CSV.
---
## Client configuration
### Claude Desktop — `%APPDATA%\\Claude\\claude_desktop_config.json`
```json
{
\"mcpServers\": {
\"wpa\": {
\"command\": \"wpa-mcp\",
\"env\": {
\"WPAEXPORTER_PATH\": \"C:/Program Files (x86)/Windows Kits/10/Windows Performance Toolkit/wpaexporter.exe\",
\"XPERF_PATH\": \"C:/Program Files (x86)/Windows Kits/10/Windows Performance Toolkit/xperf.exe\"
}
}
}
}
```
### VS Code (GitHub Copilot Chat / MCP) — `.vscode/mcp.json`
Already included in this repo. It points at `server.py` in the workspace.
### Custom MCP host
Any MCP client that speaks stdio works. Launch `wpa-mcp` (or `python server.py`) as a child process and send `tools/list` + `tools/call` over stdio.
---
## Release process
This repo publishes to PyPI via **GitHub Actions + PyPI trusted publishing (OIDC)** — no secrets required.
One-time PyPI setup:
1. Claim the `wpa-mcp` project on PyPI.
2. Add a **Trusted Publisher**:
- Owner: `Jialong-zhong`
- Repository: `wpr-xperf-mcp-server`
- Workflow: `publish.yml`
- Environment: `pypi`
Then, to ship a new version:
```powershell
# bump version in pyproject.toml, commit, then:
git tag v0.2.0
git push origin v0.2.0
```
The `Publish to PyPI` workflow (on tag `v*`) will build the sdist + wheel and publish automatically.
---
## Troubleshooting
| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `wpaexporter not found` | WPT not installed or path wrong | Install Windows Performance Toolkit; set `WPAEXPORTER_PATH` |
| `xperf stats failed` | ETL corrupted or not a WPR trace | Re-capture; ensure you ran `wpr -stop <file>` successfully |
| `columns missing` in summarizer | Your WPA version renamed columns | Open the corresponding `.wpaProfile` and adjust `<Column Name=...>` to match your WPA |
| `has_stacks: false` in validation | `-start CPU` not used during capture, or no admin | Re-capture with `-start CPU` as Administrator |
| Empty `dwm_slow_frames` | `DesktopComposition` profile wasn't enabled | Re-capture with `-start DesktopComposition` |
| `ready_latency_top` all near zero during a hang | The thread isn't ready-waiting → it's doing work | Run `render_flamegraph` on CPU exports to see what work |
| New tool added in `server.py` but not visible in client | MCP host cached old tool manifest | Restart MCP host/client session and run a tools/list check |
### MCP tool visibility quick check
After adding a new MCP tool (for example `analyze_audio_glitch_ex4`), verify in this order:
1. Restart the MCP client session (or restart VS Code window / host app).
2. Confirm the server command points to the updated `server.py`.
3. Trigger a `tools/list` from the client and verify the tool name appears.
4. Run one dry call with a known ETL path to confirm runtime import succeeds.
If the tool still does not appear, close all host processes that keep persistent MCP connections, then reconnect.
You can run a local preflight check before reconnecting the client:
```powershell
python scripts\check_mcp_tools.py
```
With ETL dry-run validation:
```powershell
python scripts\check_mcp_tools.py --etl-path C:\DumpFiles\wpr_example.etl
```
Strict gating mode (fail if `validate_trace` emits warnings):
```powershell
python scripts\check_mcp_tools.py --etl-path C:\DumpFiles\wpr_example.etl --fail-on-validation-warning
```
Exit codes:
- `0`: pass
- `2`: required MCP tools missing
- `3`: ETL path not found
- `4`: strict mode enabled and validation warnings found
- `5`: validation interrupted
- `6`: validation failed due to runtime/tooling error
---
## FAQ
**Q: Does this need WPA GUI installed?**
No. Only `wpaexporter.exe` and `xperf.exe` (both from the Windows Performance Toolkit) are called. WPA GUI never launches.
**Q: Can I use this on Linux/macOS?**
The MCP server itself is pure Python. But `wpaexporter` / `xperf` only exist on Windows, so analysis must run on Windows. A common setup is: capture on Windows, copy ETL to a Windows analysis box, run `wpa-mcp` there.
**Q: Why not parse ETL directly in Python?**
ETL parsing is deep. Microsoft already ships an excellent, correct parser (`wpaexporter`) that understands every kernel + provider schema. Reusing it is cheaper and more accurate than reimplementing.
**Q: Can I add my own WPA profile?**
Yes. Drop a `.wpaProfile` into `wpa/profiles/`, add a key to `PROFILE_MAP` in `server.py`, and (optionally) a summarizer in `wpa/summarizer.py`.
**Q: Does the LLM see the full CSV?**
No — by design. The LLM sees compact summary JSON plus (optionally) folded-stack text. Raw CSVs stay on disk and are referenced by path.
---
## License
MIT. See [LICENSE](./LICENSE).
