convez.ai
MCP ServerDesenvolvimento WebIntermediário
neurarch-ai

Neurarch MCP

neurarch-ai/neurarch-mcp

Análise estrutural de redes neurais integrada ao Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe grafos de modelos neurais (PyTorch, JAX, etc.) para Claude Code, Cursor e outros agentes MCP-aware. Fornece consciência estrutural da rede neural: camadas, contagem de parâmetros, FLOPs, análise de impacto e diagramas Mermaid sem necessidade de colar código na conversa.

Instalação

$npx convez-ai neurarch-ai/neurarch-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 6 dias
Versão
v0.15.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Debugar arquiteturas de modelos com IA em tempo real
  • Reescrever loops de treinamento com conhecimento completo do grafo
  • Analisar dependências entre camadas e impacto de mudanças
  • Documentar distribuição de parâmetros e budget computacional

Veredito

Ferramenta especializada e bem-construída para pesquisadores e engenheiros de ML que usam Claude Code. Resolve um problema real (consciência estrutural de modelos) com implementação sólida em TypeScript e integração MCP nativa. Nicho técnico mas impactante.

README

A tradução para o português deste README ainda está na fila.

neurarch-mcp

CI npm version npm downloads License: MIT Model Context Protocol GitHub stars Try Neurarch

Model Context Protocol server that exposes a Neurarch model graph to Claude Code, Cursor, 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.

▶ Watch the 13s demo — every number above is produced by the tools, not guessed by the model.

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:

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. Just point your MCP client at it via npx:

// ~/.claude/mcp_servers.json (Claude Code)
{
  "mcpServers": {
    "neurarch": {
      "command": "npx",
      "args": ["-y", "neurarch-mcp", "/abs/path/to/your-model.neurarch.json"]
    }
  }
}

Every MCP-aware client uses the same command + args shape, only the config file differs:

ClientMCP config
Claude Code~/.claude/mcp_servers.json
Cursor.cursor/mcp.json
Windsurfits MCP config (same command + args)
Codexits MCP config (same command + args)

To produce the model file: open your model in the Neurarch app, then File → Save (.json). The MCP server reads that file directly.

Try it in 30 seconds (no app needed)

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

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

Then ask: "describe the architecture, and tell me where the parameter budget lives."

Tools

Read (always available)

ToolWhat it does
get_model_summaryOne-shot overview: layer count, total params, dominant types, input/output shape.
describe_architectureOne-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_layerFull definition of one layer by name: params, shapes, notes, upstream/downstream ids.
compare_layersStructural diff of two layers: same-type, param-count delta, shape match, and exactly which param keys differ.
find_layersSearch layers by type, name regex, scope prefix, or augmentation (e.g. frozen layers); optionally rank by parameter count.
layer_impactBlast radius of changing a layer or matched set. Flags shape-sensitive and weight-carrying downstream layers.
validate_modelStructural invariants: cycles, dangling connection refs, duplicate ids/names, orphan layers.
find_pathShortest directed path between two layers, or null when unreachable.
list_connectionsFlat edge list with optional from / to filters.
param_count_by_blockParameter counts grouped by block / scope / type.
flops_by_blockMAC counts (FLOPs ÷ 2) grouped by block / scope / type.
mermaid_diagramRender the model as Mermaid flowchart TD syntax; groups render as labelled subgraphs. Truncates past 60 layers (keeping the topological head).
list_blocksList collapsed groups (or scope-derived blocks if none): members, params, FLOPs.
get_blockDrill 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_modelsStructurally diff the current model against another .neurarch.json file: layers added / removed / modified (field-level) and connection changes.
list_hyperparamsModel-level hyperparameters (learning rate, batch size, ...) the user set in the app.
get_design_notesPinned design rationale: agent / advisor / manual notes, optionally filtered by layer.

Write (opt in with --write)

ToolWhat it does
add_layerInsert a new layer, optionally auto-wired downstream of an existing one.
modify_layerShallow-merge params, rename, or change scope. Returns a before/after diff.
add_connectionWire two existing layers. Fails on self-loops and duplicate edges.
delete_layerRemove a layer and every connection touching it. Invalidates downstream shapes.
delete_connectionRemove a single directed edge. Invalidates the target's cached shape.
save_modelPersist the in-memory model to disk. Call this after any mutation.

layer_impact is the headline read tool. Before the agent recommends delete every conv_X, it can call layer_impact and tell the user "this rewires 8 downstream layers, 3 of which carry weights and will need rebuild." validate_model is the headline safety tool — call it before recommending a destructive edit to surface pre-existing issues separately from the change.

Flags

  • --write — expose mutation tools. Off by default so accidental writes can't clobber a file you're editing in the Neurarch app.
  • --watch — poll the model file for changes and reload on save. Pair with the Neurarch app: edit visually, agent sees the latest graph without restarting the MCP server. Note: an external save will overwrite any unsaved in-memory edits made via --write.
  • --version (alias -v) — print the version and exit. --help (-h) prints usage and the full tool list.

Example prompt (Claude Code)

After wiring the server, in Claude Code:

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 your model.

What this is not

  • Not a generic codebase indexer. This serves one .neurarch.json file. For codebase structure, use GitNexus or similar.
  • Not connected to your Neurarch workspace. v1 reads a saved JSON file only. Live editing happens in the Neurarch web app.

Issues & Feedback

This repo is the public home for both:

  • neurarch-mcp (this MCP server): bugs, protocol changes, integration questions.
  • Neurarch (the app): canvas bugs, agent issues, linter rules, feature requests.
🐛 Report a bugSomething is broken or behaving unexpectedly.
💡 Request a featureAn idea that would make Neurarch or the MCP server better.
❓ Ask a questionSomething specific you can't figure out.
💬 Start a discussionOpen-ended ideas, design feedback, "how would you…".

Please tag issues with mcp, app, linter, or feature-request so we can triage faster.

Star this repo

If neurarch-mcp saved you from pasting an nn.Module into chat, a ⭐ helps other ML engineers find it. It is the lowest-effort way to support the project.

Contributing

A new tool is a small, self-contained PR. See CONTRIBUTING.md for the 3-step "add a tool" guide.

Development

git clone https://github.com/neurarch-ai/neurarch-mcp
cd neurarch-mcp
npm install
npm run typecheck             # tsc --noEmit
npm run build                 # tsup → dist/index.js
npm test                      # vitest (≈100 unit tests)
node dist/index.js --help     # confirm bin works

CI runs typecheck + build + test on Node 20 and 22 for every push and PR.

The package vendors a small set of pure-TypeScript utilities (model types, parameter and FLOP estimators, impact analyzer) from the main Neurarch repo. They live under src/lib/ and have no runtime dependencies beyond @modelcontextprotocol/sdk.

License

MIT. See LICENSE.

Links

  • Neurarch — the visual neural-network editor that produces the model files this server reads.
  • Model Context Protocol — the spec this server implements.
  • npm — package page.
Ver o original no GitHub

Bom para

Relacionados