CPU Performance Engineering

cpu-perf

An MCP server that gives any AI client the whole CPU Performance Engineering list as something it can search and reason over, instead of a page it has to be pasted. Connect it to Claude Code, Codex, Claude Desktop, Cursor or VS Code and use it for your own performance work: ask questions, paste perf stat or compiler output, and the client's own model writes the answer from what the server returns, with citations back to the sources.

It knows two things.

1. The repository. Every entry and its reason, in reading order; the watchlist and what would promote each line; the editorial record behind the list (every candidate that was considered and left out, with the rule it failed; every performance number examined against the seven-field rule, with its verdict; the link-verification notes); the fourteen benchmarks with their claims, machines, results, analysis, code and raw output; and the house rules. This is bundled with the server and loads in a fraction of a second.
2. The sources themselves. On first run the server reads every source the README links, plus the main document behind each link (the PDF behind an arXiv abstract, the manual behind a vendor landing page, a repository's README, a pull request's description), extracts the text with page numbers, and builds a local full-text and semantic index of it. Questions are then answered from the papers, manuals and documentation, not from memory.

Nothing is invented on top: the server reads the README, the section drafts and the benchmarks at start-up, the README stays the product, and no generated index is committed anywhere.

Connect it

Your AI client starts the server itself, with uv: it runs uvx cpu-perf, which fetches the release and starts it. Add that command to your client once, as below; run in a terminal, it only waits for a client. (pip install cpu-perf works too and gives the same cpu-perf command.)

The first start downloads its dependencies, which can take longer than some clients wait for a new server. Run uvx cpu-perf --version once in a terminal first, and every client after that starts it in about a second.

Every client above starts the server on your own machine; there is nothing to host. Claude.ai, the mobile apps and ChatGPT on the web connect only to servers on the internet, not to a program on your computer, so they cannot use it yet.

Claude

Claude Code

claude mcp add --scope user cpu-perf -- uvx cpu-perf

Claude Desktop: Settings, Developer, Edit Config, then add to claude_desktop_config.json. Desktop does not always see your shell's PATH, so give the full path that which uvx prints:

{

"mcpServers": { "cpu-perf": { "command": "/full/path/to/uvx", "args": ["cpu-perf"] } } }

ChatGPT

The ChatGPT desktop app runs local servers through its Codex host, configured as below.

Codex

codex mcp add cpu-perf -- uvx cpu-perf

or, in ~/.codex/config.toml (shared by the CLI, the IDE extension and the ChatGPT desktop app):

[mcp_servers.cpu-perf]

command = "uvx" args = ["cpu-perf"] startup_timeout_sec = 120 # room for the first start's downloads

Codex starts servers with a minimal environment; behind a proxy, pass it on:

env_vars = ["HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY"]

Cursor and VS Code

Cursor (~/.cursor/mcp.json) and VS Code (.vscode/mcp.json, which names the key servers and adds "type": "stdio"):

{

"mcpServers": { "cpu-perf": { "command": "uvx", "args": ["cpu-perf"] } } }

What every client sees

The answers are markdown written for a model to read. Claude Code and Codex show the model only a tool's structured data when a tool returns any, so the server returns none by default and every client reads the same text (--structured-output adds it back for programmatic use). Every tool is marked read-only, so no client asks for approval on each call, and slow reads of large documents return within a minute, finishing in the background.

Then ask, for example:

• Why does my multithreaded counter stop scaling past two threads?
• Here is my perf stat output; where is the time going?
• gcc says "not vectorized: complicated access pattern"; what do I change?
• What does cycle_activity.stalls_l3_miss count?
• What does the Intel optimisation manual say about store forwarding?
• Give me a reading path for NUMA, ending with something I can run.
• Why is cppreference not in the list?
• Is "AVX-512 gives 2x on Zen 5" a claim the list would quote?

Use it for your own work

ask takes the question and, optionally, whatever the user pasted as context. The server reads that output itself, with no model involved:

