wpa-mcp

Local, evidence-driven Windows ETL analysis for MCP clients.

中文 | Latest release | Client compatibility | Contributing

wpa-mcp lets an AI client investigate an ETL trace without loading the entire trace into model context. The server opens the trace locally, applies explicit process, thread, and time scopes, and returns structured evidence in bounded pages.

What it does

• Reuses an opened trace through a stable trace reference instead of reopening the ETL for every question.

• Analyzes sampled CPU, precise CPU and scheduler activity when the trace contains the required events.

• Narrows analysis by process, PID, thread, TID, module, stack, and time window.

• Uses thread_compare_windows to compare named fast/slow intervals for one exact thread instance without mixing PID/TID reuse.

• Resolves symbols on demand and reports when missing symbols limit attribution.

• Returns capability evidence, warnings, partial failures, and pagination state instead of silently treating missing data as zero.

• Keeps high-cardinality stack output compact and supports snapshot-backed pagination for batch CPU and thread-window analysis.

Related MCP server: wpa-mcp

Quick start

1. Install and register in one command (recommended)

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

The installer downloads the latest complete wpa-mcp-win-x64.zip bundle to %USERPROFILE%\.local, verifies that the executable is usable, and registers its absolute path with every detected Codex, Claude Code, and Claude Desktop installation. The bundle is self-contained; no .NET runtime or SDK is required.

Verify the installed executable directly:

& "$HOME\.local\bin\wpa-mcp.exe" --version

Remote scripts should be reviewed before execution. To pin a release or select one client explicitly:

iex "& { $(irm https://raw.githubusercontent.com/tooluse-labs/wpa-mcp/main/scripts/install.ps1) } -Tag '<release-tag>' -Client codex"

2. Install manually

Windows x64 users can install the complete ZIP bundle without running a remote script. Keep the bin and native directories together:

$archive = Join-Path $env:TEMP 'wpa-mcp-win-x64.zip'
$install = Join-Path $HOME '.local\share\wpa-mcp'
$bin = Join-Path $install 'bin'

Invoke-WebRequest 'https://github.com/tooluse-labs/wpa-mcp/releases/latest/download/wpa-mcp-win-x64.zip' -OutFile $archive
Expand-Archive -LiteralPath $archive -DestinationPath $install -Force

# Make wpa-mcp available in this PowerShell session.
$env:Path = "$bin;$env:Path"

# Persist the bin directory for new processes and terminals.
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
$userEntries = @($userPath -split ';' | Where-Object { $_ })
if ($userEntries -notcontains $bin) {
    [Environment]::SetEnvironmentVariable(
        'Path', (($userEntries + $bin) -join ';'), 'User')
}

wpa-mcp.exe --version

If user-level environment changes are restricted by policy, omit the persistent PATH block and use the absolute command & "$install\bin\wpa-mcp.exe". Restart existing terminals and MCP clients after changing the persistent PATH.

The standalone wpa-mcp-win-x64.exe asset is intended for portable smoke checks. Use the ZIP bundle for normal installations because native dependencies and in-place updates require the complete bin plus native layout.

3. Connect an MCP client

Configure the client to launch bin\wpa-mcp.exe over stdio. Use an absolute path. JSON-based clients commonly use this shape:

{
  "mcpServers": {
    "wpa": {
      "command": "C:\\Users\\you\\.local\\share\\wpa-mcp\\bin\\wpa-mcp.exe"
    }
  }
}

Codex, Claude Code, and Claude Desktop use different configuration locations. Follow the exact recipe in Client compatibility.

3. Ask the first question

Open C:\traces\startup.etl. Summarize trace duration and available capabilities,
then show the top CPU processes. Do not resolve symbols yet.

Start broad, select the relevant PID or TID, and then request stacks or symbols. This produces better evidence and smaller responses than asking for every stack in one call.

Trace access

By default, load_trace opens any readable local .etl/.etlx path. To confine traces to specific directories, configure one or more roots by repeating --trace-root; each occurrence accepts exactly one value:

"args": ["--trace-root", "C:\\Traces", "--trace-root", "D:\\Captures"]

