Metadata-Version: 2.4
Name: multisim-mcp
Version: 0.1.0a2
Summary: Unofficial MCP server for NI Multisim Automation API
Author: Multisim MCP contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/yxy050208/multisim-mcp
Project-URL: Repository, https://github.com/yxy050208/multisim-mcp
Project-URL: Issues, https://github.com/yxy050208/multisim-mcp/issues
Project-URL: Security, https://github.com/yxy050208/multisim-mcp/security/advisories/new
Keywords: multisim,mcp,circuit,simulation,ai-agent,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Win32 (MS Windows)
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: pywin32>=306; sys_platform == "win32"
Dynamic: license-file

# Multisim MCP

<!-- mcp-name: io.github.yxy050208/multisim-mcp -->

Unofficial Windows MCP server for creating NI Multisim schematics, running
experiments, exporting data, and generating reproducible reports.

非官方 Multisim 自动化 MCP：从受限 SPICE 网表生成可编辑电路图，调用本机
Multisim 执行实验，并导出 `.ms14`、原理图、raw、CSV、SVG 和 Markdown 报告。

> Alpha software. This project is not affiliated with NI. Multisim must be
> installed and licensed locally. The current COM worker requires 32-bit Python.

Linux and Docker support MCP initialization, tool discovery, and
`runtime_status` diagnostics only. They do not run Multisim. On an unsupported
platform the server starts in `introspection-only` mode, while every COM-backed
operation fails closed with a Windows compatibility message. The repository's
minimal non-root Docker image exists for registry validation and contains no NI
software, samples, licenses, or extracted templates.

## Current capability

Stable and verified on Multisim 14.3:

- MCP stdio lifecycle and 32-bit runtime diagnostics.
- Open/save circuits and enumerate components, inputs, and outputs.
- DC operating point, AC sweep, single-frequency AC, and transient analysis.
- Input waveform injection and RLC value read/write.
- SPICE netlist execution with safe `op`, `dc`, `ac`, and `tran` commands.
- Netlist, BOM, schematic image, raw data, CSV, SVG, and Markdown export.
- High-level `run_circuit_experiment` workflow.

Experimental:

- Editable schematic generation supports R/L/C, scalar and waveform voltage/current
  sources, B/E/F/G/H controlled sources, T/O/U distributed lines, coupled
  inductors, modeled diodes,
  NPN/PNP BJT, NMOS/PMOS, JFET/MESFET, voltage switches, five-terminal op-amps,
  and generic two-to-sixteen-terminal X subcircuits. Extended families currently
  use verified carrier symbols pending dedicated artwork.
  Native NOT/AND/OR/NAND/NOR/XOR/XNOR and JK flip-flop symbols are available as
  a preview; their open/export and authoritative timing-data paths are verified.
  Native XSC oscilloscope and configurable XFG function-generator state are
  generated alongside authoritative CSV/SVG experiment data.
  Multisim's exported native netlist is checked after opening so silently
  omitted parts fail the run.
- Generated schematic probes are not enabled by default. Experiment data is
  obtained authoritatively from the same netlist through Multisim's engine.

## Install

Requirements:

- Windows and a licensed Multisim 14+ installation.
- 32-bit Python 3.10+.
- Node.js 18+ only for `.ms14` XML conversion.

Install the Python package once; the server launcher never installs packages or
writes setup logs to MCP stdout:

```powershell
cd mcp_server
.\setup.ps1 -Python C:\path\to\python32\python.exe
npm install --global electronics-workbench-decoder@0.2.0
```

The public wheel is intentionally code-only: it contains the provenance
manifest but no XML extracted from NI samples. Before generating schematics,
build a local component pack from your own licensed installation as described
below and set `MULTISIM_MCP_TEMPLATE_DIR`. Other Automation API tools can still
be installed without that pack.

Start the server:

```powershell
.\run_server.ps1
```

MCP client configuration:

```json
{
  "mcpServers": {
    "multisim": {
      "command": "C:\\path\\to\\python32\\python.exe",
      "args": ["-m", "multisim_mcp.server"]
    }
  }
}
```

Call `runtime_status` first when diagnosing installation problems.

### User-local component packs

To keep licensed/reverse-engineered component assets separate from the open
engine, a contributor can derive a local pack from the NI samples installed on
their own machine:

```powershell
$env:PYTHONPATH = (Resolve-Path .\mcp_server).Path
.\tools\python32\python.exe .\tools\bootstrap_local_component_pack.py `
  --output C:\MultisimMcp\component-pack
$env:MULTISIM_MCP_TEMPLATE_DIR = 'C:\MultisimMcp\component-pack'
```

The configured pack is the public release's schematic-template source. A local
development checkout may contain ignored fallback templates, but public wheels
do not. The generated manifest records relative sample provenance. Local
reverse-engineering authorization does not itself grant permission to publish
the resulting XML files.

## Recommended agent workflow

The high-level tool accepts a SPICE netlist and a safe experiment command:

```json
{
  "netlist": "VIN vin 0 DC 10\nR1 vin vout 1k\nR2 vout 0 1k\n.end\n",
  "commands": "dc VIN 0 10 0.1",
  "output_dir": "C:\\experiments\\divider",
  "title": "Resistor divider",
  "overwrite": false
}
```

`run_circuit_experiment` will:

1. Validate the supported netlist and analysis command.
2. Generate and encode an editable `circuit.ms14`.
3. Open the design in Multisim and export `schematic.png`.
4. Run the requested analysis through Multisim's engine.
5. Export `result.raw`, `data.csv`, `plot.svg`, logs, and `report.md`.

Use `create_schematic_from_netlist` when only an editable schematic is needed,
or `run_spice_netlist` for netlist-only simulation.

Virtual instruments use explicit pseudo-device records in the same netlist:

```spice
XFG1 out 0 inv FGEN WAVE=SINE FREQ=1k AMPLITUDE=2 OFFSET=0.5
XSC1 out inv 0 0 out 0 OSCILLOSCOPE
```

The XSC terminal order is A, B, C, D, EXT+, EXT-. XFG supports `WAVE` (SINE,
SQUARE, or TRIANGLE), `FREQ`, `AMPLITUDE`, `OFFSET`, `DUTY`, and `RISE`.

## Safety model

- Safe analysis commands are allowlisted: `op`, `dc`, `ac`, and `tran`.
- `do_command_line` is disabled by default. It requires the server-side
  `MULTISIM_MCP_ENABLE_UNSAFE_COMMANDS=1` opt-in.
- Runtime npm downloads are disabled. On Windows the npx fallback remains
  disabled even when opted in because `.cmd` shims are not safe for
  caller-controlled paths. Install the pinned codec globally, or set
  `MULTISIM_MCP_EWD` and `MULTISIM_MCP_EWE` to its `dist/ewd.js` and
  `dist/ewe.js` entry points; the server invokes them through `node.exe`.
- Existing experiment artifacts are not overwritten unless `overwrite=true`.
- The server is intended for trusted local stdio clients, not public network
  exposure. See `SECURITY.md` in the repository root.

## Test

COM-free tests:

```powershell
$env:PYTHONPATH = (Resolve-Path .\mcp_server).Path
C:\path\to\python32\python.exe -m unittest discover -s mcp_server\tests -p 'test_*.py' -v
```

Real Multisim E2E:

```powershell
$env:MULTISIM_MCP_E2E_SAMPLE='C:\path\to\fixture.ms14'
tools\python32\python.exe mcp_server\tests\e2e_mcp_test.py
```

The E2E test requires a local fixture with RLC components and at least one
simulation output; proprietary NI sample designs are not distributed.

## License

Project code is MIT licensed. NI Multisim, its formats, trademarks, and locally
installed samples remain subject to their respective owners' terms.