• `perf stat` in its plain, -x and -j forms, per-CPU and interval output included: the counters as read, and the ratios computed from them (instructions per cycle, frequency, branch, cache and TLB miss rates, misses per thousand instructions, stalled-cycle shares, faults and context switches per second), each with its formula, computed as perf computes its own columns. P-core and E-core counts on hybrid parts are never divided by each other.
• Top-down level 1 from perf stat --topdown, -M TopdownL1, the AMD PipelineL1 group, or toplev, and level 2 from -M TopdownL2. A level is flagged only against a threshold a listed source states: Intel's own values from its TMA metrics sheet, applied only to Intel P-cores and cited with every flag. Everything else is reported as measured, without a verdict. A flagged level sends the answer to the part of the list about it: a memory-bound run to the memory hierarchy, a front-end-bound one to fetch and decode.
• The machine: when the PMUs and event names show Intel, AMD or Arm, sources about the other vendors' hardware and tools are left out.
• How far to trust it: multiplexed counters (and the lowest running share, metric groups included), events that were not counted or not supported, how many -I intervals were summed, and lines the parser could not read, which are listed rather than guessed.
• perf's own errors: a missing metric group, perf_event_paranoid refusals, unknown or unsupported events, the NMI watchdog: each restated with what perf itself says to do, instead of being searched for word by word.
• gcc `-fopt-info` and clang `-Rpass` remarks: why each loop was left scalar, counted per loop, routed to the list's auto-vectorisation sources and benchmark.
• Assembly and code: objdump -d with or without the opcode bytes, gdb's disassemble, perf annotate, and source code. The instructions and identifiers that matter (gathers, atomics, fences, intrinsics, alignas, restrict) are routed to the matching sections, and so is what a loop does: a float sum carried across iterations, which stays one serial chain of adds without -fassociative-math even when a remark says the loop was vectorised (and packed multiplies feeding a run of scalar adds, its shape in assembly), an early exit, or fields read from an array of structs.

The event names, remarks and identifiers then steer the search, so the passages that come back are about the pasted output, not just the question.

Every answer says which of the list's sources it carries text from and which it does not. Each entry is marked as quoted (with the passages and pages), in the library but without a matching passage (with the read_source call that looks inside), or not read on this machine (with the reason: blocked, refused by a proxy, not fetched yet, a talk with only its description). The model is told to attribute a claim to a source only through a passage it was given, and to offer an unread source as further reading, never as a citation. A listed paper the question is about comes with its abstract, and every passage carries the list's title for its source rather than the document's own, which is often a placeholder such as "Untitled Document".

Answers are brief by default: passages are trimmed to the part that matches, the benchmark and the editorial record come only when they are relevant, and each passage carries an id that read_source(ref, passage=id) expands in full. detail="full" returns whole passages and everything related. Repeated questions are answered from a cache until the library changes.

The first run: building the library

The server answers from the repository immediately. In the background it fetches the linked sources into a local library:

• where: ~/.local/share/cpu-perf on Linux, ~/Library/Application Support/cpu-perf on macOS, %LOCALAPPDATA%\cpu-perf on Windows, or CPU_PERF_DATA_DIR;
• how long: a few minutes to a quarter of an hour, depending on the network and the large manuals; the crawl resumes where it stopped if the client closes the server;
• how big: one SQLite file of passages, a keyword index and embeddings, a few hundred megabytes at most; the downloaded files themselves are not kept;
• what it skips: very large PDFs are indexed up to a page cap and the rest is read on demand; scanned PDFs, compressed PostScript and videos have no text to index (videos keep their title and description).

To build it in the foreground with progress, run cpu-perf index; cpu-perf status --detail lists every source with its state.

Several MCP clients (Claude Desktop, Claude Code and Cursor at once, say) share one library. Every few minutes one of them, whichever holds an operating-system lock on the data folder, does the upkeep: it fetches sources that are new, due for a refresh or due for a retry, embeds passages that have no vector, and brings a library built by an older release up to date in place; a source is fetched again only when a release improves how its kind of document is read (this one rejoins words PDFs hyphenate across lines). A refresh that fails keeps the copy already in the library, unless the document is gone. The lock is released by the system if that client exits or crashes, and the work pauses while requests arrive.

Some publishers (ACM, IEEE, parts of the Intel and Arm portals) refuse automated clients or render their documents only in a browser. Those sources are reported as blocked or partial, with the list's own link notes on why, and the answer points the reader to the link instead. Coverage is reported as it is, never padded.

Semantic search uses the small static embedding model potion-base-8M, downloaded once. Without it (offline, or CPU_PERF_EMBED_MODEL=none) the library falls back to keyword search alone.

Copyright and politeness

The library is built on the user's own machine, or the operator's own server, from the public URLs the list links; nothing crawled is committed, published or shipped in the package or the container image. The crawler fetches only those documents, identifies itself, waits between requests to one host and backs off on rate limits. It reads each listed link the way a reader opening it would, so it does not consult robots.txt unless asked to with --respect-robots (CPU_PERF_RESPECT_ROBOTS=1); sources a site then disallows are reported as blocked.

Tools

| ask | The evidence for a question: the best passages from the linked sources (with page numbers), the list's entries and reasons, and, when relevant, the matching benchmark and the editorial record. With context, the pasted output's metrics and notes too. Call it