CPU Performance Engineering

cpu-perf

任意の AI クライアントに、CPU Performance Engineering の全リストを検索・推論できる形で提供する MCP サーバーです。ページを貼り付ける必要はありません。Claude Code、Codex、Claude Desktop、Cursor、VS Code に接続し、パフォーマンス関連の作業に活用できます。質問したり、perf stat やコンパイラーの出力を貼り付けたりすると、サーバーから返された情報を基に、クライアント自身のモデルが出典を示して回答を作成します。

このサーバーが把握している情報は、次の 2 つです。

1. リポジトリ。 すべての項目とその理由（掲載順）、ウォッチリストと各項目を昇格させる条件、リストの編集記録（検討のうえ除外された候補と、それぞれが満たさなかったルール、7 項目ルールに照らして検証したすべてのパフォーマンス数値とその判定、リンクの検証メモ）、主張、マシン、結果、分析、コード、未加工の出力を含む 14 件のベンチマーク、そして編集方針を網羅しています。これらはサーバーに同梱されており、1 秒にも満たない時間で読み込まれます。
2. ソース自体。 初回起動時に、サーバーは README がリンクするすべてのソースに加えて、各リンク先の主要な文書（arXiv の要旨の先にある PDF、ベンダーのランディングページの先にあるマニュアル、リポジトリの README、プルリクエストの説明）を読み込み、ページ番号付きでテキストを抽出し、ローカルの全文・セマンティックインデックスを構築します。質問には記憶ではなく、論文、マニュアル、ドキュメントの内容を基に回答します。

サーバーが独自の情報を付け加えることはありません。起動時に README、セクションの草稿、ベンチマークを読み込み、README がそのまま製品として維持されます。生成されたインデックスがどこかにコミットされることもありません。

接続方法

AI クライアントは uv を使ってサーバーを自分で起動します。uvx cpu-perf を実行してリリースを取得し、サーバーを起動します。以下のように、そのコマンドをクライアントに一度登録してください。ターミナルで実行した場合は、クライアントからの接続を待つだけです。（pip install cpu-perf でもインストールでき、同じ cpu-perf コマンドを利用できます。）

初回起動時には依存関係がダウンロードされるため、一部のクライアントでは新しいサーバーの起動待ち時間を超える場合があります。まずターミナルで uvx cpu-perf --version を一度実行してください。以降、各クライアントは約 1 秒でサーバーを起動できます。

クライアント	セットアップ
Claude Code	コマンドを 1 つ実行
Claude Desktop	数行の設定
Codex（CLI、IDE 拡張機能、ChatGPT デスクトップアプリ）	コマンドを 1 つ実行
Cursor、VS Code	数行の設定
Claude.ai、Claude モバイルアプリ、ChatGPT ウェブ版	まだ利用できません

上記の各クライアントは、自分のマシン上でサーバーを起動するため、ホストするものはありません。Claude.ai、モバイルアプリ、ChatGPT ウェブ版はインターネット上のサーバーにのみ接続し、コンピューター上のプログラムには接続できないため、現時点では利用できません。

Claude

Claude Code

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

Claude Desktop：Settings、Developer、Edit Config の順に選択し、claude_desktop_config.json に追加します。Desktop ではシェルの PATH が常に認識されるとは限らないため、which uvx で表示されるフルパスを指定してください。

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

ChatGPT

ChatGPT デスクトップアプリは、以下のように設定した Codex ホストを通じてローカルサーバーを実行します。

Codex

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

または、CLI、IDE 拡張機能、ChatGPT デスクトップアプリで共有される ~/.codex/config.toml に設定します。

