{
  "markdown": "# Circuitarium MCP\n\nLocal electronics tools for MCP-capable assistants, with support for CRUMB\nsave files and Logisim-evolution projects.\n\n[![CI](https://github.com/Craftiee/circuitarium-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Craftiee/circuitarium-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/circuitarium-mcp.svg)](https://www.npmjs.com/package/circuitarium-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.Craftiee%2Fcircuitarium-5c4ee5.svg)](https://registry.modelcontextprotocol.io/?q=io.github.Craftiee%2Fcircuitarium)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\nCircuitarium lets an MCP host inspect circuit files without pretending that\nstatic analysis is a running simulator. It can trace CRUMB nets, build BOMs,\nrun electrical rule checks, analyze Logisim projects, and optionally ask\nLogisim-evolution to produce truth tables or run test vectors.\n\nRelease `0.3.1` includes 22 tools, nine read-only Resources, and four workflow\nPrompts. The server is model-neutral: Codex, Claude Code/Desktop, VS Code,\nLM Studio, Jan, or another local MCP host supplies the model and launches\nCircuitarium over stdio. Circuitarium itself needs no OpenAI, Anthropic, or\nlocal-model API key.\n\n## Quick start\n\nYou need:\n\n- Node.js 22 or newer;\n- an MCP client that can launch a local stdio server; and\n- a dedicated folder containing only the circuit files you want the client to\n  access.\n\nWindows, macOS, and Linux are covered by CI. CRUMB analysis and the static\nLogisim tools need neither simulator nor Java.\n\nTo install and start the local stdio server from a terminal:\n\n```bash\nnpx -y circuitarium-mcp@0.3.1\n```\n\nIn an interactive terminal this prints a short status panel. In normal use,\nyour MCP client runs the same command and keeps the server connected over\nstdio.\n\n### 1. Add Circuitarium to your MCP client\n\nMost clients ask for the same command, arguments, and environment variable:\n\n```text\nCommand: npx\nArguments: -y circuitarium-mcp@0.3.1\nEnvironment:\n  CIRCUITARIUM_MCP_ROOT=/absolute/path/to/circuit-workspace\n```\n\nThe first launch can take longer while npm downloads the package. Later starts\nnormally use npm's cache.\n\nReplace the path with the smallest folder that should contain the `.cru`,\n`.circ`, `.vec`, and `.txt` files available to the model. Do not point it at\nyour home directory or a drive root.\n\nCopyable configurations are available for:\n\n- [Codex](examples/client-configs/codex.toml)\n- [Claude Code](examples/client-configs/claude-code.md)\n- [VS Code](examples/client-configs/vscode-mcp.json)\n- [LM Studio](examples/client-configs/lm-studio-mcp.json)\n- [Jan](examples/client-configs/jan.md)\n\nSee the [client setup guide](docs/client-setup.md) for platform-specific\nexamples and local-model guidance. The\n[starter workspace recipe](examples/starter-workspace/README.md) copies one\nsynthetic CRUMB fixture plus the full-adder Logisim project into an isolated\nfolder, so a first test does not require access to the rest of a source\ncheckout. Restart or reload the client after adding the server.\n\nClaude Desktop users can instead download\n[`circuitarium-mcp-0.3.1.mcpb`](https://github.com/Craftiee/circuitarium-mcp/releases/download/v0.3.1/circuitarium-mcp-0.3.1.mcpb)\ndirectly and open it as a local bundle. The installer asks for a circuit\nworkspace and offers optional Logisim JAR and Java settings. The\n[release page](https://github.com/Craftiee/circuitarium-mcp/releases/tag/v0.3.1)\nalso includes checksums and the matching npm tarball.\n\n### 2. Try a circuit with no simulator installed\n\nPaste this into the connected client:\n\n> Use Circuitarium. Call `electronics_capabilities`. Create the built-in\n> `breadboard-led` fixture as `demo/first-led.cru` without overwriting\n> anything, analyze it, and run `crumb_check_design`. Explain which findings\n> are static inferences rather than simulation results.\n\nYour client may ask you to approve creation of the synthetic file. The tool\nrefuses to overwrite an existing path; on a repeat run, analyze the existing\nfile or choose a new name.\n\nA healthy connection creates a small synthetic file, recognizes its\nbreadboard and LED, and reports two floating-terminal warnings. The fixture is\nindependently authored and safe to redistribute; it is not a CRUMB asset.\n\n### 3. Check the launcher from a terminal\n\nThese commands verify the published launcher without opening a server session:\n\n```text\nnpx -y circuitarium-mcp@0.3.1 --help\nnpx -y circuitarium-mcp@0.3.1 --version\nnpx -y circuitarium-mcp@0.3.1 doctor --smoke\n```\n\nIf the bare `npx -y circuitarium-mcp@0.3.1` command appears to wait, the server\nis working as designed: it is waiting for an MCP host on stdin. Press Ctrl+C\nand let the host launch the command itself.\n\n[Watch the terminal demo](https://github.com/Craftiee/circuitarium-mcp/blob/v0.3.1/docs/assets/circuitarium-terminal-demo.gif)\nto see the source-checkout command runner inspect a synthetic fixture, build\nits BOM, and export its netlist. The public package exposes the MCP server,\nhelp, version, and doctor commands shown above.\n\n[Watch the MCP Inspector demo](https://github.com/Craftiee/circuitarium-mcp/blob/v0.3.1/docs/assets/circuitarium-inspector-demo.gif)\nto see the server running in an independent MCP client, or read the\n[reproducible 22-tool host verification](https://github.com/Craftiee/circuitarium-mcp/blob/v0.3.1/docs/host-demo.md)\nand its sanitized evidence report.\n\n## What you can do\n\n| Area | Current capabilities |\n|---|---|\n| General electronics | Discover available backends, validate portable experiment descriptions, and plan what evidence is needed to verify circuit claims |\n| 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 |\n| Logisim-evolution | Discover and inspect `.circ` projects, export a deliberately partial neutral netlist, and optionally run component statistics, truth tables, and test vectors |\n| 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 |\n\n**CRUMBLE**—Circuit Representation & Universal Model Bridge for Laboratory\nElectronics—is the unofficial CRUMB-specific integration inside Circuitarium.\nThe simulator-neutral tools keep CRUMB-specific assumptions out of future\nadapters.\n\nThe current surface breaks down into three neutral `electronics_*` tools,\nthirteen `crumb_*` tools, and six `logisim_*` tools. All tool results use the\n`electronics.mcp/0.2` result contract, independent of the package version.\n\n### Static analysis versus runtime execution\n\n| Operation | Simulator or Java required? | What it establishes |\n|---|---|---|\n| All `crumb_*` tools | No | Facts inferred from a saved Unity-era `.cru` file; never live CRUMB behavior |\n| `logisim_list_projects`, `logisim_analyze_design`, `logisim_export_netlist` | No | Saved `.circ` structure and an explicitly partial neutral representation |\n| `logisim_component_stats` | Java 21 and a user-supplied Logisim 4.1.0 all-JAR | The selected project and circuit loaded in one bounded subprocess |\n| `logisim_truth_table`, `logisim_run_test_vector` | Java 21 and a user-supplied Logisim 4.1.0 all-JAR | Bounded behavioral evidence for the exact project digest; not a live GUI session |\n| Resources and Prompts | No | Guidance and workflow templates only; they do not read a project or execute a simulator |\n\n## Compatibility and honest limits\n\n| Target | Status | Boundary |\n|---|---|---|\n| CRUMB 1.3.5, Unity-era `.cru` format | Experimental support | Static, version-pinned file analysis under `crumb.unity/1.3.5` |\n| Godot-era CRUMB 2.x | Not supported | Requires a separate evidence profile and controlled-save corpus |\n| Live CRUMB control or simulation | Not implemented | No run, pause, step, signal-read, or GUI bridge |\n| Arbitrary CRUMB editing | Not implemented | The only public write tool creates one of five fixed synthetic fixtures |\n| Logisim-evolution 4.1.0 static analysis | Experimental support | Clean-room `.circ` parsing; neutral netlists remain explicitly partial |\n| Logisim-evolution 4.1.0 execution | Optional | Bounded, one-shot JAR subprocesses; no live GUI session |\n\nCRUMB electrical rule checks operate on inferred net connectivity and saved\ncomponent values. They can find supply shorts, an LED placed directly across\nboth rails of one recognized supply, a directly connected resistor whose\nsaved values imply excessive dissipation, and selected floating terminals or\nIC power pins. They do **not** trace series paths, prove polarity, calculate\ngeneral circuit behavior, or certify a physical build.\n\n> [!WARNING]\n> Circuitarium is experimental educational software, not a safety\n> certification tool. Do not rely on its output alone for mains voltage,\n> battery charging, medical, automotive, life-safety, high-energy, or\n> regulatory work. Use authoritative component documentation, appropriate\n> measurements, and qualified engineering review wherever consequences\n> matter.\n\nFile parsing happens locally, but the MCP host may send returned data to a\ncloud model. Embedded firmware source is omitted by default, and binary EEPROM\ncontents are never returned, but you should still use a narrow workspace with\nno secrets. Read the [security policy](SECURITY.md) for the full trust model.\n\n## Optional Logisim runtime\n\nThe three static Logisim tools work without Java. To enable component\nstatistics, truth tables, and test vectors:\n\n1. Install Java 21 or newer.\n2. Download the official\n   [`logisim-evolution-4.1.0-all.jar`](https://github.com/logisim-evolution/logisim-evolution/releases/tag/v4.1.0).\n3. Add the JAR path to the MCP host configuration.\n\n```text\nCIRCUITARIUM_LOGISIM_JAR=/absolute/path/to/logisim-evolution-4.1.0-all.jar\nCIRCUITARIUM_JAVA=java\n```\n\n`CIRCUITARIUM_JAVA` is optional when `java` already resolves to Java 21 or\nnewer. On a headless Linux machine, test-vector execution also needs a working\nX11 display; Xvfb is sufficient.\n\nUse only a trusted JAR. Circuitarium verifies that it self-reports version\n4.1.0, but that response does not authenticate the file or its publisher.\nRuntime tools may update Logisim's per-user Java preferences and are not an\noperating-system sandbox.\n\nThe repository includes an independently authored\n[full-adder project and vector](examples/logisim/README.md) for a first\nruntime test. Circuitarium does not bundle or download Logisim-evolution.\nSee the [Logisim adapter guide](docs/logisim.md) for setup, Linux notes,\nevidence levels, and subprocess safeguards.\n\n## Typical workflows\n\n### Review a CRUMB save\n\n1. Call `electronics_capabilities`.\n2. Call `crumb_list_projects` if the path is not known. Projects include a\n   digest when requested and within the documented file and aggregate bounds;\n   otherwise the result explains why it was omitted.\n3. Call `crumb_analyze_design` with `view: \"summary\"`.\n4. Use `crumb_export_netlist`, `crumb_trace_net`, `crumb_check_design`, or\n   `crumb_bom` only as the question requires.\n\nStatic findings remain file-format inference. Circuitarium does not observe\nwhether CRUMB is running or how the circuit behaves.\n\n### Verify a Logisim project\n\n1. Call `logisim_list_projects`, then `logisim_analyze_design`.\n2. Treat `logisim_export_netlist` as partial static evidence and review its\n   conversion-loss markers.\n3. If the optional runtime is available, select an exact circuit and call\n   `logisim_truth_table` or `logisim_run_test_vector`.\n4. Use `electronics_plan_verification` when a claim needs several kinds of\n   evidence or an explicit list of remaining gaps.\n\n### Hand work to another model\n\nKeep `projectRef`, `projectDigest`, `backendId`, `adapterVersion`, and\n`compatibilityProfile` with the handoff. The receiving model should pass the\nrecorded digest as `expectedProjectDigest` on its first read. If the bytes have\nchanged, Circuitarium returns `PROJECT_STATE_CONFLICT` instead of silently\nreusing stale conclusions.\n\nSee the [cross-model handoff example](examples/cross-model/handoff.md).\n\n## Tool reference\n\n<details>\n<summary><strong>All 22 tools</strong></summary>\n\n### Neutral electronics tools\n\n| Tool | Purpose |\n|---|---|\n| `electronics_capabilities` | Report callable backends, limitations, and recommended workflows |\n| `electronics_validate_experiment` | Validate a portable experiment description without claiming it ran |\n| `electronics_plan_verification` | Build an evidence plan for explicit circuit claims |\n\n### CRUMBLE tools\n\n| Tool | Purpose |\n|---|---|\n| `crumb_component_catalog` | Return the version-pinned CRUMB component catalog |\n| `crumb_analyze_design` | Read bounded semantic views of a `.cru` save |\n| `crumb_compare_designs` | Compare two digest-guarded saves without modifying either |\n| `crumb_inspect_design` | Return a compact format-level inventory |\n| `crumb_validate_design` | Check XML structure and known invariants |\n| `crumb_generate_fixture` | Create one fixed synthetic fixture without overwriting |\n| `crumb_list_projects` | Discover workspace `.cru` files and bounded artifact metadata |\n| `crumb_get_component` | Fetch one component and optional bounded source window |\n| `crumb_bom` | Group recognized components into a bill of materials |\n| `crumb_ic_reference` | Query the version-pinned IC package and pin registry |\n| `crumb_export_netlist` | Export static, jumper-collapsed inferred nets |\n| `crumb_trace_net` | Produce a paged conductive witness for one terminal |\n| `crumb_check_design` | Run scoped static electrical rule checks |\n\n### Logisim-evolution tools\n\n| Tool | Purpose |\n|---|---|\n| `logisim_list_projects` | Discover workspace `.circ` files |\n| `logisim_analyze_design` | Inspect static project, circuit, component, Pin, Clock, and wire structure |\n| `logisim_export_netlist` | Export an explicitly partial coordinate-based neutral netlist |\n| `logisim_component_stats` | Ask the configured JAR to load and inventory a circuit |\n| `logisim_truth_table` | Evaluate a bounded combinational truth table |\n| `logisim_run_test_vector` | Run a workspace-contained vector and return structured failures |\n\n</details>\n\nThe nine Resources provide capability metadata, compatibility profiles,\nsynthetic-example metadata, electrical-review and digital-testing guidance, a\nneutral component-profile schema, and version-pinned component catalogs. The\nfour user-invoked Prompts are:\n\n- `review-circuit-design`\n- `compare-crumb-designs`\n- `verify-logisim-design`\n- `handoff-circuit-project`\n\nResources and Prompts do not read a project or run a simulator by themselves.\nClients that do not expose those MCP features can still use all 22 tools. The\n[contract reference](docs/contract.md) documents exact resource URIs, Prompt\narguments, result envelopes, errors, output bounds, and tool schemas.\n\n## Contributing\n\nCircuitarium is still early, and small, well-evidenced improvements are useful.\nGood starting points include client setup fixes, synthetic test circuits,\nsource-cited component profiles, parser edge cases, controlled compatibility\nobservations, and scoped [roadmap](ROADMAP.md) work.\n\nBefore changing an adapter or public contract, read the\n[contribution guide](CONTRIBUTING.md),\n[architecture](docs/architecture.md), and\n[provenance policy](PROVENANCE.md). Questions and early design ideas belong in\n[Discussions](https://github.com/Craftiee/circuitarium-mcp/discussions);\nreproducible bugs, scoped feature requests, and controlled interoperability\nevidence belong in the\n[issue tracker](https://github.com/Craftiee/circuitarium-mcp/issues/new/choose).\n\n```text\ngit clone https://github.com/Craftiee/circuitarium-mcp.git\ncd circuitarium-mcp\nnpm ci\nnpm run lint\nnpm run check\n```\n\nUse `npm run test:coverage` for behavioral changes,\n`npm run package:check` for package or launcher changes, and\n`npm run logisim:e2e` for Logisim runtime changes. The Logisim E2E test\nrequires Java 21 and a separately supplied 4.1.0 all-JAR.\n\nFixtures must be small, synthetic, independently authored, and safe to\nredistribute. Do not submit private circuits, firmware, simulator binaries,\nextracted assets, or third-party circuit designs. Build a minimal synthetic\nreproduction instead. Report vulnerabilities through\n[GitHub private vulnerability reporting](SECURITY.md), not a public issue.\nAll contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Documentation\n\n| Document | Use it for |\n|---|---|\n| [Client setup](docs/client-setup.md) | Host-specific installation, subscriptions/APIs, and local models |\n| [CRUMBLE guide](docs/crumble.md) | Current CRUMB scope and evidence profiles |\n| [Logisim guide](docs/logisim.md) | JAR setup, runtime evidence, safety, and Linux notes |\n| [MCP contract](docs/contract.md) | Exact tools, Resources, Prompts, envelopes, and limits |\n| [Architecture](docs/architecture.md) | Adapter boundaries and simulator-neutral design |\n| [Provenance](PROVENANCE.md) | Evidence categories and redistribution rules |\n| [Roadmap](ROADMAP.md) | Shipped milestones and planned work |\n| [Changelog](CHANGELOG.md) | Release history |\n\n## Privacy Policy\n\nCircuitarium runs locally over stdio, has no telemetry, and does not send\ncircuit files to a maintainer-controlled service. The MCP host and model\nprovider you choose may still process tool arguments and results under their\nown terms. Read the complete [Privacy Policy](PRIVACY.md) before granting a\nhost access to a workspace.\n\n## Project status and license\n\nCircuitarium MCP is experimental community software released under the\n[Apache License 2.0](LICENSE). Version `0.3.1` is available on\n[npm](https://www.npmjs.com/package/circuitarium-mcp/v/0.3.1) and as a\n[GitHub release](https://github.com/Craftiee/circuitarium-mcp/releases/tag/v0.3.1),\nand its metadata is listed in the\n[official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.Craftiee%2Fcircuitarium).\nFor help, see [SUPPORT.md](SUPPORT.md). Research and teaching users can cite\nthe project with [CITATION.cff](CITATION.cff).\n\nCircuitarium MCP, CRUMBLE, and the Logisim-evolution adapter are independent,\nunofficial interoperability work. They are not affiliated with, endorsed by,\nor sponsored by CRUMB, Logisim-evolution, or their developers. This repository\ncontains no CRUMB or Logisim-evolution simulator code, binaries, extracted\nassets, logos, or bundled third-party circuit designs. Product names and marks\nbelong to their respective owners.\n",
  "bytes": 18594,
  "sha": "9f619fcf29687ab1d440e5ce693864bf7ff20cc5d26221b832fc14edcff1c9e1",
  "repo_slug": "craftiee/circuitarium-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_craftiee_circuitarium_fda23a5f/readme"
}