Logisim-evolution MCP Server

A local Model Context Protocol (MCP) server for working with saved Logisim-evolution .circ projects. It provides structured project inspection, guarded edits, validation, circuit analysis, test execution, format conversion, and GUI launch.

Requirements

• Node.js 22 or later
• Logisim-evolution 4.0.0 or a compatible release
• GNU coreutils cp at /usr/bin/cp on Linux, used to preserve metadata during atomic file replacement

By default, the server uses the Logisim launcher at /opt/logisim-evolution/bin/logisim-evolution and the current user's home directory as its workspace. Configure different locations with the environment variables below.

Install and build

npm install
npm run build

To install the bundled OpenCode skill, run the optional command below. It overwrites or refreshes the configured skill copy at ${XDG_CONFIG_HOME:-~/.config}/opencode/skills/logisim-evolution/SKILL.md.

npm run install:skill

Set OPENCODE_CONFIG_DIR when OpenCode uses a different configuration root, then restart OpenCode.

MCP configuration

Build the project before configuring the client. Replace the placeholder paths with locations on the machine running the server.

{
  "mcp": {
    "logisim": {
      "type": "local",
      "command": [
        "node",
        "/absolute/path/to/Logisim-Evolution-MCP-Server/dist/index.js"
      ],
      "enabled": true,
      "environment": {
        "LOGISIM_EXECUTABLE": "/absolute/path/to/logisim-evolution",
        "LOGISIM_WORKSPACE": "/absolute/path/to/logisim-workspace"
      },
      "timeout": 120000
    }
  }
}

Restart the MCP client after changing its configuration.

Environment variables

Variable	Purpose
LOGISIM_EXECUTABLE	Path to the Logisim-evolution launcher.
LOGISIM_WORKSPACE	Root directory allowed for project and test-vector file operations.
LOGISIM_VALIDATE_WRITES	Set to false to skip post-edit Logisim CLI validation. It is enabled by default.
OPENCODE_CONFIG_DIR	Optional OpenCode configuration root for the skill installer.

Capabilities

The server exposes these tool groups:

• Status and inspection: logisim_get_status, logisim_describe_component, logisim_list_projects, and logisim_inspect_project.
• Project and circuit management: logisim_create_project, logisim_copy_circuit, logisim_add_circuit, and logisim_set_main_circuit.
• Edits: logisim_add_component, logisim_update_component, logisim_remove_component, logisim_add_wire, logisim_remove_wire, and logisim_apply_batch.
• Automatic layout: logisim_layout_graph places and routes supported semantic graphs in an empty circuit and returns a geometry certificate.
• Validation and execution: logisim_validate_project, logisim_truth_table, logisim_test_vector, logisim_test_bench, logisim_convert_project, and logisim_launch_gui.

Use logisim_describe_component before supplying unfamiliar component attributes or semantic ports. logisim_apply_batch is intended for known coordinates; logisim_layout_graph is intended for a new, empty circuit.

Supported automatic-layout components

The source-verified layout catalog includes Wiring Pin, Clock, and legacy Splitter; Gates AND Gate, OR Gate, XOR Gate, NAND Gate, NOR Gate, XNOR Gate, NOT Gate, and Buffer; Arithmetic Adder; Memory D Flip-Flop, Register, and Counter; and I/O LED.

The Splitter layout is decode-only: it accepts appear="legacy", fanout 2--8, incoming width 1--64, spacing 1--9, and an explicit non-none mapping for each incoming bit. It does not support reverse-combine use or nonlegacy appearances.

Safety model

• File operations are restricted to LOGISIM_WORKSPACE; project paths must end in .circ.
• Mutations use per-project locks, write to a private temporary directory, validate the result by default, create a backup under .logisim-mcp/backups/, and atomically replace the original only after validation succeeds.
• The validation round trip checks that the circuit, component, and wire inventory survives Logisim normalization.
• Projects using external jar# or file# libraries, or filePath resources, are rejected before Logisim runs.
• GUI launches preflight the project and open a validated file descriptor to avoid a pathname replacement between validation and launch.

Development

npm run build
npm test
npm run smoke

npm test builds the TypeScript source and runs the compiled Node.js tests. npm run smoke starts the built server, checks tool registration, and queries server status and the Pin component description. It requires a usable Logisim launcher and workspace configuration.

Limitations

• Edits apply to saved project files, not unsaved state in an already-open GUI window. Reopen a project after an external edit.
• Component names, library numbers, and XML attribute names must match Logisim's format. The component catalog covers only verified geometry.
• Automatic layout supports only the components listed above and only empty circuits. It is deterministic and bounded; it selects the best feasible candidate it evaluates, not a global optimum.
• Crossing-free routing is not possible for every graph. Non-planar graphs need an explicit crossover component or another supported design.
• Removing a component does not remove its connected wires.
• Project locks are not reaped automatically. After a crash, confirm the lock owner is no longer running before removing a reported lock file.
• Logisim 4.0.0 test-vector execution can report failures while exiting with status 0. The server parses the reported passed and failed counts.
• The server can launch Logisim but cannot control an already-running editor or simulator window.

License

This project is licensed under the MIT License.