[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 と VS Code

Cursor（~/.cursor/mcp.json）と VS Code（.vscode/mcp.json。キー名は servers で、"type": "stdio" を追加します）：

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

すべてのクライアントに表示される内容

回答は、モデルが読み取るための Markdown です。ツールが何らかのデータを返す場合、Claude Code と Codex は構造化データのみをモデルに表示するため、サーバーはデフォルトではデータを返さず、すべてのクライアントが同じテキストを読み取ります（プログラムから利用する場合は --structured-output を追加すると、構造化データが返されます）。すべてのツールは読み取り専用としてマークされているため、どのクライアントも呼び出しごとに承認を求めません。また、大きなドキュメントの読み込みに時間がかかる場合でも、1 分以内に応答し、バックグラウンドで処理を完了します。

たとえば、次のように質問できます。

• マルチスレッドカウンターのスケーリングが 2 スレッドを超えると止まるのはなぜですか？
• perf stat の出力を貼ります。どこに時間がかかっていますか？
• gcc に「not vectorized: complicated access pattern」と表示されます。何を変更すればよいですか？
• cycle_activity.stalls_l3_miss は何をカウントしていますか？
• Intel の最適化マニュアルには、ストアフォワーディングについて何と書かれていますか？
• NUMA について、実際に実行できる内容で締めくくる学習順序を教えてください。
• cppreference がリストにないのはなぜですか？
• 「AVX-512 は Zen 5 で 2 倍の性能を発揮する」という主張を、リストで引用しますか？

自分の作業で使う

ask は質問と、任意でユーザーが貼り付けた内容を context として受け取ります。サーバーはモデルを介さず、その出力自体を読み取ります。

• perf stat のプレーン形式、-x 形式、-j 形式（CPU ごとの出力とインターバル出力を含む）：読み取ったカウンターと、そこから計算した比率（サイクルあたりの命令数、周波数、分岐、キャッシュ、TLB のミス率、命令 1,000 件あたりのミス数、ストールサイクルの割合、フォールト数とコンテキストスイッチ数の毎秒値）を、それぞれの計算式とともに示します。計算は perf が独自の列を算出する方法に従います。ハイブリッド構成の P コアと E コアのカウントを相互に割ることはありません。
• トップダウン分析：perf stat --topdown、-M TopdownL1、AMD の PipelineL1 グループ、または toplev によるレベル 1 と、-M TopdownL2 によるレベル 2。レベルにフラグを付けるのは、列挙された情報源が示すしきい値に照らしてのみです。Intel 独自の値は同社の TMA メトリクスシートから取得し、Intel の P コアにのみ適用したうえで、フラグごとに出典を示します。それ以外は判定を付けず、測定値として報告します。フラグが付いたレベルに応じて、回答はリスト内の該当箇所に誘導されます。メモリがボトルネックの実行はメモリ階層へ、フロントエンドがボトルネックの実行はフェッチとデコードへ誘導されます。
• マシン：PMU とイベント名から Intel、AMD、Arm のいずれかが分かる場合、ほかのベンダーのハードウェアやツールに関する情報源は除外されます。
• どこまで信頼できるか：多重化されたカウンター（メトリクスグループを含む、最も低い実行割合）、カウントされなかったイベントやサポートされていないイベント、合算した -I インターバルの数、パーサーが読み取れなかった行を、推測せずに列挙します。
• perf 自体のエラー：メトリクスグループの欠落、perf_event_paranoid による拒否、不明またはサポートされていないイベント、NMI ウォッチドッグについて、単語ごとに検索するのではなく、perf 自身が推奨する対処法とともに説明します。
• gcc の -fopt-info と clang の -Rpass の報告：各ループがスカラーのままになった理由をループごとに数え、自動ベクトル化に関する情報源とベンチマークの項目に振り分けます。
• アセンブリとコード：オペコードのバイトを含む場合と含まない場合の objdump -d、gdb の disassemble、perf annotate、ソースコード。重要な命令や識別子（ギャザー、アトミック、フェンス、組み込み関数、alignas、restrict）は対応するセクションに振り分け、ループの処理内容も同様に扱います。たとえば、反復をまたいで持ち越される浮動小数点数の合計は、報告にループがベクトル化されたとあっても、-fassociative-math がなければ加算の直列チェーンのままです（また、パックされた乗算の後に連続するスカラー加算が続くアセンブリ上の形状も扱います）。早期終了や、構造体の配列から読み取られるフィールドも対象です。

イベント名、報告、識別子に基づいて検索先が絞られるため、返される抜粋は質問だけでなく、貼り付けられた出力に即したものになります。

回答では、リスト内のどの情報源から本文を引用し、どの情報源からは引用していないかを必ず示します。各項目には、引用済み（抜粋とページを記載）、ライブラリ内にあるが該当する抜粋がない（内部を確認する read_source 呼び出しを記載）、またはこのマシンでは未読（ブロックされた、プロキシに拒否された、まだ取得されていない、説明だけの講演などの理由を記載）のいずれかの印が付きます。モデルには、提示された抜粋を通じてのみ主張の出典を示すよう指示され、未読の情報源は引用ではなく参考資料として提示されます。質問に関連する、リスト掲載論文には要旨が添えられます。また、各抜粋には文書自体のタイトル（「Untitled Document」のような仮のタイトルであることが多い）ではなく、リストに掲載された情報源のタイトルが付けられます。

回答はデフォルトで簡潔です。抜粋は該当部分に絞り、ベンチマークと編集記録は関連する場合にのみ含めます。また、各抜粋には ID が付き、read_source(ref, passage=id) で全文を展開できます。detail="full" は抜粋全体と関連するすべての内容を返します。 ライブラリが変更されるまでは、同じ質問への回答にキャッシュが使われます。

初回実行：ライブラリの構築

サーバーはリポジトリからすぐに応答します。バックグラウンドでは、リンク先のソースをローカルライブラリに取得します。

• 保存先：Linux では ~/.local/share/cpu-perf、macOS では ~/Library/Application Support/cpu-perf、Windows では %LOCALAPPDATA%\cpu-perf、または CPU_PERF_DATA_DIR です。
• 所要時間：ネットワークの状況やマニュアルの大きさによって、数分から15分ほどです。クライアントがサーバーを終了しても、クロールは停止した場所から再開されます。
• サイズ：文章、キーワードインデックス、埋め込みを含む SQLite ファイルが1つで、最大でも数百メガバイトです。ダウンロードしたファイル自体は保存されません。
• 対象外：非常に大きな PDF はページ数の上限までインデックス化され、残りは必要に応じて読み込まれます。スキャンした PDF、圧縮された PostScript、動画にはインデックス化できるテキストがありません（動画についてはタイトルと説明を保持します）。

進捗を表示しながらフォアグラウンドで構築するには、cpu-perf index を実行します。cpu-perf status --detail を実行すると、すべてのソースの状態が一覧表示されます。

複数の MCP クライアント（たとえば Claude Desktop、Claude Code、Cursor を同時に使用する場合）は、1つのライブラリを共有します。数分ごとに、データフォルダーの OS ロックを保持するクライアントのいずれかがメンテナンスを行います。新規、更新時期、または再試行時期を迎えたソースを取得し、ベクトルがない文章を埋め込み、以前のリリースで構築されたライブラリをその場で最新の状態にします。ソースを再取得するのは、その種類のドキュメントの読み取り方法がリリースによって改善された場合に限られます（このリリースでは、PDF の行をまたぐハイフン付きの単語を結合します）。更新に失敗した場合、ドキュメントがなくなっていない限り、ライブラリ内の既存のコピーは保持されます。クライアントが終了またはクラッシュすると、システムによってロックが解除されます。また、リクエストの処理中はメンテナンスが一時停止します。

一部の発行元（ACM、IEEE、Intel と Arm のポータルの一部）は、自動クライアントを拒否したり、ブラウザーでしかドキュメントを表示できないようにしたりします。これらのソースは、ブロックまたは一部取得として報告され、その理由は各リンクの注記に記載されます。回答では、代わりにそのリンクを参照するよう案内します。対応状況は実際の状態のまま報告し、実態以上に見せることはありません。

セマンティック検索には、小型の静的埋め込みモデル potion-base-8M を使用します。このモデルは一度だけダウンロードされます。モデルを使用できない場合（オフライン、または CPU_PERF_EMBED_MODEL=none の場合）、ライブラリはキーワード検索のみを使用します。

著作権と配慮

ライブラリは、ユーザー自身のマシン、または運用者自身のサーバー上で、リストにリンクされた公開 URL から構築されます。クロールした内容がコミット、公開されたり、パッケージやコンテナーイメージに同梱されたりすることはありません。クローラーはそれらのドキュメントのみを取得し、身元を明示し、同一ホストへのリクエスト間隔を空け、レート制限を受けた場合はアクセスを控えます。リストにあるリンクは、読者が開く場合と同じ方法で読み取るため、--respect-robots を指定して要求しない限り、robots.txt は参照しません（CPU_PERF_RESPECT_ROBOTS=1）。その場合にサイトが禁止するソースは、ブロックとして報告されます。

ツール

ツール	回答する内容
ask	質問に対する根拠：リンク先ソースから最適な抜粋（ページ番号付き）、リストの項目とその理由、該当する場合は一致するベンチマークと編集記録。context を指定すると、貼り付けられた出力のメトリクスと注記も含まれます。最初に呼び出してください。
lookup	項目、セクション、ベンチマーク、記録、注記、ベンチマークコードをランキング付きで検索するか、ソースのテキストを検索します（scope="sources"）。
search、fetch	IDでドキュメント（項目、セクション、ベンチマーク、記録項目、ソースの抜粋）を見つけ、全文を読み取ります。ChatGPT のディープリサーチと企業ナレッジを併用する方法です。
get_section	目次、または依存関係順にベンチマークとウォッチリストの昇格条件を含むセクションを1つ取得します。
get_entry	項目を文脈とともに取得します：掲載理由、前後に読む内容、ほかに掲載されている場所、ベンチマーク、その項目で検討した数値、除外した代替案、リンクに関する注記。
reading_path	トピックについて読むものを順番に示し、最後にその内容を再現するベンチマークを提示します。
get_benchmark	ベンチマークの主張、マシン（7つのフィールド）、結果、分析、制限、コード、ビルドおよび実行スクリプト、生の出力とメトリクス。
editorial_record	掲載の有無とその理由：ルールによる却下、判定別の主張、リンクに関する注記。
check_evidence	パフォーマンスに関する主張を7つのフィールドで監査し、類似の数値をリストがどう評価したかを示します。
read_source	ライブラリ内、またはその場で取得した、リンク先ソース1件のテキストを読み取ります。query を指定すると一致する抜粋のみ、passage を指定すると抜粋1件の全文を読み取ります。
read_file	サーバーが保持するリポジトリ内の任意のファイル。
library_status	提供中のリストのコピー、日次更新の状態、リンク先資料のインデックス化状況、ブロックされた項目とその理由。

リソース： cpuperf://readme、cpuperf://contents、cpuperf://rules、 cpuperf://watchlist、cpuperf://benchmarks、およびテンプレート cpuperf://section/{number}、cpuperf://entry/{id}、 cpuperf://benchmark/{slug}、cpuperf://file/{+path}、cpuperf://source/{id}。

プロンプト： ask_the_list、study_plan、diagnose（リスト独自の手法： USE メソッド、役立つカウンター、トップダウン、ルーフライン、そしてメカニズム）、 audit_claim、reproduce_benchmark、review_candidate（提案された項目を CONTRIBUTING.md に照らして事前審査します）。

項目 ID（4.3.5、Start here 1.7）は README に従い、README の変更に応じて変わります。すべての出力には URL も含まれますが、こちらは変わりません。

リストを最新の状態に保つ

1日1回（マシン上のすべてのクライアントで共有するリクエスト1件）、サーバーは GitHub にリストの最新コミットを問い合わせます。新しいコミットがある場合は、 そのコミットをダウンロードし、リスト自体のファイルのみ（パッケージに含まれるものと同じファイル群）を残して、それらが解析可能であり、提供中のリスト以上のサイズであることを確認してから、2回の呼び出しの間に切り替えます。新しいリストが追加したリンクは次回のメンテナンス時に取得され、削除されたリンクは回答から除かれます。項目 ID が現在別のソースを指している場合は、get_entry でその旨が示されます。

ダウンロードしたファイルはデータとして読み取られます。ファイルから何かをインポートしたり実行したりすることはありません。書き込み前にファイルサイズとパスを確認し、解析できないコピーは無効のままにして、サーバーのアップグレードを促す注記を library_status に表示します。チェックアウト（--repo、またはリポジトリからの実行）は更新されません。これは編集中のコピーです。CPU_PERF_AUTO_UPDATE=0 で確認を無効にし、CPU_PERF_UPSTREAM=owner/repo で代わりにフォークを追跡します。

正確性を保つ仕組み

• misc/scripts/check_format.py と同じ文法で README を読み込みます。両者にずれがあるとテストが失敗し、解析した件数が README のバッジや変更履歴の合計と一致しない場合にも、別のテストが失敗します。
• README が信頼できる情報源です。各セクションのドラフトから取り込むのは、ファイル番号で結合した Rejected、Claims、Link notes、Benchmark proposal の各ブロックのみです。
• ベンチマークの数値は 1 台の Apple M4 Pro から得られたものです。出力にはその旨を記載し、サーバーは 7 つすべてのフィールドが揃っている場合に限り、数値を引用するようクライアントに伝えます。
• ソースからのテキストはフェンスで囲み、信頼できないデータとしてラベル付けします。
• 貼り付けられた出力のメトリクスは、出力に示されたとおりに正確に計算します。適用するしきい値は、Intel が公開しているトップダウン分析レベル 1 のものだけで、毎回出典を明記します。
• 日常的な質問を集めた検索テストセットでランキングを検証します。変更のたびに再現率を維持する必要があります（python tests/eval_queries.py path/to/library.sqlite でレポートが出力されます）。

取得時の安全性

リポジトリに記載された URL のみを読み込みます。すべてのリクエストとリダイレクトを検証します。デフォルトポートの http と https のみを許可し、ホストはパブリックアドレスに解決される必要があります（ループバック、プライベート、リンクローカル、クラウドメタデータの各アドレスは不可）。接続先は検証済みのアドレスに固定されます。ダウンロードと展開には、サイズ上限と時間制限を設けています。HTTPS_PROXY と NO_PROXY を尊重します。

速度

リポジトリに関する情報はすべてメモリに保持し、検索はすべて辞書の走査で行います。文章は SQLite FTS5 と量子化された埋め込みの行列を使って提供します。cpu-perf --selftest を実行すると、お使いのマシンでの読み込み、インデックス作成、クエリの所要時間を確認できます。

設定

変数（フラグ）	意味
CPU_PERF_DATA_DIR (--data-dir)	ライブラリの保存先です。
CPU_PERF_EMBED_MODEL (--embed-model)	model2vec のモデル ID、またはキーワード検索のみを使う場合の none です。
CPU_PERF_AUTO_INDEX=0 (--no-auto-index)	バックグラウンドでライブラリを構築しません。
CPU_PERF_LIVE_FETCH=0 (--no-live-fetch)	read_source はインデックス済みのものだけを提供します。
CPU_PERF_LIBRARY=0 (--no-library)	リポジトリのナレッジのみを使用します。
CPU_PERF_RESPECT_ROBOTS=1 (--respect-robots)	robots.txt で禁止されているものをスキップします。デフォルトでは、一覧にあるすべてのリンクを読み込みます。
CPU_PERF_REPO (--repo)	バンドルされたコピーの代わりにチェックアウトを提供します。
CPU_PERF_AUTO_UPDATE=0 (--no-auto-update)	インストール済みのリストを提供し、毎日の確認は行いません。
CPU_PERF_UPSTREAM	毎日の確認対象となる owner/repo（フォークなど）です。
CPU_PERF_MAINTENANCE_SECONDS	メンテナンス処理の実行間隔です（デフォルトは 300）。
CPU_PERF_STRUCTURED_OUTPUT=1 (--structured-output)	プログラムから利用するクライアント向けに、構造化データと出力スキーマも返します。
CPU_PERF_LIVE_WAIT_SECONDS	「取得中です」と応答するまで、ライブ読み込みを待つ時間です（デフォルトは 40）。
CPU_PERF_TRANSPORT、_HOST、_PORT、_PATH	HTTP での提供（--transport http）です。
CPU_PERF_ALLOWED_HOSTS (--allowed-host)	HTTP 経由で受け入れるホスト名です。
GITHUB_TOKEN	不要です。プルリクエストの説明は公開 API から取得します。

HTTP 経由での提供

cpu-perf を使うクライアントは、上記のとおりすべてローカルで起動するため、これを必要とする人はいません。これは、共有インスタンスを 1 つ実行するためのものです。同じサーバーが Streamable HTTP にも対応しています。リポジトリのルートから、次のコマンドを実行します。

docker build -f misc/mcp/Dockerfile -t cpu-perf .
docker run -p 8000:8000 -v cpu-perf-data:/data -e CPU_PERF_ALLOWED_HOSTS=your-host cpu-perf

エンドポイントは /mcp で、ヘルスチェックには /healthz を使います。HTTPS の背後に配置してください。許可されたホストが指定されていない場合、サーバーは localhost 以外のホスト宛てのリクエストを拒否します。これにより、DNS リバインディングから保護されます。認証はないため、URL を知っていれば誰でもツールを呼び出せます。これらのツールはすべて読み取り専用です。コンテナは初回起動時にライブラリを /data ボリュームにビルドします。イメージ自体にクロールしたテキストは含まれません。公開インスタンスでは、検索エンジンが抜粋を表示するのと同じように、他の人の作品からの引用とリンクが提供されます。

開発

cd misc/mcp
pip install -e ".[test]"
pytest
cpu-perf --selftest

編集可能モードでインストールすると、チェックアウトした内容が読み込まれるため、README の編集は次回の起動時に反映されます。テストにネットワークは不要です。クローラーはローカルのフィクスチャサイトと決定論的なエンベッダーを使って実行され、日次更新は GitHub のローカルな代替環境に対して実行されます。CPU_PERF_EVAL_DB にクロール済みの library.sqlite を指定すると、取得テストも実際のソースを使って実行されます。

リリース

pyproject.toml でバージョンを設定してマージした後、同じバージョンで main 上のマージコミットにタグを付けます。

git tag mcp-v0.1.1 && git push origin mcp-v0.1.1

.github/workflows/mcp-release.yml が信頼済みパブリッシングを使ってビルド、テストを行い、PyPI に公開します。初回リリース前に一度だけ、PyPI でプロジェクト cpu-perf、オーナー usamahz、リポジトリ cpu-performance-engineering、ワークフロー mcp-release.yml、環境 pypi を指定した保留中のパブリッシャーを追加します。GitHub は初回実行時に pypi 環境を作成します。

リリース候補（たとえば 0.1.1rc1）にも同じ方法でタグを付けます。バージョンを指定した場合にのみインストールされ、uvx [email protected] のように実行します。そのため、テストしても最新リリースを使っている人に影響することはありません。

同じワークフローが、ワークフロー自身の GitHub ID でサインインし、server.json の内容をMCP Registryに登録するため、リリース時にほかの手順は不要です。server.json のバージョンは pyproject.toml と同じです。レジストリは、PyPI に表示される README 内の次の行を確認して、PyPI パッケージが掲載情報に対応していることを証明するため、この行はここに残します。

mcp-name: io.github.usamahz/cpu-perf

ライセンス

リポジトリと同じく MIT です。wheel にはリポジトリのファイルと LICENSE が含まれています。