arm-code-mcp

arm-code-mcp

Arm64 上の Linux ワークロードを最適化する AI アシスタントを支援する MCP サーバーです。 perf report の出力を解析し、ホットループ向けの NEON SIMD intrinsic を推奨し、 Python の依存関係マニフェストを監査して arm64 ホイールの利用可否を確認します。 すべてオフラインで動作し、構造化されており、Claude Code、GitHub Copilot、Codex から呼び出せます。

---

内容

• analyze_perf_output — perf report --stdio を解析し、ホットシンボルを順位付けしたリストを返します
• suggest_neon_intrinsic — 厳選された 110 個の NEON intrinsic を対象に、セマンティック検索とキーワード検索を行います
• check_arm64_deps — arm64 ホイールがない、または特別な対応が必要な requirements.txt、pyproject.toml、Dockerfile 内のパッケージを検出します

---

前提条件

• Docker
• MCP 対応の AI アシスタント（Claude Code、GitHub Copilot、Codex）

---

クイックスタート

docker pull jeannjohnson/arm-code-mcp:latest

MCP クライアントの設定（例：~/.claude/mcp.json）に追加します。

{
  "mcpServers": {
    "arm-code-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "jeannjohnson/arm-code-mcp:latest"]
    }
  }
}

クライアントを再起動します。3 つのツールがすべて利用可能になります。

---

ツール

analyze_perf_output

perf report --stdio の生出力を解析し、オーバーヘッド順に並べた上位のホットシンボルを返します。

analyze_perf_output(
    perf_report_text: str,          # raw stdout of `perf report --stdio`
    top_n: int = 10,                # max symbols to return
    min_overhead_pct: float = 0.5,  # ignore symbols below this %
) -> dict

応答例：

{
  "summary": {
    "total_samples": 5432100,
    "total_events": null,
    "command": "myapp"
  },
  "hot_symbols": [
    {"overhead_pct": 24.17, "samples": 1245, "command": "myapp",
     "module": "myapp", "symbol": "process_buffer"},
    {"overhead_pct": 12.34, "samples": 636, "command": "myapp",
     "module": "libc-2.31.so", "symbol": "__memcpy_avx_unaligned_erms"}
  ],
  "warnings": []
}

---

suggest_neon_intrinsic

110 個の intrinsic を収録した厳選ナレッジベースを対象に、ハイブリッド方式のセマンティック検索と完全一致検索を行い、ホットループ向けの NEON intrinsic を推奨します。

suggest_neon_intrinsic(
    operation_description: str,    # e.g. "32-bit float multiply-accumulate"
    target_arch: str = "armv8-a",  # "armv8-a" | "armv8.2-a" | "armv9-a"
    top_k: int = 5,
) -> dict

応答例：

{
  "matches": [
    {
      "intrinsic": "vmlaq_f32",
      "signature": "float32x4_t vmlaq_f32(float32x4_t a, float32x4_t b, float32x4_t c)",
      "header": "<arm_neon.h>",
      "min_arch": "armv8-a",
      "description": "Multiply-accumulate: a + (b * c), lane-wise, 4x f32.",
      "score": 0.9142
    }
  ],
  "notes": "Filtered to armv8-a. KB contains 110 entries (103 compatible)."
}

---

check_arm64_deps

依存関係マニフェストをスキャンし、既知の arm64 互換性問題があるパッケージを検出します。 完全オフラインで動作し、ネットワーク呼び出しはなく、高速で決定論的です。

check_arm64_deps(
    file_content: str,                    # raw text of the manifest
    file_type: str = "requirements.txt",  # "requirements.txt" | "pyproject.toml" | "Dockerfile"
) -> dict

応答例：

