circuitarium-mcp

# Circuitarium MCP

Local electronics tools for MCP-capable assistants, with support for CRUMB
save files and Logisim-evolution projects.

[![CI](https://github.com/Craftiee/circuitarium-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Craftiee/circuitarium-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/circuitarium-mcp.svg)](https://www.npmjs.com/package/circuitarium-mcp)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

Circuitarium lets an MCP host inspect circuit files without pretending that
static analysis is a running simulator. It can trace CRUMB nets, build BOMs,
run electrical rule checks, analyze Logisim projects, and optionally ask
Logisim-evolution to produce truth tables or run test vectors.

Release `0.3.0` includes 22 tools, nine read-only Resources, and four workflow
Prompts. The server is model-neutral: Codex, Claude Code/Desktop, VS Code,
LM Studio, Jan, or another local MCP host supplies the model and launches
Circuitarium over stdio. Circuitarium itself needs no OpenAI, Anthropic, or
local-model API key.

## Quick start

You need:

- Node.js 22 or newer;
- an MCP client that can launch a local stdio server; and
- a dedicated folder containing only the circuit files you want the client to
  access.

Windows, macOS, and Linux are covered by CI. CRUMB analysis and the static
Logisim tools need neither simulator nor Java.

### 1. Add Circuitarium to your MCP client

Most clients ask for the same command, arguments, and environment variable:

```text
Command: npx
Arguments: -y circuitarium-mcp@0.3.0
Environment:
  CIRCUITARIUM_MCP_ROOT=/absolute/path/to/circuit-workspace
```

The first launch can take longer while npm downloads the package. Later starts
normally use npm's cache.

Replace the path with the smallest folder that should contain the `.cru`,
`.circ`, `.vec`, and `.txt` files available to the model. Do not point it at
your home directory or a drive root.

Copyable configurations are available for:

- [Codex](examples/client-configs/codex.toml)
- [Claude Code](examples/client-configs/claude-code.md)
- [VS Code](examples/client-configs/vscode-mcp.json)
- [LM Studio](examples/client-configs/lm-studio-mcp.json)
- [Jan](examples/client-configs/jan.md)

See the [client setup guide](docs/client-setup.md) for platform-specific
examples and local-model guidance. Restart or reload the client after adding
the server.

Claude Desktop users can instead download
[`circuitarium-mcp-0.3.0.mcpb`](https://github.com/Craftiee/circuitarium-mcp/releases/tag/v0.3.0)
and open it as a local bundle. The installer asks for a circuit workspace and
offers optional Logisim JAR and Java settings.

### 2. Try a circuit with no simulator installed

Paste this into the connected client:

> Use Circuitarium. Call `electronics_capabilities`. Create the built-in
> `breadboard-led` fixture as `demo/first-led.cru` without overwriting
> anything, analyze it, and run `crumb_check_design`. Explain which findings
> are static inferences rather than simulation results.

Your client may ask you to approve creation of the synthetic file. The tool
refuses to overwrite an existing path; on a repeat run, analyze the existing
file or choose a new name.

A healthy connection creates a small synthetic file, recognizes its
breadboard and LED, and reports two floating-terminal warnings. The fixture is
independently authored and safe to redistribute; it is not a CRUMB asset.

### 3. Check the launcher from a terminal

These commands verify the published launcher without opening a server session:

```text
npx -y circuitarium-mcp@0.3.0 --help
npx -y circuitarium-mcp@0.3.0 --version
npx -y circuitarium-mcp@0.3.0 doctor
```

If the bare `npx -y circuitarium-mcp@0.3.0` command appears to wait, the server
is working as designed: it is waiting for an MCP host on stdin. Press Ctrl+C
and let the host launch the command itself.

[Watch the terminal demo](https://github.com/Craftiee/circuitarium-mcp/blob/v0.3.0/docs/assets/circuitarium-terminal-demo.gif)
to see the published CLI inspect a synthetic fixture, build its BOM, and
export its netlist.

## What you can do

| Area | Current capabilities |
|---|---|
| General electronics | Discover available backends, validate portable experiment descriptions, and plan what evidence is needed to verify circuit claims |
| CRUMBLE / CRUMB | Discover, inspect, validate, and compare Unity-era `.cru` saves; build BOMs and netlists; trace conductive nets; query supported IC pinouts; and run static electrical checks |
| Logisim-evolution | Discover and inspect `.circ` projects, export a deliberately partial neutral netlist, and optionally run component statistics, truth tables, and test vectors |
| Cross-model work | Preserve workspace-relative project references and raw-byte SHA-256 digests so another model can confirm it is reading the same artifact |

**CRUMBLE**—Circuit Representation & Universal Model Bridge for Laboratory
Electronics—is the unofficial CRUMB-specific integration inside Circuitarium.
The simulator-neutral tools keep CRUMB-specific assumptions out of future
adapters.

The current surface breaks down into three neutral `electronics_*` tools,
thirteen `crumb_*` tools, and six `logisim_*` tools. All tool results use the
`electronics.mcp/0.2` result contract, independent of the package version.

## Compatibility and honest limits

| Target | Status | Boundary |
|---|---|---|
| CRUMB 1.3.5, Unity-era `.cru` format | Experimental support | Static, version-pinned file analysis under `crumb.unity/1.3.5` |
| Godot-era CRUMB 2.x | Not supported | Requires a separate evidence profile and controlled-save corpus |
| Live CRUMB control or simulation | Not implemented | No run, pause, step, signal-read, or GUI bridge |
| Arbitrary CRUMB editing | Not implemented | The only public write tool creates one of five fixed synthetic fixtures |
| Logisim-evolution 4.1.0 static analysis | Experimental support | Clean-room `.circ` parsing; neutral netlists remain explicitly partial |
| Logisim-evolution 4.1.0 execution | Optional | Bounded, one-shot JAR subprocesses; no live GUI session |

CRUMB electrical rule checks operate on inferred net connectivity and saved
component values. They can find supply shorts, an LED placed directly across
both rails of one recognized supply, a directly connected resistor whose
saved values imply excessive dissipation, and selected floating terminals or
IC power pins. They do **not** trace series paths, prove polarity, calculate
general circuit behavior, or certify a physical build.

> [!WARNING]
> Circuitarium is experimental educational software, not a safety
> certification tool. Do not rely on its output alone for mains voltage,
> battery charging, medical, automotive, life-safety, high-energy, or
> regulatory work. Use authoritative component documentation, appropriate
> measurements, and qualified engineering review wherever consequences
> matter.

File parsing happens locally, but the MCP host may send returned data to a
cloud model. Embedded firmware source is omitted by default, and binary EEPROM
contents are never returned, but you should still use a narrow workspace with
no secrets. Read the [security policy](SECURITY.md) for the full trust model.

## Optional Logisim runtime

The three static Logisim tools work without Java. To enable component
statistics, truth tables, and test vectors:

1. Install Java 21 or newer.
2. Download the official
   [`logisim-evolution-4.1.0-all.jar`](https://github.com/logisim-evolution/logisim-evolution/releases/tag/v4.1.0).
3. Add the JAR path to the MCP host configuration.

```text
CIRCUITARIUM_LOGISIM_JAR=/absolute/path/to/logisim-evolution-4.1.0-all.jar
CIRCUITARIUM_JAVA=java
```

`CIRCUITARIUM_JAVA` is optional when `java` already resolves to Java 21 or
newer. On a headless Linux machine, test-vector execution also needs a working
X11 display; Xvfb is sufficient.

Use only a trusted JAR. Circuitarium verifies that it self-reports version
4.1.0, but that response does not authenticate the file or its publisher.
Runtime tools may update Logisim's per-user Java preferences and are not an
operating-system sandbox.

The repository includes an independently authored
[full-adder project and vector](examples/logisim/README.md) for a first
runtime test. Circuitarium does not bundle or download Logisim-evolution.
See the [Logisim adapter guide](docs/logisim.md) for setup, Linux notes,
evidence levels, and subprocess safeguards.

## Typical workflows

### Review a CRUMB save

1. Call `electronics_capabilities`.
2. Call `crumb_list_projects` if the path is not known. Projects include a
   digest when requested and within the documented file and aggregate bounds;
   otherwise the result explains why it was omitted.
3. Call `crumb_analyze_design` with `view: "summary"`.
4. Use `crumb_export_netlist`, `crumb_trace_net`, `crumb_check_design`, or
   `crumb_bom` only as the question requires.

Static findings remain file-format inference. Circuitarium does not observe
whether CRUMB is running or how the circuit behaves.

### Verify a Logisim project

1. Call `logisim_list_projects`, then `logisim_analyze_design`.
2. Treat `logisim_export_netlist` as partial static evidence and review its
   conversion-loss markers.
3. If the optional runtime is available, select an exact circuit and call
   `logisim_truth_table` or `logisim_run_test_vector`.
4. Use `electronics_plan_verification` when a claim needs several kinds of
   evidence or an explicit list of remaining gaps.

### Hand work to another model

Keep `projectRef`, `projectDigest`, `backendId`, `adapterVersion`, and
`compatibilityProfile` with the handoff. The receiving model should pass the
recorded digest as `expectedProjectDigest` on its first read. If the bytes have
changed, Circuitarium returns `PROJECT_STATE_CONFLICT` instead of silently
reusing stale conclusions.

See the [cross-model handoff example](examples/cross-model/h