neurarch-mcp

# neurarch-mcp

[![CI](https://github.com/neurarch-ai/neurarch-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/neurarch-ai/neurarch-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/neurarch-mcp.svg)](https://www.npmjs.com/package/neurarch-mcp)
[![npm downloads](https://img.shields.io/npm/dm/neurarch-mcp.svg)](https://www.npmjs.com/package/neurarch-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![Model Context Protocol](https://img.shields.io/badge/MCP-server-7c3aed.svg)](https://modelcontextprotocol.io)
[![GitHub stars](https://img.shields.io/github/stars/neurarch-ai/neurarch-mcp.svg?style=social)](https://github.com/neurarch-ai/neurarch-mcp/stargazers)
[![Try Neurarch](https://img.shields.io/badge/Neurarch-try_it-7c3aed)](https://neurarch.com)

Model Context Protocol server that exposes a [Neurarch](https://neurarch.com) model graph to Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Codex, and any other MCP-aware AI agent.

The agent gets **structural awareness** of your neural network: layer list, parameter counts, FLOPs, blast-radius impact analysis, and Mermaid diagrams, without you pasting 200 lines of `nn.Module` into chat.

<!-- For guaranteed inline autoplay on GitHub: drag docs/demo.webm into any GitHub
     issue or PR comment box, then replace the <video> src below with the resulting
     https://github.com/user-attachments/assets/... URL. The raw URL works as a
     poster + download fallback until then. -->
<video
  src="https://github.com/neurarch-ai/neurarch-mcp/raw/main/docs/demo.webm"
  poster="https://raw.githubusercontent.com/neurarch-ai/neurarch-mcp/main/docs/demo-poster.png"
  autoplay muted loop playsinline width="900">
  <a href="https://github.com/neurarch-ai/neurarch-mcp/raw/main/docs/demo.webm">
    <img src="https://raw.githubusercontent.com/neurarch-ai/neurarch-mcp/main/docs/demo-poster.png"
         alt="neurarch-mcp answering a model-structure question, grounded in real tool output" width="900">
  </a>
</video>

<sub>▶ [Watch the 13s demo](https://github.com/neurarch-ai/neurarch-mcp/raw/main/docs/demo.webm) — every number above is produced by the tools, not guessed by the model.</sub>

## Why

When you ask Claude Code "rewrite the training loop for my new encoder block", it sees your `train.py` but not your model. It guesses at shapes and parameter counts. `neurarch-mcp` plugs the structured model graph into the same conversation so the agent can answer "what depends on `attn_8`?" or "where does the parameter budget actually live?" with one call instead of ten.

## What it looks like

A real exchange against [`examples/tiny-gpt.neurarch.json`](./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.
```

Numbers above are produced by the tools, not estimated by the model.

## Install

No install step. Every client below launches the server the same way:

```bash
npx -y neurarch-mcp /abs/path/to/your-model.neurarch.json
```

To produce the model file: open your model in the [Neurarch](https://neurarch.com) app, then **File → Save (.json)**. The MCP server reads that file directly. Add `--watch` so the agent sees app-side saves without a restart, and `--write` if you want the agent to be able to edit the model (off by default).

Use an **absolute** path to the model file in any global config: `npx` does not run from your project directory, so relative paths only work in project-scoped configs.

### Claude Code

One command:

```bash
claude mcp add neurarch -- npx -y neurarch-mcp /abs/path/to/your-model.neurarch.json --watch
```

Or commit a project-scoped `.mcp.json` at the repo root so every collaborator gets the server automatically:

```json
{
  "mcpServers": {
    "neurarch": {
      "command": "npx",
      "args": ["-y", "neurarch-mcp", "./model.neurarch.json", "--watch"]
    }
  }
}
```

### Claude Desktop

Open **Settings → Developer → Edit Config**, or edit the file directly:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "neurarch": {
      "command": "npx",
      "args": ["-y", "neurarch-mcp", "/abs/path/to/your-model.neurarch.json", "--watch"]
    }
  }
}
```

Fully quit and reopen Claude Desktop (the config is read at startup). The tools appear under the search-and-tools icon in the chat input.

### Cursor

Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for all projects), then enable the server under **Settings → MCP**:

```json
{
  "mcpServers": {
    "neurarch": {
      "command": "npx",
      "args": ["-y", "neurarch-mcp", "./model.neurarch.json", "--watch"]
    }
  }
}
```

### VS Code (Copilot agent mode)

Create `.vscode/mcp.json` (note the `servers` key, not `mcpServers`):

```json
{
  "servers": {
    "neurarch": {
      "command": "npx",
      "args": ["-y", "neurarch-mcp", "${workspaceFolder}/model.neurarch.json", "--watch"]
    }
  }
}
```

Or from a shell: `code --add-mcp '{"name":"neurarch","command":"npx","args":["-y","neurarch-mcp","/abs/path/to/model.neurarch.json"]}'`

### Other clients (Windsurf, Codex, ...)

Same `command` + `args` shape; only the config file location differs. For clients that speak Streamable HTTP instead of stdio, run the server with `--http` and point the client at it:

```json
{
  "mcpServers": {
    "neurarch": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp"
    }
  }
}
```

If you set `NEURARCH_MCP_TOKEN`, add `"headers": { "Authorization": "Bearer <token>" }`. See [Remote access](#remote-access) for tunnels and security.

### Verify it works

Ask the agent: *"List the Neurarch tools you can see."* You should get `describe_architecture`, `layer_impact`, `validate_model` and friends (17 read tools; 6 more with `--write`). From a shell, `npx -y neurarch-mcp --help` prints usage and the full tool list.

## Try it in 30 seconds (no app needed)

This repo ships runnable example models under [`examples/`](./examples). Point the server at one and your agent can immediately answer structural questions:

```jsonc
{
  "mcpServers": {
    "neurarch": {
      "command": "npx",
      "args": ["-y", "neurarch-mcp", "./examples/tiny-gpt.neurarch.json"]
    }
  }
}
```

- [`examples/tiny-gpt.neurarch.json`](./examples/tiny-gpt.neurarch.json) — a small GPT-style decoder (embedding, 2 transformer blocks, LM head).
- [`examples/tiny-cnn.neurarch.json`](./examples/tiny-cnn.neurarch.json) — a CIFAR-style CNN (2 conv stages + classifier).
- [`examples/resnet-mini.neurarch.json`](./examples/resnet-mini.neurarch.json) — a residual block with a skip/merge node (a branchier graph for impact and path tools).

Then ask:

> Look at the Neurarch model. Where do the parameters actually live, and which block would shrink the model fastest if I cut it in half?

The agent calls `describe_architecture` (one shot: pipeline, depth, param + compute hotspots, validation), then `layer_impact` on the heaviest block, and writes a recommendation grounded in the actual numbers from the model, like the transcript above.

## Tools

### Read (always available)

| Tool | What it does |
|---|---|
| `get_model_summary` | One-shot overview: layer count, total params, dominant types, input/output shape. |
| `describe_architecture` | One-call orientation: topo-ordered pipeline, depth, IO shapes, total params/MACs, top-5 param **and** compute hotspots, validation rollup. Replaces a 4-tool chain. |
| `get_layer` | Full definition of one layer by name: params, shapes, notes, upstream/downstream ids. |
| `compare_layers` | Structural diff of two layers: same-type, param-count delta, shape match, and exactly which param keys differ. |
| `find_layers` | Search layers by type, name regex, scope prefix, or augmentation (e.g. frozen layers); optionally rank by parameter count. |
| `layer_impact` | Blast radius of changing a layer or matched set. Flags shape-sensitive and weight-carrying downstream layers. |
| `validate_model` | Structural invariants: cycles, dangling connection refs, duplicate ids/names, orphan layers. |
| `find_path` | Shortest directed path between two layers, or `null` when unreachable. |
| `list_connections` | Flat edge list with optional `from` / `to` filters. |
| `param_count_by_block` | Parameter counts grouped by block / scope / type. |
| `flops_by_block` | MAC counts (FLOPs ÷ 2) grouped by block / scope / type. |
| `mermaid_diagram` | Render the model as Mermaid `flowchart TD` syntax; groups render as labelled subgraphs. Truncates past 60 layers (keeping the topological head). |
| `list_blocks` | List collapsed groups (or scope-derived blocks if none): members, params, FLOPs. |
| `get_block` | Drill into one block (group or scope prefix): per-layer params/FLOPs, totals, and the edges crossing the block boundary (what feeds it, what it feeds). |
| `diff_models` | Structurally diff the current model against another `.neurarch.json` file: layers added / removed / modified (field-level) and connection changes. |
| `list_hyperparams` | Model-level hyperparameters (learning rate, batch size, ...) the us