circuitjs-mcp

MCP-сервер, позволяющий управлять симулятором схем CircuitJS1 Фальстада из AI-агентов. Это стандартный MCP-сервер на stdio, поэтому он работает с любым MCP-совместимым клиентом: Claude Code, Codex CLI, Claude Desktop, Cursor и другими.

CircuitJS1 — это название HTML5/JavaScript-версии симулятора схем Пола Фальстада, который раньше был известен как Java-апплет «Circuit Simulator Applet», а сейчас работает в браузере на falstad.com/circuit. После прекращения поддержки Java-апплетов в браузерах Айан Шарп портировал его на JavaScript с помощью GWT; движок симуляции и текстовый формат схем общие с версией-апплетом (файлы схем времён апплета читаются как есть). JavaScript-интерфейс, который использует этот сервер, появился уже в CircuitJS1 — в версии-апплете его нет.

Сервер запускает скомпилированное веб-приложение CircuitJS1 (включено в webapp/, работает офлайн) в headless-режиме Chromium (Playwright) и предоставляет его JavaScript-интерфейс в виде MCP-инструментов. Состояние симулятора сохраняется между вызовами инструментов (можно интерактивно: загрузить схему → запустить → измерить → переписать схему).

Установка

Требования: Node.js 18 или новее.

cd circuitjs-mcp
npm install          # postinstall で Playwright の Chromium も入ります
npm test             # スモークテスト（RC回路の過渡応答が理論値と一致するか等を検証）

Если playwright install chromium по каким-то причинам невозможен, можно использовать уже установленный Chrome/Chromium:

export CIRCUITJS_CHROMIUM="/usr/bin/google-chrome"   # 例

Related MCP server: circuit-sim-mcp

Регистрация в MCP-клиенте

Команда запуска одинакова для всех клиентов: node /абсолютный/путь/circuitjs-mcp/server.mjs

С переменной окружения CIRCUITJS_HEADFUL=1 окно браузера будет видимым, и человек сможет напрямую управлять тем же симулятором, что и агент (режим совместной работы). Во всех примерах ниже эта переменная указана; если она не нужна, уберите её.

Claude Code:

claude mcp add circuitjs -e CIRCUITJS_HEADFUL=1 -- node /絶対パス/circuitjs-mcp/server.mjs

Codex CLI:

codex mcp add circuitjs --env CIRCUITJS_HEADFUL=1 -- node /絶対パス/circuitjs-mcp/server.mjs

Клиенты с файлом конфигурации (claude_desktop_config.json для Claude Desktop, mcp.json для Cursor и т. п.):

{
  "mcpServers": {
    "circuitjs": {
      "command": "node",
      "args": ["/絶対パス/circuitjs-mcp/server.mjs"],
      "env": { "CIRCUITJS_HEADFUL": "1" }
    }
  }
}

Инструмент screenshot возвращает PNG как изображение MCP-контента. В клиентах, не поддерживающих отображение изображений, используйте аргумент save_path для сохранения в файл.

Список инструментов

Примеры использования (образцы инструкций агенту)

• «Собери RC-фильтр нижних частот на 1 кОм и 1 мкФ, подай меандр 1 кГц и сними форму выходного сигнала за 5 мс».

• «Загрузи эту схему (вставка текста) и выведи список потребляемой мощности каждого резистора».

• «Покажи скриншот схемы».

В местах, где нужно проводить измерения, размещайте узлы с метками (тип элемента 207, пример: 207 336 128 400 128 4 out) — тогда напряжение можно читать пробой {"node":"out"} или через nodes в circuit_state. Токи и напряжения отдельных элементов задаются через index, который возвращают circuit_load / circuit_state.

Прямое управление из скриптов

Если нужно вызывать инструменты из скрипта, минуя MCP-клиент, используйте drive.mjs. Он запускает сервер как дочерний процесс, последовательно выполняет JSON-файлы из каталога команд (cmd-1.json, cmd-2.json, ...) и записывает результаты в res-N.json:

node drive.mjs /tmp/cjs-commands
# 別プロセスから: echo '{"tool":"circuit_state","args":{}}' > /tmp/cjs-commands/cmd-1.json

Файлы следует сначала записывать под временным именем, а затем переименовывать (чтобы избежать чтения наполовину записанного файла).

Переменные окружения

Ограничения

• Скорость симуляции в run_transient зависит от настройки скорости симуляции в строке $ схемы и от CPU. Если реальное время слишком велико, выполнение прерывается по wallTimeoutMs и возвращаются частичные данные (это можно определить по полю reason).

• «Редактирование» схемы в основном сводится к переписыванию текста Falstad и повторной загрузке через circuit_load (при импорте время сбрасывается).

• Только переходные процессы (в самом CircuitJS1 нет, например, AC-анализа по малому сигналу). Частотную характеристику можно получить, перебирая частоты и повторяя run_transient.

Лицензия

Весь репозиторий распространяется под лицензией GPL-2.0-or-later (COPYING.txt).

• CircuitJS1 — это ПО Пола Фальстада / Айана Шарпа под лицензией GPLv2+. webapp/ — его скомпилированная сборка (без изменений); соответствующий исходный код доступен в pfalstad/circuitjs1 (оригинал) и в ветке pages репозитория code4fukui/circuitjs1 (источник этой сборки).

• Код сервера (server.mjs, drive.mjs, test-client.mjs) © 2026 Suzu (涼鈴), GPL-2.0-or-later.