# 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

```bash
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`.

```bash
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.

```json
{
  "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

```bash
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](LICENSE).