# Arm-Migrate MCP

**Migrate your LLM workload to Arm — and prove the speedup with real numbers.**

Arm-Migrate is an [MCP](https://modelcontextprotocol.io) server plus a
GitHub Actions benchmark harness. Connect it to any MCP client (Claude Code,
Claude Desktop, …) and ask it to migrate an LLM inference workload to Arm64.
It will:

1. **Analyze** the workload (`analyze_workload`) — scans Dockerfiles,
   compose files, and dependency lists for migration blockers: x86-pinned
   base images, CUDA-only stacks, missing quantization, arch-specific wheels.
2. **Plan** the migration (`generate_migration_plan`) — emits ready-to-commit
   artifacts: an arm64 Dockerfile built around llama.cpp with
   [KleidiAI](https://github.com/ARM-software/kleidiai) kernels, a CI
   benchmark workflow, recommended quantization (Q4_0 for KleidiAI's
   int8mm/dotprod paths), and a migration checklist.
3. **Measure** (`trigger_benchmark` / `fetch_benchmark_results`) — runs a
   3-way benchmark matrix on GitHub's **free `ubuntu-24.04-arm` runners**:
   Arm64 + KleidiAI vs Arm64 baseline vs x86 baseline, using `llama-bench`
   with repetitions and captured CPU feature flags.
4. **Report** (`generate_report`) — turns the raw JSON artifacts into a
   migration report: prompt-processing and token-generation tokens/sec,
   deltas, hardware context, and a go/no-go recommendation.

Zero-cost, fully reproducible: everything runs on free public-repo CI.
No GPUs, no cloud account, no API keys.

## Measured results (Neoverse-N2, free GitHub Arm64 runners)

Qwen2.5-0.5B-Instruct, llama-bench, 5 repetitions, 4 threads. Full reports
with stddev and hardware context: [Q4_0](docs/EXAMPLE-REPORT.md) ·
[Q8_0](docs/EXAMPLE-REPORT-Q8_0.md).

| Comparison | Prompt proc. | Generation |
|---|---|---|
| Arm optimized kernels vs naive Arm build (Q4_0) | **+131%** | **+44%** |
| KleidiAI vs default kernels (Q4_0) | ~0% | ~0% |
| KleidiAI vs default kernels (**Q8_0**) | **+59%** | **+15%** |
| Arm64+KleidiAI vs x86 runner (Q8_0) | **+269%** | **+155%** |

The practical guidance that falls out: **Q4_0 is fast on Arm out of the box
(mainline repack kernels); Q8_0 leaves large gains on the table unless you
build with `-DGGML_CPU_KLEIDIAI=ON`.** Arm64 wins token generation — the
axis that dominates chat/agent serving cost — across every silicon draw we
measured; the x86 prompt-processing picture depends on whether GitHub's
mixed pool hands you AVX-512 (see the variance disclosure in the reports).

## Why this matters

Arm64 cloud (Graviton, Axion, Cobalt, Ampere) is routinely the cheapest
compute per vCPU, and KleidiAI makes CPU-only LLM inference genuinely usable
— but teams don't migrate because they can't predict what *their* workload
gains. Arm-Migrate closes that gap: the agent hands you the migration plan
and the measured numbers in one conversation.

## Quickstart

```bash
npm install && npm run build
```

Register with your MCP client (Claude Code shown):

```bash
claude mcp add arm-migrate -- node <path>/dist/index.js
```

Then ask: *"Analyze this Dockerfile for Arm migration and generate a plan."*

To reproduce our benchmark numbers: fork, enable Actions, run the
`arm-bench` workflow (workflow_dispatch) — the report lands in the run's
artifacts and job summary.

## Repository layout

```
src/            MCP server (TypeScript)
bench/          benchmark scripts + report generator (no deps)
templates/      generated migration artifacts (Dockerfile.arm64, …)
.github/        the arm-bench harness itself
```

## Hackathon

Built for **Arm Create: AI Optimization Challenge 2026** (Track 2 — Cloud
AI). See [RULES.md](RULES.md) for the rules digest and
[DEVLOG.md](DEVLOG.md) for an honest build log.

## License

MIT