{
  "checked": ["numpy", "tensorflow", "cupy-cuda12x", "faiss-cpu", "requests"],
  "issues": [
    {"package": "cupy-cuda12x", "severity": "error",
     "message": "GPU-only package with no arm64 wheel. Use cupy with ROCm or a CPU fallback."},
    {"package": "tensorflow", "severity": "warning",
     "message": "Official TensorFlow PyPI wheels are x86-only before 2.10; use tensorflow-aarch64 or build from source."},
    {"package": "faiss-cpu", "severity": "warning",
     "message": "No official arm64 wheel on PyPI; build from source or use the conda-forge package."},
    {"package": "numpy", "severity": "info",
     "message": "arm64 wheels available from PyPI since 1.21.0. Ensure version >= 1.21.0."}
  ],
  "summary": "Checked 5 package(s): 1 error(s), 2 warning(s), 1 info(s)."
}

重大度レベル：

レベル	意味
error	arm64 ホイールがありません（例：GPU 専用パッケージ）
warning	ホイールはありますが、回避策または代替ソースが必要です
info	ホイールは利用可能ですが、バージョン制約またはシステムライブラリに関する注記があります

---

設定

環境変数はすべて任意です。設定なしでサーバーを利用できます。

変数	デフォルト	説明
ARM_CODE_MCP_LOG_LEVEL	INFO	ログの詳細度：DEBUG、INFO、WARNING
ARM_CODE_MCP_KB_PATH	同梱の JSONL	neon_intrinsics.jsonl のパスを上書きします
ARM_CODE_MCP_CACHE_DIR	~/.cache/arm-code-mcp	埋め込みキャッシュディレクトリ

環境変数をコンテナに渡します。

docker run --rm -i \
  -e ARM_CODE_MCP_LOG_LEVEL=DEBUG \
  jeannjohnson/arm-code-mcp:latest

---

評価

suggest_neon_intrinsic は、実際の all-MiniLM-L6-v2 埋め込みモデルを使い、手作業で厳選した 15 組の（クエリ、期待する intrinsic）ペアで評価されます。 現在のベースライン：

指標	スコア
hit@1	0.667
hit@3	0.933
hit@5	1.000
MRR	0.817

回帰チェックでは、hit@3 が 0.70 を下回るとゼロ以外の終了コードで終了します。

評価ハーネスをローカルで実行します。

uv sync
make eval

評価方法と既知の制限事項については、eval/README.md を参照してください。

---

開発

git clone https://github.com/jean-johnson-zwix/arm-code-mcp
cd arm-code-mcp
uv sync
make test    # 78 tests
make lint    # ruff check + format
make eval    # real model, 15 gold queries

Makefile のターゲット：

ターゲット	説明
make setup	uv sync + pre-commit のインストール
make test	テストスイート全体を実行します
make lint	ruff check + ruff format --check
make eval	NEON 検索評価ハーネスを実行します
make docker-build	arm-code-mcp:dev をローカルでビルドします
make docker-run	ローカルの開発イメージを stdio 経由で実行します

マルチアーキテクチャイメージ（linux/amd64 + linux/arm64）は、v*.*.* タグで .github/workflows/release.yml によって自動的にビルドされ、プッシュされます。

---

ナレッジベースのメンテナンス

NEON intrinsic のナレッジベースは src/arm_code_mcp/kb/data/neon_intrinsics.jsonl にあります（110 件）。intrinsic の追加やモデルのアップグレード後の更新については、docs/kb-refresh.md を参照してください。

---

ロードマップ

ツール

• parse_flamegraph — Linux perf のフレームグラフ SVG からホットパスを抽出します
• suggest_sve2_intrinsic — 検索対象を SVE2 intrinsic（Neoverse V2、Cortex-X4）に拡張します

評価

• 各ゴールドペアに対する複数クエリの言い換え拡張
• セマンティック候補に対する再ランキング処理
• 指標の分散を抑えるため、ゴールドセットを拡大（クエリ 50 件以上）

---

デモ

近日公開。

---

コントリビューション

スター、フォーク、イシューを歓迎します。GitHubで PR を作成するか、イシューを登録してください。

初めてのコントリビューションにおすすめのイシュー：

• kb/data/neon_intrinsics.jsonl に NEON intrinsic の項目を追加する
• SVE2 intrinsics の gold 評価クエリを追加する
• Linux の perf flamegraph SVG ファイル用の parse_flamegraph ツールを追加する

---

ライセンス

Apache 2.0 — arm/mcp と同じです。