circuitjs-mcp

Falstad CircuitJS1 回로 시레이터를 AI 에이전트에서 조작할 수 있게 하는 MCP 서버입니다. 표준 stdio MCP 서버이므로 Claude Code, Codex CLI, Claude Desktop, Cursor 등 MCP 지원 클라이언트라면 어디서든 사용할 수 있습니다.

CircuitJS1이란 Paul Falstad 씨의 회로 시뮬레이터——예전에는 Java 애플릿 버전 "Circuit Simulator Applet" 으로 친숙했고, 현재는 falstad.com/circuit 에서 브라우저에서 동작하는 것——의 HTML5/JavaScript 버전 이름입니다. 브라우저의 Java 애플릿 지원 종료에 따라 Iain Sharp 씨가 GWT로 JavaScript에 포팅했으며, 시뮬레이션 엔진도 회로 텍스트 형식도 애플릿 버전과 공통입니다(애플릿 시대의 회로 파일을 그대로 읽을 수 있습니다). 본 서버가 이용하는 JavaScript 인터페이스는 CircuitJS1이 된 이후 추가된 기능으로, 애플릿 버전에는 없습니다.

컴파일된 CircuitJS1 웹앱(webapp/에 포함, 오프라인 동작)을 헤드리스 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

환경 변수 CIRCUIJS_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의 claude_desktop_config.json, Cursor의 mcp.json 등):

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

screenshot 도구는 MCP의 이미지 콘텐츠로 PNG를 반환합니다. 이미지 표시를 지원하지 않는 클라이언트에서는 save_path 인수로 파일에 저장하는 방식으로 사용해 주세요.

도구 목록

사용 예(에이전트에 대한 지시 예시)

• "1kΩ와 1µF의 RC 로우패스를 만들어 1kHz 구형파를 넣었을 때의 출력 파형을 5ms분 가져와"

• "이 회로(텍스트 붙여넣기)를 읽어 들여 각 저항의 소비 전력을 목록으로 만들어 줘"

• "회로 스크린샷을 보여 줘"

측정하고 싶은 곳에는 라벨이 붙은 노드(요소 타입 207, 예: 207 336 128 400 128 4 out)를 두면 {"node":"out"} 프로브나 circuit_state의 nodes로 전압을 읽을 수 있습니다. 요소 단위의 전류·전압은 circuit_load / circuit_state가 반환하는 index로 지정합니다.

스크립트에서 직접 조작

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

파일은 임시 이름으로 쓴 다음 rename으로 배치할 것(쓰기 도중 읽기를 피하기 위해).

환경 변수

제한 사항

• run_transient의 시뮬레이션 속도는 회로의 $ 행의 시뮬레이션 속도 설정과 CPU에 의존합니다. 실제 시간이 너무 오래 걸리면 wallTimeoutMs로 중단되고, 부분 데이터가 반환됩니다(reason 필드로 판별 가능).

• 회로의 "편집"은 Falstad 텍스트를 다시 써서 circuit_load를 다시 하는 것이 기본입니다(가져오기 시 시각은 리셋됩니다).

• 과도 해석만(CircuitJS1 자체가 AC 소신호 해석 등을 가지지 않기 때문). 주파수 특성은 주파수를 바꿔 가며 run_transient를 반복하면 얻을 수 있습니다.

라이선스

본 리포지토리 전체를 GPL-2.0-or-later로 제공합니다(COPYING.txt).

• CircuitJS1은 Paul Falstad / Iain Sharp의 GPLv2+ 소프트웨어입니다. webapp/는 그 컴파일된 빌드(무수정)이며, 대응하는 소스 코드는 pfalstad/circuitjs1(원작) 및 code4fukui/circuitjs1의 pages 브랜치(본 빌드의 취득원)에서 입수할 수 있습니다.

• 서버 코드(server.mjs, drive.mjs, test-client.mjs) © 2026 Suzu(涼鈴), GPL-2.0-or-later.