# logisim-mcp

MCP-сервер, через который Claude (или другой ИИ-ассистент) **чертит, моделирует и проверяет** схемы
[Logisim-evolution 5](https://github.com/logisim-evolution/logisim-evolution), не открывая окно программы.

Описываешь словами («полный сумматор», «F = A·¬B ∨ BC в базисе И-НЕ», «счётчик на JK-триггерах»),
ассистент собирает настоящий `.circ`: сам расставляет элементы, разводит провода и показывает картинку.
Готовую схему сам Logisim проверяет на правильность соединений и симуляцией на поведение.

## Что умеет

| Инструмент | Что делает |
|---|---|
| `logisim_build` | Чертит схему по списку элементов и соединений: автоматическая раскладка (сигнал идёт слева направо), трассировка проводов, шины входов «как в учебнике», туннели для тактов и сбросов, подписи по-русски |
| `logisim_build_logic` | Синтезирует схему по формулам или таблице истинности: МДНФ/МКНФ (Квайн — Мак-Класки), СДНФ/СКНФ, базисы И-ИЛИ-НЕ, И-НЕ, ИЛИ-НЕ, ограничение числа входов элементов; считает элементы и цену по Квайну; входы и их инверсии рисуются вертикальными шинами |
| `logisim_check` | Ищет ошибки монтажа: неподключённые входы, «висящие» цепи, два выхода на одном проводе, провод сквозь вывод, разную разрядность, одинокие туннели; прогоняет симуляцию и ловит конфликты (E), неопределённость (x), генерацию |
| `logisim_verify` | Сверяет схему с ожидаемым: формулами, таблицей истинности, набором строк или тактовой последовательностью |
| `logisim_truth_table` | Строит таблицу истинности и выводит минимальные ДНФ/КНФ по готовой схеме |
| `logisim_simulate` | Пошаговая симуляция с тактами: трасса значений выходов, светодиодов и пробников |
| `logisim_inspect` | Читает любой `.circ`: элементы, выводы, цепи (как их видит сам Logisim) |
| `logisim_render` | Картинка схемы (цвет проводов показывает значения) |
| `logisim_components` | Справочник типов элементов, их выводов и атрибутов |

Logisim запускается один раз и остаётся в памяти, поэтому вызовы занимают десятки миллисекунд.

## Примеры

Все схемы ниже собраны сервером автоматически, сохранены в [`examples/`](examples) и проверены Logisim
(пересоздать: `python scripts/make_examples.py`).

| **Дешифратор 2→4** (`Y0 = EN·¬A1·¬A0 …`) | **Мажоритарный элемент в базисе ИЛИ-НЕ** |
|---|---|
| ![](examples/decoder_2to4.png) | ![](examples/majority_nor.png) |
| **Мультиплексор 4→1** | **F = A·¬B ∨ B·C ∨ ¬A·¬C в базисе И-НЕ (2 входа)** |
| ![](examples/mux_4to1.png) | ![](examples/nand_basis.png) |

Дешифратор 7-сегментного индикатора по таблице истинности (МДНФ с безразличными наборами) и счётчик на
JK-триггерах с тактом через туннели: [`seven_segment.png`](examples/seven_segment.png),
[`jk_counter.png`](examples/jk_counter.png).

## Установка

Нужны: **Python 3.10+**, **Java 21+** ([Temurin JDK 21](https://adoptium.net/temurin/releases/?version=21)),
[Claude Code](https://claude.com/claude-code). Сам Logisim ставить не обязательно: если его нет,
установщик скачает `logisim-evolution-5.0.0-all.jar` (~55 МБ).

```bash
git clone https://github.com/n0n3o/logisim-mcp.git
cd logisim-mcp
python install.py
```

Без git: [скачай zip](https://github.com/n0n3o/logisim-mcp/archive/refs/heads/main.zip), распакуй и запусти
`python install.py` в распакованной папке.

Установщик проверит Java, найдёт или скачает Logisim и зарегистрирует сервер в Claude Code
(`claude mcp add logisim -s user ...`). После этого перезапусти Claude Code и набери `/mcp`:
сервер `logisim` должен быть в статусе connected. Если Claude Code уже был открыт со старой версией,
достаточно в `/mcp` выбрать `logisim` → Reconnect.

Другие клиенты (Claude Desktop, Cursor и т. п.): `python install.py --no-register` выведет готовый JSON для конфига.

Проверить установку в любой момент: `python run_server.py doctor`.

## Примеры запросов

- «Начерти полный сумматор в `D:\labs\fa.circ` и проверь его таблицей истинности»
- «Построй F = ¬A·B ∨ A·¬C ∨ B·C в базисе ИЛИ-НЕ на двухвходовых элементах, сохрани в `lab3.circ`»
- «Вот таблица истинности, построй МКНФ и схему по ней: …»
- «Проверь мою схему `lab2.circ`: почему на выходе F красный провод?»
- «Сделай 4-битный счётчик на JK-триггерах с тактовым генератором и проверь 16 тактов»
- «Получи формулу по схеме `task.circ` и минимизируй её»

## Полезно знать про Logisim

- Подписи выводов, светодиодов и туннелей должны быть **латиницей** (иначе Logisim 5 их переименует),
  а русский текст пишется в `caption` (надпись рядом с элементом) или в `title`.
- Провод, упёршийся концом в середину другого провода, и вывод, лежащий на проводе, **соединяются**
  (Logisim разрезает провод при загрузке). Простое пересечение двух проводов без концов в этой точке не соединяет.
  `logisim_check` предупреждает о проводах, идущих насквозь через выводы.
- Схемы, собранные `logisim_build`, после записи загружаются обратно в Logisim, и каждое соединение
  сверяется с заказанным, так что случайных замыканий не бывает.
- Существующий `.circ` не перезаписывается без явного согласия (`overwrite`), так что нарисованную руками
  схему случайно не потерять. Файлы, подключающие сторонние Java-библиотеки, сервер не открывает.
- Очень плотные схемы (сотня элементов и больше) разводятся дольше, до полуминуты; если для какой-то цепи
  не нашлось места, она соединяется подписанными туннелями, и сервер об этом сообщает.

## Настройки (переменные окружения)

| Переменная | Значение |
|---|---|
| `LOGISIM_JAR` | путь к `logisim-evolution-5.0.0-all.jar`, если он лежит в нестандартном месте |
| `LOGISIM_JAVA` | путь к `java(.exe)`, если найденная Java не подходит |
| `LOGISIM_MCP_HOME` | папка кэша (по умолчанию `%LOCALAPPDATA%\logisim-mcp` или `~/.cache/logisim-mcp`) |
| `LOGISIM_MCP_NO_DOWNLOAD` | `1` — ничего не скачивать автоматически |

## Если что-то не работает

- `Java 21+ not found`: поставь Temurin JDK 21 и перезапусти терминал (или укажи `LOGISIM_JAVA`).
- Сервер не виден в `/mcp`: выполни `python run_server.py doctor`, затем снова `python install.py`.
- Схема не разводится (очень плотная): сервер сам переведёт такие цепи на туннели и напишет об этом;
  можно задать колонки элементов (`column`) или явные координаты (`at`).

## Для разработчиков

```bash
uvx --with pytest-cov pytest tests --cov=logisim_mcp     # интеграционные тесты нужны Java и jar
python scripts/build_java.py                             # пересобрать java/classes после правки LogiWorker.java
```

Устройство: `server.py` (MCP поверх stdio) → `tools.py` → `build.py` (раскладка `layout.py`,
трассировка `router.py`, запись `circfile.py`), `logic.py` (формулы, минимизация, синтез), `lint.py`, `verify.py`.
Logisim вызывается через постоянный JVM-процесс `java/LogiWorker.java` (JSON по строкам).

## Лицензия

GPL-3.0-or-later (как и Logisim-evolution).