neurarch-mcp

PyTorch MCP server: lint, verify and rank a neural network design before you train it, from Claude Code, Cursor, Claude Desktop, VS Code, Windsurf or Codex.

Your coding agent reads your model as source text, so it guesses at shapes, parameter counts, and what an edit breaks. neurarch-mcp hands it the structured graph instead, plus the verifier: the design rules, the full readiness / cost / deployment verdict, and which of several candidate designs is worth the GPU time. Trace the model to get real shapes, or point it at a saved graph, a PyTorch .py, or a Hugging Face repo. Every tool but two runs on your machine, offline, with no API key and no account.

The two that do not are the point of the other half of this README. A frontier model can read your architecture and reason about it; what it structurally cannot do is tell you what happened the last time this exact structure trained here. That is not in the weights and not in the repository. plan and history read it from your organisation's ledger, and they are the only tools in this package that open a socket.

_{Every number above is produced by the tools, not guessed by the model. 13s webm.}

Install

claude mcp add neurarch -- npx -y neurarch-mcp /abs/path/to/model.py        # Claude Code

Per-client config for Claude Desktop, Cursor, VS Code, Windsurf and Codex is below. Node 20+ is the only requirement; there is no install step beyond npx.

What it looks like

A real exchange against examples/tiny-gpt.neurarch.json:

You ▸ Where does the parameter budget live, and is it safe to drop block_1?

Claude ▸ (calls describe_architecture)
  tiny-gpt: 8 layers, depth 7, 57.8M params, 8.27 GMACs.
  Heaviest by params: token_embedding (25.7M, 44%), lm_head (25.7M), block_0/1 (3.1M each).
  Heaviest by compute: lm_head, then the two decoder blocks. Validation: clean.

  (calls layer_impact { names: ["block_1"] })
  Downstream of block_1: final_norm and lm_head (shape-sensitive, weight-carrying), then output.

  The budget is dominated by the embedding + LM head (~89%), not the decoder blocks,
  so dropping block_1 frees only ~3.1M params (~5%) while removing one of just two
  decoder layers. It is structurally safe (final_norm just re-reads block_0's output),
  but it is the wrong lever if your goal is shrinking the model. Quantizing the
  embedding/head would do far more.

And the one this server is built around. Point it at examples/tiny-vit.py, plain PyTorch source with a bug planted in it, and ask "lint this model":

block  head-dim-divisibility [attn:multiHeadAttention]: embed dim (258) must be
       divisible by numHeads (8); head_dim would be 32.25

That is a runtime crash sitting in source that reads fine, found offline in milliseconds, with no key and no account. The same rule set the Neurarch CI action reports, so a clean result here is a clean CI run. The rules are measured (the crash rules: 96 of 96 blocked graphs crashed PyTorch forward, 80 of 80 passes ran); the static parser in front of them is the weaker half, and we measured that too.

Three ways in, in order of how well they work

A .neurarch.json saved from the Neurarch app (File → Save) is the fourth, and carries shapes, groups and design notes. Add --watch so the agent sees app-side saves without a restart.

The flow this server is built around, in one line each: trace_model for a graph with real shapes, plan for the card that says whether to spend the GPU time, lint_model / check_design for the offline detail behind it, suggest_fix for the edit. Everything else answers a question one of those raised.

What the static parser can read

We measured it rather than describe it: docs/REAL_REPOS_STUDY.md runs the parser and linter over 116 model files from 59 popular repositories (nanoGPT, HF modeling_*.py, timm, torchvision, DiT, MAE, CLIP, Mamba, SAM, diffusers and more). Re-measured 2026-09-03 with the current engine: the parser returns a graph for 86% of files and a graph a person would recognise as the model for 41% (Llama, Qwen2, Mistral and Gemma come back as 58-node graphs; nanoGPT as 72), up from 63% and 8% in August. The linter's findings on those graphs are still not trustworthy: every block and warn it raised was hand-judged and none was a real defect, because the parser records construction order as data flow and never sees forward(), so residual adds, functional activations and config-selected heads all read as missing or misordered. The graph is good enough to orient with and not yet good enough to lint from; run trace_model before acting on a finding from a .py.

Three consequences are in this release. A graph from source carries a parseQuality grade (full, partial, thin) on describe_architecture and lint_model, with the fix named. Dimension rules are held back on layers whose dimension is still source text, and the count is reported as suppressed rather than dropped. And find_models marks thin parses partial so an agent does not build a plan on two layers. For real repositories, use neurarch-trace: it reads the numbers at runtime, which is the only place they exist.

Every read tool also takes an optional model_path, so one server covers a whole repository: ask about baseline.py, then variant_b.neurarch.json, then zoo:llama-3-8b, without restarting anything. find_models tells the agent what is there.

Tools

Start here: the plan card, and the memory behind it

These two are the front door, and the only two tools in this package that reach the network. plan is the artifact: the same card the Neurarch CI bot posts on a pull request and the neurarch-trace CLI prints, so the agent and the reviewer read the same words about the same graph.