profiler-mcp

Two MCP servers that put CPU profilers in front of coding agents: vtune (Intel VTune Profiler, 7 tools) and uprof (AMD uProf, 9 tools) — one Python package, one shared core. Neither profiler runs on macOS or on machines without the right silicon, so each server ships a byte-realistic mock backend (derived from verbatim captures of the real CLIs) that lets the whole project run, self-test, and even self-optimize anywhere.

MCP client (Claude Code)
    │ stdio (default) or streamable-http
    ▼
vtune-mcp / uprof-mcp      server.py  — FastMCP tool surface
    │                      cli.py     — argv construction
    ▼
core/runner.py subprocess ──► real `vtune` / `AMDuProfCLI`
    │                   └───► or mocks/*_mock.py   (picked by core/config.py; auto-mock iff no real binary)
    ▼
parse.py ──► TypedDicts (core/models.py) ──► core/store.py registry (result_id, e.g. "hs-0000")
                  core/compare.py ──► verdict ──► fail_on_regression gate for optimize loops

Quickstart

uv sync                      # Python >=3.11; only runtime dep is the mcp SDK (pinned >=1.28,<2)
uv run pytest                # deterministic self-test gate (layers 1-4, see below)
make -C examples/workloads   # compile the deterministic example workload (hotspots)

Registering with Claude Code: the repo ships a project-scope .mcp.json that starts both servers with uv run vtune-mcp / uv run uprof-mcp — open Claude Code in this directory and it works out of the box on any machine (mock mode auto-activates where the real profilers are absent). To register explicitly instead:

claude mcp add vtune -- uv run vtune-mcp        # from inside this repo
claude mcp add uprof -- uv run uprof-mcp
# or from anywhere, at user scope:
claude mcp add --scope user vtune -- uv run --directory /path/to/profiler-mcp vtune-mcp

A typical conversation (mock mode shown; identical flow with uprof_*):

> what profiling is available here?
  vtune_check() -> mode: "mock", binary: .../mocks/vtune_mock.py, 15 analyses
> profile the example workload's compute phase
  vtune_collect(analysis="hotspots",
                command=["examples/workloads/hotspots", "--seconds", "5", "--only", "compute"])
  -> result_id: "hs-0000"
> where does the time go?
  vtune_report_hotspots(result_id="hs-0000") -> hot_compute 95%, main 5%
  (notes: "Mock mode: synthetic data — do not treat numbers as real hardware measurements.")

Tool reference

vtune (7 tools)

uprof (9 tools)

Results persist server-side under short ids; tools return capped structured summaries, never raw dumps. Every result is stamped with the mode it was collected in.

Real hardware setup

Linux x86 — VTune (oneAPI Base Toolkit or standalone): source /opt/intel/oneapi/vtune/latest/env/vars.sh puts vtune on PATH, or set VTUNE_MCP_BIN to the binary; the conventional install paths are probed automatically. Driverless hardware sampling needs perf_event_paranoid <= 1 (0 for system-wide/uncore, which memory-access requires) — vtune_check warns when the setting blocks collection. Validate an install with <install-dir>/bin64/vtune-self-checker.sh.

Linux x86 — uProf: installs land in /opt/AMDuProf_X.Y-ZZZ/; the newest /opt/AMDuProf_*/bin/AMDuProfCLI is found automatically, or set UPROF_MCP_BIN. timechart and the energy config additionally need the AMDPowerProfiler kernel driver (auto-installed by rpm/deb; sudo ./AMDPowerProfilerDriver.sh install for tar installs). On Intel CPUs uProf runs tbp (timer-based) only — PMC/IBS/energy configs need AMD hardware.

Windows: default install paths are probed (C:\Program Files (x86)\Intel\oneAPI\vtune\latest\bin64\vtune.exe, C:\Program Files\AMD\AMDuProf\bin\AMDuProfCLI.exe); the *_MCP_BIN overrides work the same way.

macOS: mock mode only. VTune dropped macOS support entirely in 2024.0 and uProf never had it, so there is nothing real to run; auto mode falls back to the mocks.

Mock mode

The mocks (src/profiler_mcp/mocks/) are not stubs. They are byte-realistic emulations of the vendor CLIs, built from verbatim captured output (docs/research/captures-*.md), strict about flags (unknown options are errors, so server argv bugs fail loudly), and they actually execute the profiled command — process lifecycle, exit codes, working dirs, and timeouts are all real. Sample attribution is synthetic and deterministic, driven by a <binary>.mockprofile.json sidecar model next to the target (see examples/workloads/hotspots.mockprofile.json); a generic model applies otherwise.

What they are not: measurements. The weights are fixed, so mock numbers do not respond to your code edits — use mock mode to exercise tooling and workflows, real mode to optimize programs. Every mock-collected result carries an explicit mock-data note.

Fault injection for testing error paths:

Self-testing and self-optimization

The full story is in docs/SELF_TESTING.md. The pyramid:

Layers 1–4 are the deterministic gate: uv run pytest. Layer 5 runs via the Workflow tool with {scriptPath: ".claude/workflows/self-test.js"}; the companion {scriptPath: ".claude/workflows/optimize-project.js"} is the test-gated self-improvement loop (find → adversarial verify → apply one at a time → re-gate). Agent skills in .claude/skills/: profile-hotspots (drive either server and interpret results), optimize-loop (verdict-gated baseline/change/compare protocol), profiler-selftest (run and extend the pyramid).

Configuration reference

Status & known limitations

This is a prototype, honest about what it is:

• Never run on real hardware. Everything here was developed and validated in mock mode. The real mode paths are best-effort and unverified. Expect to fix binary discovery, argument construction, and — most likely — the parsers, which are written against captured samples that may differ from your VTune/uProf version's actual output.

• CLI surfaces are reconstructed from vendor docs and public captures, not from a live tool. Both vendors change flags across versions (uProf 5.0 "simplified CLI options"; VTune knob names vary by release). *_check currently reports a hardcoded analysis/config list rather than querying the installed tool.

• Auto-discovery of the uProf binary sorts install paths lexicographically, so e.g. AMDuProf_5.9 can win over AMDuProf_5.10. Set UPROF_MCP_BIN explicitly.

• real-mode report tools re-run the CLI on every call (results are only partially cached), and *_report_raw/*_report_hotspots carry a readOnlyHint even though the first call may generate a report file as a side effect.

• uProf stdout parsing keys on marker lines (Generated data files path: etc.); a profiled program that prints those same strings could in principle confuse session-dir discovery (a newest-directory glob is the fallback).

• Concurrency is best-effort. Result-id reservation is atomic (via directory creation) and registry writes take a POSIX file lock, but the lock degrades to a no-op on Windows.

• The mock's numbers are fixed weights — they do not respond to code changes, so the optimize loop exercises the machinery, not real speedups, in mock mode.

The code passes a 97-test deterministic suite plus an agentic self-test, and a five-lens adversarial review whose nine confirmed findings were fixed and regression-tested — but all of that is against the mocks. Contributions that exercise it on actual VTune/uProf installs are exactly what it needs. See docs/DESIGN.md for the architecture and rationale.

License

MIT (LICENSE). The uProf invocation and stdout-contract knowledge derives from AMDResearch/intellikit (MIT, AMD) — re-implemented, not vendored; see NOTICE.

No warranty. Provided as-is under the MIT license; see the caution at the top.