Alternatively set WPAMCP_TRACE_ROOTS (;-separated on Windows). Once any root is configured, only those directories load, and a trace_access_denied error names the rule that rejected the path plus the configured roots. --allow-any-trace-path (or WPAMCP_ALLOW_ANY_TRACE_PATH=true) forces confinement off even when roots are configured. Arguments the server does not recognize fail at startup instead of being ignored.

Update

A bundle installation can update itself to the latest stable GitHub Release:

wpa-mcp.exe update

If the executable is not on PATH, invoke it by absolute path. The updater accepts only a published, non-draft, non-prerelease release. It verifies GitHub's asset digest, immutable release evidence, the ZIP SHA-256, and the staged executable version before replacing the installed bundle.

Updating does not change MCP client registration. By default, the command exits without downloading or changing files when another process is running the exact installed executable; it reports the blocking PIDs so you can close the associated MCP clients and retry. To explicitly terminate only those exact-path server instances after the new bundle has been verified, use:

wpa-mcp.exe update --stop-running

This option does not terminate MCP client processes or similarly named executables from other paths, and it never bypasses release verification. Terminated server sessions lose in-memory trace and symbol state. The apply phase runs inside the verified staged wpa-mcp.exe itself and does not depend on PowerShell, execution policy, or shell language mode. The asynchronous replacement result is recorded in .wpa-mcp-update.log under the installation root. Installations created before the executable apply helper must install the latest ZIP bundle once.

Analysis workflow

1. Open the ETL and inspect duration, processes, and capability evidence.

2. Select one process, thread, or time interval that matches the observed symptom.

3. Compare intervals before requesting a large stack expansion.

4. Resolve symbols only for the selected scope.

5. Follow hasMore and continuation metadata until the required evidence is complete.

Useful prompts:

• Compare TID 4120 during 3-8 seconds and 8-13 seconds. Report sampled CPU, wait duration, top stacks, and any evidence the trace cannot provide.

• For PID 9000, find the hottest CPU functions, excluding ETW self-overhead. Resolve symbols only for the top modules.

• Explain why this thread is runnable but not running. Separate CPU execution, ready time, and blocked time.

• Analyze these PIDs in bounded pages. Continue from the returned snapshot instead of restarting the batch.

A wait duration does not by itself identify the blocking method. Reliable attribution depends on scheduler events, stack capture, symbols, and a sufficiently narrow time scope. thread_compare_windows therefore reports sampled counts, scheduler running time, ready latency, and blocked duration separately; ready latency and blocked duration are not additive.

Capture a useful trace

wpa-mcp can only analyze events that were recorded. Sampled CPU needs profile events and stacks; scheduler delay analysis needs context-switch and ready-thread events; method attribution usually needs resolvable symbols.

See WPR profile guidance for provider choices and capture tradeoffs. The repository includes the focused JitOnlyCapture.wprp profile and the Capture-JitOnly.ps1 helper under tests\WpaMcp.Tests\fixtures.

Do not enable every provider by default. Capture the smallest event set that can answer the performance question, and record markers around the scenario when possible.

Understand results

• traceRef identifies the opened trace used by later calls.

• scope records the process, thread, and time boundaries applied to a result.

• capabilityEvidence distinguishes available, absent, and unmeasured trace data.

• warnings and failedSections expose partial analysis instead of hiding it.

• hasMore and continuation metadata indicate that more bounded pages are available.

Treat unavailable capability evidence as unknown, not as a measured zero. Preserve the trace reference, scope, and symbol context when comparing results.

Troubleshooting

ETL files remain on the machine running the MCP server, but tool results are returned to the connected client. Symbol resolution may contact the symbol servers configured on that machine.

Documentation

• Architecture

• Client compatibility

• Capability gaps

• Symbol recipes

• WPR profile guidance

• Case studies

• Contract migration

The README documents the stable user journey. Detailed protocol design, rollout history, measurement baselines, and implementation tasks belong under docs/.

Build from source

Use the SDK selected by global.json:

git clone https://github.com/tooluse-labs/wpa-mcp.git
cd wpa-mcp
dotnet restore --locked-mode
dotnet build WpaMcp.sln -c Release --no-restore
dotnet test WpaMcp.sln -c Release --no-build

Source builds require the configured .NET SDK. Release bundles remain self-contained. See CONTRIBUTING.md before changing contracts or reviewed baselines.