arm-code-mcp

arm-code-mcp

一个帮助 AI 助手优化 Arm64 上 Linux 工作负载的 MCP 服务。 它会解析 perf report 输出，为热点循环推荐 NEON SIMD intrinsic， 并检查 Python 依赖清单中是否有适用于 arm64 的 wheel—— 全程离线、结构化，可从 Claude Code、GitHub Copilot 和 Codex 调用。

---

包含内容

• analyze_perf_output — 将 perf report --stdio 解析为按排名排列的热点符号列表
• suggest_neon_intrinsic — 在 110 个精选 NEON intrinsic 中进行语义搜索和关键词搜索
• check_arm64_deps — 标记 requirements.txt、pyproject.toml 或 Dockerfile 中缺少 arm64 wheel 或需要特殊处理的软件包

---

前提条件

• 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"]
    }
  }
}

重启客户端。现在即可使用全部三个工具。

---

工具

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 wheel（例如，仅支持 GPU 的软件包）
warning	存在 wheel，但需要使用变通方法或替代来源
info	有可用 wheel；适用版本约束或系统库说明

---

配置

所有环境变量均为可选项。服务无需配置即可运行。

变量	默认值	说明
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	Embedding 缓存目录

将环境变量传递给容器：

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

---

评估

suggest_neon_intrinsic 使用真实的 all-MiniLM-L6-v2 embedding 模型， 在 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 相同。