mc9py 0.2.0__tar.gz

mc9py-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+.venv/
+__pycache__/
+sandbox/prefix-pristine/
+sandbox/prefix-work/
+sandbox/exchange/
+re/*.exe
+re/work/
+re/*.strings.txt
+re/.venv-re/
+re/ghidra-proj/
+re/ghidramcp-dl/
+re/decomp/
+re/test/
+re/*.log
+
+# never publish: proprietary binaries / decompiled code / local setup
+re/
+tools/winpy-dl/
+.mcp.json
+sandbox/
+*.exe
+*.dll
+*.packed.exe
+site/
+dist/

mc9py-0.2.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.2.0 - 2026-10-25
+- Windows backend (Win32 API via ctypes), tested by running Windows Python under Wine.
+- Automatic placement: `Netlist` -> placed and routed `Schematic` (backbone + branches, buses, label fallback), verified net-for-net.
+- `Schematic.pin_nets()`, `audit()`, label-aware connectivity (`nets()` joins equal names and all grounds).
+- One package `mc9`; `workspace` paths; `Driver` abstraction; CLI (`mc9 setup | doctor | reset | mcp`).
+- MCP tools `build_netlist` and others; documentation site; CI.
+
+## 0.1.0
+- First version: Linux/Wine sandbox, circuit editing, analyses with numeric results, cursors, native screenshots, `Schematic` builder,
+  measurements (bandwidth, Rin, Rout, THD, solver), MCP server.

mc9py-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DontforgetAntaiku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mc9py-0.2.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.5
+Name: mc9py
+Version: 0.2.0
+Summary: Python scripting layer for Micro-Cap 9: run analyses, read results, take native screenshots and build schematics from code (Linux + Wine, Windows).
+Project-URL: Homepage, https://github.com/DontforgetAntaiku/mc9py
+Project-URL: Documentation, https://DontforgetAntaiku.github.io/mc9py/
+Project-URL: Issues, https://github.com/DontforgetAntaiku/mc9py/issues
+Project-URL: Changelog, https://github.com/DontforgetAntaiku/mc9py/blob/main/CHANGELOG.md
+Author: DontforgetAntaiku
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,circuit-simulation,education,electronics,mc9,mcp,micro-cap,microcap,spice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.10
+Requires-Dist: pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.3; extra == 'mcp'
+Provides-Extra: tools
+Requires-Dist: numpy; extra == 'tools'
+Requires-Dist: scipy; extra == 'tools'
+Description-Content-Type: text/markdown
+
+<h1 align="center">mc9py</h1>
+
+<p align="center">
+  <b>Script Micro-Cap 9 from Python.</b><br>
+  Open or <i>describe</i> a circuit, run analyses, get the numbers, and take screenshots that are <b>MC9's own pictures</b>.<br>
+  Linux (sandboxed Wine) · Windows · AI-ready (MCP)
+</p>
+
+<p align="center">
+  <a href="https://github.com/DontforgetAntaiku/mc9py/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/DontforgetAntaiku/mc9py/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://DontforgetAntaiku.github.io/mc9py/"><img alt="docs" src="https://img.shields.io/badge/docs-GitHub%20Pages-blue"></a>
+  <a href="https://pypi.org/project/mc9py/"><img alt="PyPI" src="https://img.shields.io/pypi/v/mc9py"></a>
+  <img alt="Python" src="https://img.shields.io/badge/python-3.10%E2%80%933.13-blue">
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/ce_schematic_dc.png" width="48%" alt="common-emitter stage, drawn by mc9 and simulated by MC9">
+  <img src="docs/assets/ce_ac_cursors.png" width="48%" alt="MC9's own AC plot with cursors on the band edges">
+</p>
+
+---
+
+## Why
+
+Micro-Cap 9 is a fast, capable circuit simulator that many universities still teach with - but it has **no scripting interface**:
+every lab means clicking through the same dialogs, reading values off cursors and pasting screenshots. `mc9py` automates exactly
+that, **using MC9 itself**, so results and pictures are the ones your teacher expects.
+
+- 📷 **Native pictures.** Plots and schematics are screenshots of MC9 - its grid, fonts, cursor tables and voltage boxes. Nothing is re-plotted.
+- 🔢 **Real numbers.** Every value is parsed from MC9's own numeric output: operating points, AC / transient / DC tables, THD, Rin, Rout ...
+- ✏️ **Circuits from code.** Describe a circuit like a SPICE netlist and get a *placed, routed, collision-free* MC9 schematic; or place parts by hand.
+- 🛡️ **Safe by design.** On Linux MC9 runs in a bubblewrap sandbox: no network, no access to your files. Your circuits are copied in, never modified.
+- 🪟 **Windows and Linux.** Native Win32 driver on Windows, sandboxed Wine on Linux. One API.
+- 🤖 **AI-ready.** A built-in [MCP](https://modelcontextprotocol.io) server lets an assistant build, simulate and photograph circuits for you.
+
+## A 60-second tour
+
+```python
+import mc9
+from mc9 import Netlist, measure, sources
+
+n = Netlist()                                       # 1. describe a circuit
+n.V("V1", "in", "0", sources.sine(0.1, 1e3))
+n.R("R1", "in", "out", "1k")
+n.C("C1", "out", "0", "159.155n")                   #    RC low-pass, fc = 1 kHz
+c = n.build("rc")                                   #    placed + routed + written for MC9
+
+print(c.op().nodes)                                 # 2. DC operating point
+r = c.ac(10, 1e5, 401, ["db(v(out))"])              # 3. AC sweep -> numbers
+bw = measure.bandwidth(c, "db(v(out))", cursors=True)   # 4. -3 dB point, MC9's cursors placed on it
+print(f"{bw.f_high:.1f} Hz")                        #    998 Hz
+
+c.shot("rc_ac.png")                                 # 5. MC9's own plot, cursor table included
+c.dynamic_dc(25); c.shot("rc_dc.png", "schematic")  # 6. schematic with node voltages
+```
+
+Working on an existing lab file? `c = mc9.open("my_lab/amplifier.cir")` copies it into the work folder; then `c.parts()`,
+`c.set("R2", "RESISTANCE", "180k")`, `c.ac(...)`, `c.cursors(...)`, `c.shot(...)`, `c.export(...)` (writes a *new* file).
+
+## Install
+
+### Step 1 - install the Python package
+
+You need **Python 3.10 or newer** and **git**. `pip` is Python's package installer; it comes with Python. mc9py is **not on PyPI yet**
+(so `pip install mc9py` does not work yet) - install it straight from GitHub. Use a *virtual environment*, a private folder for
+Python packages that keeps your system clean:
+
+<details open><summary><b>Linux / macOS</b></summary>
+
+```bash
+python3 -m venv ~/mc9-env                       # create the environment once
+source ~/mc9-env/bin/activate                   # activate it (repeat in every new terminal)
+pip install "git+https://github.com/DontforgetAntaiku/mc9py.git"
+mc9 doctor                                      # prints what is installed and what is missing
+```
+</details>
+
+<details><summary><b>Windows (PowerShell)</b></summary>
+
+```powershell
+py -m venv $HOME\mc9-env                        # create the environment once
+& $HOME\mc9-env\Scripts\Activate.ps1            # activate it (repeat in every new terminal)
+pip install "git+https://github.com/DontforgetAntaiku/mc9py.git"
+mc9 doctor
+```
+</details>
+
+Want `mc9` available in every terminal without activating anything? Use [pipx](https://pipx.pypa.io) instead:
+`pipx install "git+https://github.com/DontforgetAntaiku/mc9py.git"`.
+For development: `git clone https://github.com/DontforgetAntaiku/mc9py && cd mc9py && pip install -e ".[dev]"`.
+Once the project is published on PyPI, `pip install mc9py` will do the same.
+
+### Step 2 - connect MC9
+
+<details open><summary><b>Linux</b> (MC9 runs in a sandbox: Wine + virtual display)</summary>
+
+```bash
+# 1. system packages: wine, bubblewrap, Xvfb, xdotool, ImageMagick  (package names for Arch / Debian / Fedora: see the docs)
+# 2. install MC9 once into a Wine prefix (the default ~/.wine is fine)
+WINEPREFIX=~/.wine wine /path/to/mc9-setup.exe
+# 3. create the sandbox snapshot (links to your home folders are removed from the copy)
+mc9 setup ~/.wine
+mc9 doctor                                      # everything should say [ok]
+```
+</details>
+
+<details><summary><b>Windows</b> (MC9 is driven natively)</summary>
+
+`mc9 doctor` finds `mc9.exe` in the usual install folders. If yours is elsewhere, tell the library once at the top of your script:
+`mc9.config.mc9_exe = r"D:\Tools\MC9\mc9.exe"`. Use 100 % display scaling and keep the keyboard and mouse free while a script runs.
+More in the [Windows page](https://dontforgetantaiku.github.io/mc9py/getting-started/install-windows/).
+</details>
+
+## What it can do
+
+| Area | Features |
+|---|---|
+| **Circuits** | open (copy) `.cir` files · list / get / set part values · raw `[Limits]` and curve editing · export to a *new* file · display toggles (voltages/currents/power) |
+| **Analyses** | operating point · AC (log sweep) · transient (steady-state windows) · DC sweep (temperature lists, several runs) · Distortion window · Dynamic DC · Dynamic AC phasors |
+| **Data** | `Result`/`Run`/`OP`: `value_at`, `cross`, `peak`, `trough`, `amplitude`, `mean`, CSV export · device tables (`IC`, `GM`, `RPI`, power ...) · SI-suffix parsing, `N/A` handling |
+| **Pictures** | plot / schematic / window screenshots · tight automatic crops · cursors placed at exact X values with MC9's own cursor table · maximized plot windows · failure screenshots with MC9's error dialog |
+| **Measurements** | `bandwidth` (-3 dB, low/high/band-pass) · `gain_at` · `rin` · `rout` (load removal) · `thd` (steady-state DFT) · `solve` (find the part value that hits a target) |
+| **Schematics** | `Schematic` builder (catalog: R C L V VB I D Q QP M OPAMP GND) · automatic label placement · `check()` / `audit()` / `pin_nets()` · auto centre & zoom · T-junction and node-name handling |
+| **Auto-placement** | SPICE-like `Netlist` → backbone + branches + rail/ground buses, label fallback to avoid crossings · verified net-for-net against your netlist · starter circuits in `mc9.library` |
+| **Platforms** | Linux: sandboxed Wine + Xvfb · Windows: Win32 API (language independent) |
+| **AI** | MCP server with 24 tools (files, analyses, cursors, screenshots, measurements, `build_netlist`, `build_schematic`) |
+| **Tooling** | `mc9 setup / doctor / reset / mcp` · 37 offline tests (run on Linux, Windows, macOS CI) · opt-in MC9 integration tests · MkDocs site · GitHub Actions CI |
+
+<p align="center">
+  <img src="docs/assets/ce_schematic_ac.png" width="49%" alt="Dynamic AC phasors">
+  <img src="docs/assets/inverting_schematic.png" width="49%" alt="inverting op-amp stage placed automatically">
+</p>
+<p align="center">
+  <img src="docs/assets/ce_transient.png" width="49%" alt="transient plot">
+  <img src="docs/assets/ce_distortion.png" width="49%" alt="MC9 distortion window">
+</p>
+
+## Automatic placement in one picture
+
+```python
+n = mc9.library.ce_amplifier().build("amp")     # a common-emitter stage from the starter library
+# or write your own:
+n = Netlist()
+n.V("V1", "src", "0", sources.sine(3.5e-3, 2224)); n.R("R1", "src", "ue", "200"); n.C("C1", "ue", "b", "3.47u")
+n.R("R2", "vcc", "b", "233.2k"); n.Q("Q1", c="col", b="b", e="0", model="BF420"); n.R("R3", "vcc", "col", "1.2k")
+n.C("C3", "col", "ua", "553n"); n.R("R4", "ua", "0", "1.2k"); n.VB("V2", "vcc", "0", "18")
+c = n.build("amp")                              # VB = 0.695 V, VC = 9.5 V, IC = 7.09 mA - as in the textbook calculation
+```
+
+How the placer works, in short: classify nodes → lay the **signal backbone** left to right → hang **branches** to ground (down) and
+rails (up) → draw **buses** → if wires would cross, that net falls back to **named labels** (MC9 joins equally named nodes) → check
+collisions with MC9's voltage boxes and re-space. Every generated drawing is verified to have exactly the nets of your netlist.
+
+## Use it from an AI assistant
+
+This is optional. It lets an AI assistant such as [Claude Code](https://claude.com/claude-code) or Claude Desktop drive MC9 through
+the library. You need the `mcp` extra, and the assistant must be able to *start the `mc9` program*:
+
+```bash
+# 1. install with the extra (inside your activated environment from Step 1)
+pip install "mc9py[mcp] @ git+https://github.com/DontforgetAntaiku/mc9py.git"
+
+# 2. find out where the mc9 program lives - you will paste this path below
+which mc9                                   # Windows PowerShell:  (Get-Command mc9).Source
+#   e.g.  /home/you/mc9-env/bin/mc9    or    C:\Users\you\mc9-env\Scripts\mc9.exe
+```
+
+**Claude Code** - run this once in an ordinary terminal (not inside Python), using the path from step 2:
+
+```bash
+claude mcp add microcap9 -- /home/you/mc9-env/bin/mc9 mcp
+claude mcp list                              # microcap9 should be listed; start `claude` and ask away
+```
+(If `mc9` is on your `PATH`, e.g. after `pipx install`, plain `claude mcp add microcap9 -- mc9 mcp` works.)
+
+**Claude Desktop and other MCP clients** - add this to the client's config file (Claude Desktop: *Settings -> Developer -> Edit Config*;
+file `~/.config/Claude/claude_desktop_config.json` on Linux, `%APPDATA%\Claude\claude_desktop_config.json` on Windows), with the path
+from step 2, then restart the client:
+
+```json
+{ "mcpServers": { "microcap9": { "command": "/home/you/mc9-env/bin/mc9", "args": ["mcp"] } } }
+```
+
+> "Build a common-emitter amplifier with a 12 V supply, find its −3 dB band and show me the AC plot with the cursors on the edges."
+
+More: [MCP guide](https://dontforgetantaiku.github.io/mc9py/guide/mcp/).
+
+## How it works
+
+```
+ your script / AI ─▶ mc9.Circuit · Schematic · Netlist · measure           (pure Python)
+                          │
+                 circuit-file editor ── numeric-output parser
+                          │
+                 ui flows (run, cursors, capture, error screenshots)
+                          │
+                  Driver ─┬─ Linux : bubblewrap + Wine + Xvfb + xdotool
+                          └─ Windows: Win32 API (ctypes)
+                          │
+                       MC9 (mc9.exe)  ⇄  files in the work folder
+```
+MC9 has no automation interface, so the library configures everything **in the circuit file**, starts MC9 on it, presses the few
+remaining buttons, reads MC9's numeric-output files and screenshots its window. Details: [architecture](https://DontforgetAntaiku.github.io/mc9py/internals/architecture/).
+
+## Status and honesty
+
+- **Linux/Wine** is the best-tested path: developed and verified against the Russian *GUAP Edition* of MC9 9.0.3.
+  Other editions/languages need a one-time [calibration](https://DontforgetAntaiku.github.io/mc9py/internals/calibration/) of the button positions.
+- **Windows** driver is language independent (keyboard accelerators + dialog classes). It is exercised by running Windows Python
+  under Wine against MC9 (same Win32 calls); **testers on real Windows are very welcome**.
+- Validated on real analyses: divider, RC filter (−3.01 dB at fc), inverting op-amp (20.00 dB), a BF420 common-emitter stage
+  (VC = 9.500 V, IC = 7.089 mA, Rin = 635 Ω, Rout = 1119 Ω, THD 8.6 % at 35 mV) - matching hand calculations.
+- A run takes ~15–30 s (MC9 has to start and simulate); sweeps/solvers take minutes.
+- Auto-placement targets teaching circuits (filters, clippers, single-stage amplifiers, op-amp stages); odd topologies fall back to labels.
+
+## Documentation
+
+Full guide, API reference, internals and FAQ: **<https://DontforgetAntaiku.github.io/mc9py/>** (sources in [`docs/`](docs/)).
+
+## Contributing
+
+Bug reports with `mc9 doctor` output, calibrations for other MC9 editions, Windows test reports, new measurements, catalog parts and
+circuits the placer handles badly are all welcome - see [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
+Please **never** commit MC9 binaries, licence keys, decompiled code or other people's circuits.
+
+## License
+
+[MIT](LICENSE) © 2026 DontforgetAntaiku.
+
+`mc9py` is an independent project. **Micro-Cap® is a trademark of Spectrum Software**; this project is not affiliated with, endorsed
+by or sponsored by Spectrum Software, and it **does not contain or distribute MC9** - you need your own licensed copy and must follow its
+license terms. The circuit template bundled with the package holds only the small shape and pin descriptions that MC9 itself writes into
+every circuit it saves. Third-party libraries: [Pillow](https://python-pillow.org) (HPND), [`mcp`](https://github.com/modelcontextprotocol/python-sdk)
+(MIT, optional), MkDocs Material (MIT, docs only).

mc9py-0.2.0/README.md

@@ -0,0 +1,235 @@
+<h1 align="center">mc9py</h1>
+
+<p align="center">
+  <b>Script Micro-Cap 9 from Python.</b><br>
+  Open or <i>describe</i> a circuit, run analyses, get the numbers, and take screenshots that are <b>MC9's own pictures</b>.<br>
+  Linux (sandboxed Wine) · Windows · AI-ready (MCP)
+</p>
+
+<p align="center">
+  <a href="https://github.com/DontforgetAntaiku/mc9py/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/DontforgetAntaiku/mc9py/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://DontforgetAntaiku.github.io/mc9py/"><img alt="docs" src="https://img.shields.io/badge/docs-GitHub%20Pages-blue"></a>
+  <a href="https://pypi.org/project/mc9py/"><img alt="PyPI" src="https://img.shields.io/pypi/v/mc9py"></a>
+  <img alt="Python" src="https://img.shields.io/badge/python-3.10%E2%80%933.13-blue">
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/ce_schematic_dc.png" width="48%" alt="common-emitter stage, drawn by mc9 and simulated by MC9">
+  <img src="docs/assets/ce_ac_cursors.png" width="48%" alt="MC9's own AC plot with cursors on the band edges">
+</p>
+
+---
+
+## Why
+
+Micro-Cap 9 is a fast, capable circuit simulator that many universities still teach with - but it has **no scripting interface**:
+every lab means clicking through the same dialogs, reading values off cursors and pasting screenshots. `mc9py` automates exactly
+that, **using MC9 itself**, so results and pictures are the ones your teacher expects.
+
+- 📷 **Native pictures.** Plots and schematics are screenshots of MC9 - its grid, fonts, cursor tables and voltage boxes. Nothing is re-plotted.
+- 🔢 **Real numbers.** Every value is parsed from MC9's own numeric output: operating points, AC / transient / DC tables, THD, Rin, Rout ...
+- ✏️ **Circuits from code.** Describe a circuit like a SPICE netlist and get a *placed, routed, collision-free* MC9 schematic; or place parts by hand.
+- 🛡️ **Safe by design.** On Linux MC9 runs in a bubblewrap sandbox: no network, no access to your files. Your circuits are copied in, never modified.
+- 🪟 **Windows and Linux.** Native Win32 driver on Windows, sandboxed Wine on Linux. One API.
+- 🤖 **AI-ready.** A built-in [MCP](https://modelcontextprotocol.io) server lets an assistant build, simulate and photograph circuits for you.
+
+## A 60-second tour
+
+```python
+import mc9
+from mc9 import Netlist, measure, sources
+
+n = Netlist()                                       # 1. describe a circuit
+n.V("V1", "in", "0", sources.sine(0.1, 1e3))
+n.R("R1", "in", "out", "1k")
+n.C("C1", "out", "0", "159.155n")                   #    RC low-pass, fc = 1 kHz
+c = n.build("rc")                                   #    placed + routed + written for MC9
+
+print(c.op().nodes)                                 # 2. DC operating point
+r = c.ac(10, 1e5, 401, ["db(v(out))"])              # 3. AC sweep -> numbers
+bw = measure.bandwidth(c, "db(v(out))", cursors=True)   # 4. -3 dB point, MC9's cursors placed on it
+print(f"{bw.f_high:.1f} Hz")                        #    998 Hz
+
+c.shot("rc_ac.png")                                 # 5. MC9's own plot, cursor table included
+c.dynamic_dc(25); c.shot("rc_dc.png", "schematic")  # 6. schematic with node voltages
+```
+
+Working on an existing lab file? `c = mc9.open("my_lab/amplifier.cir")` copies it into the work folder; then `c.parts()`,
+`c.set("R2", "RESISTANCE", "180k")`, `c.ac(...)`, `c.cursors(...)`, `c.shot(...)`, `c.export(...)` (writes a *new* file).
+
+## Install
+
+### Step 1 - install the Python package
+
+You need **Python 3.10 or newer** and **git**. `pip` is Python's package installer; it comes with Python. mc9py is **not on PyPI yet**
+(so `pip install mc9py` does not work yet) - install it straight from GitHub. Use a *virtual environment*, a private folder for
+Python packages that keeps your system clean:
+
+<details open><summary><b>Linux / macOS</b></summary>
+
+```bash
+python3 -m venv ~/mc9-env                       # create the environment once
+source ~/mc9-env/bin/activate                   # activate it (repeat in every new terminal)
+pip install "git+https://github.com/DontforgetAntaiku/mc9py.git"
+mc9 doctor                                      # prints what is installed and what is missing
+```
+</details>
+
+<details><summary><b>Windows (PowerShell)</b></summary>
+
+```powershell
+py -m venv $HOME\mc9-env                        # create the environment once
+& $HOME\mc9-env\Scripts\Activate.ps1            # activate it (repeat in every new terminal)
+pip install "git+https://github.com/DontforgetAntaiku/mc9py.git"
+mc9 doctor
+```
+</details>
+
+Want `mc9` available in every terminal without activating anything? Use [pipx](https://pipx.pypa.io) instead:
+`pipx install "git+https://github.com/DontforgetAntaiku/mc9py.git"`.
+For development: `git clone https://github.com/DontforgetAntaiku/mc9py && cd mc9py && pip install -e ".[dev]"`.
+Once the project is published on PyPI, `pip install mc9py` will do the same.
+
+### Step 2 - connect MC9
+
+<details open><summary><b>Linux</b> (MC9 runs in a sandbox: Wine + virtual display)</summary>
+
+```bash
+# 1. system packages: wine, bubblewrap, Xvfb, xdotool, ImageMagick  (package names for Arch / Debian / Fedora: see the docs)
+# 2. install MC9 once into a Wine prefix (the default ~/.wine is fine)
+WINEPREFIX=~/.wine wine /path/to/mc9-setup.exe
+# 3. create the sandbox snapshot (links to your home folders are removed from the copy)
+mc9 setup ~/.wine
+mc9 doctor                                      # everything should say [ok]
+```
+</details>
+
+<details><summary><b>Windows</b> (MC9 is driven natively)</summary>
+
+`mc9 doctor` finds `mc9.exe` in the usual install folders. If yours is elsewhere, tell the library once at the top of your script:
+`mc9.config.mc9_exe = r"D:\Tools\MC9\mc9.exe"`. Use 100 % display scaling and keep the keyboard and mouse free while a script runs.
+More in the [Windows page](https://dontforgetantaiku.github.io/mc9py/getting-started/install-windows/).
+</details>
+
+## What it can do
+
+| Area | Features |
+|---|---|
+| **Circuits** | open (copy) `.cir` files · list / get / set part values · raw `[Limits]` and curve editing · export to a *new* file · display toggles (voltages/currents/power) |
+| **Analyses** | operating point · AC (log sweep) · transient (steady-state windows) · DC sweep (temperature lists, several runs) · Distortion window · Dynamic DC · Dynamic AC phasors |
+| **Data** | `Result`/`Run`/`OP`: `value_at`, `cross`, `peak`, `trough`, `amplitude`, `mean`, CSV export · device tables (`IC`, `GM`, `RPI`, power ...) · SI-suffix parsing, `N/A` handling |
+| **Pictures** | plot / schematic / window screenshots · tight automatic crops · cursors placed at exact X values with MC9's own cursor table · maximized plot windows · failure screenshots with MC9's error dialog |
+| **Measurements** | `bandwidth` (-3 dB, low/high/band-pass) · `gain_at` · `rin` · `rout` (load removal) · `thd` (steady-state DFT) · `solve` (find the part value that hits a target) |
+| **Schematics** | `Schematic` builder (catalog: R C L V VB I D Q QP M OPAMP GND) · automatic label placement · `check()` / `audit()` / `pin_nets()` · auto centre & zoom · T-junction and node-name handling |
+| **Auto-placement** | SPICE-like `Netlist` → backbone + branches + rail/ground buses, label fallback to avoid crossings · verified net-for-net against your netlist · starter circuits in `mc9.library` |
+| **Platforms** | Linux: sandboxed Wine + Xvfb · Windows: Win32 API (language independent) |
+| **AI** | MCP server with 24 tools (files, analyses, cursors, screenshots, measurements, `build_netlist`, `build_schematic`) |
+| **Tooling** | `mc9 setup / doctor / reset / mcp` · 37 offline tests (run on Linux, Windows, macOS CI) · opt-in MC9 integration tests · MkDocs site · GitHub Actions CI |
+
+<p align="center">
+  <img src="docs/assets/ce_schematic_ac.png" width="49%" alt="Dynamic AC phasors">
+  <img src="docs/assets/inverting_schematic.png" width="49%" alt="inverting op-amp stage placed automatically">
+</p>
+<p align="center">
+  <img src="docs/assets/ce_transient.png" width="49%" alt="transient plot">
+  <img src="docs/assets/ce_distortion.png" width="49%" alt="MC9 distortion window">
+</p>
+
+## Automatic placement in one picture
+
+```python
+n = mc9.library.ce_amplifier().build("amp")     # a common-emitter stage from the starter library
+# or write your own:
+n = Netlist()
+n.V("V1", "src", "0", sources.sine(3.5e-3, 2224)); n.R("R1", "src", "ue", "200"); n.C("C1", "ue", "b", "3.47u")
+n.R("R2", "vcc", "b", "233.2k"); n.Q("Q1", c="col", b="b", e="0", model="BF420"); n.R("R3", "vcc", "col", "1.2k")
+n.C("C3", "col", "ua", "553n"); n.R("R4", "ua", "0", "1.2k"); n.VB("V2", "vcc", "0", "18")
+c = n.build("amp")                              # VB = 0.695 V, VC = 9.5 V, IC = 7.09 mA - as in the textbook calculation
+```
+
+How the placer works, in short: classify nodes → lay the **signal backbone** left to right → hang **branches** to ground (down) and
+rails (up) → draw **buses** → if wires would cross, that net falls back to **named labels** (MC9 joins equally named nodes) → check
+collisions with MC9's voltage boxes and re-space. Every generated drawing is verified to have exactly the nets of your netlist.
+
+## Use it from an AI assistant
+
+This is optional. It lets an AI assistant such as [Claude Code](https://claude.com/claude-code) or Claude Desktop drive MC9 through
+the library. You need the `mcp` extra, and the assistant must be able to *start the `mc9` program*:
+
+```bash
+# 1. install with the extra (inside your activated environment from Step 1)
+pip install "mc9py[mcp] @ git+https://github.com/DontforgetAntaiku/mc9py.git"
+
+# 2. find out where the mc9 program lives - you will paste this path below
+which mc9                                   # Windows PowerShell:  (Get-Command mc9).Source
+#   e.g.  /home/you/mc9-env/bin/mc9    or    C:\Users\you\mc9-env\Scripts\mc9.exe
+```
+
+**Claude Code** - run this once in an ordinary terminal (not inside Python), using the path from step 2:
+
+```bash
+claude mcp add microcap9 -- /home/you/mc9-env/bin/mc9 mcp
+claude mcp list                              # microcap9 should be listed; start `claude` and ask away
+```
+(If `mc9` is on your `PATH`, e.g. after `pipx install`, plain `claude mcp add microcap9 -- mc9 mcp` works.)
+
+**Claude Desktop and other MCP clients** - add this to the client's config file (Claude Desktop: *Settings -> Developer -> Edit Config*;
+file `~/.config/Claude/claude_desktop_config.json` on Linux, `%APPDATA%\Claude\claude_desktop_config.json` on Windows), with the path
+from step 2, then restart the client:
+
+```json
+{ "mcpServers": { "microcap9": { "command": "/home/you/mc9-env/bin/mc9", "args": ["mcp"] } } }
+```
+
+> "Build a common-emitter amplifier with a 12 V supply, find its −3 dB band and show me the AC plot with the cursors on the edges."
+
+More: [MCP guide](https://dontforgetantaiku.github.io/mc9py/guide/mcp/).
+
+## How it works
+
+```
+ your script / AI ─▶ mc9.Circuit · Schematic · Netlist · measure           (pure Python)
+                          │
+                 circuit-file editor ── numeric-output parser
+                          │
+                 ui flows (run, cursors, capture, error screenshots)
+                          │
+                  Driver ─┬─ Linux : bubblewrap + Wine + Xvfb + xdotool
+                          └─ Windows: Win32 API (ctypes)
+                          │
+                       MC9 (mc9.exe)  ⇄  files in the work folder
+```
+MC9 has no automation interface, so the library configures everything **in the circuit file**, starts MC9 on it, presses the few
+remaining buttons, reads MC9's numeric-output files and screenshots its window. Details: [architecture](https://DontforgetAntaiku.github.io/mc9py/internals/architecture/).
+
+## Status and honesty
+
+- **Linux/Wine** is the best-tested path: developed and verified against the Russian *GUAP Edition* of MC9 9.0.3.
+  Other editions/languages need a one-time [calibration](https://DontforgetAntaiku.github.io/mc9py/internals/calibration/) of the button positions.
+- **Windows** driver is language independent (keyboard accelerators + dialog classes). It is exercised by running Windows Python
+  under Wine against MC9 (same Win32 calls); **testers on real Windows are very welcome**.
+- Validated on real analyses: divider, RC filter (−3.01 dB at fc), inverting op-amp (20.00 dB), a BF420 common-emitter stage
+  (VC = 9.500 V, IC = 7.089 mA, Rin = 635 Ω, Rout = 1119 Ω, THD 8.6 % at 35 mV) - matching hand calculations.
+- A run takes ~15–30 s (MC9 has to start and simulate); sweeps/solvers take minutes.
+- Auto-placement targets teaching circuits (filters, clippers, single-stage amplifiers, op-amp stages); odd topologies fall back to labels.
+
+## Documentation
+
+Full guide, API reference, internals and FAQ: **<https://DontforgetAntaiku.github.io/mc9py/>** (sources in [`docs/`](docs/)).
+
+## Contributing
+
+Bug reports with `mc9 doctor` output, calibrations for other MC9 editions, Windows test reports, new measurements, catalog parts and
+circuits the placer handles badly are all welcome - see [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
+Please **never** commit MC9 binaries, licence keys, decompiled code or other people's circuits.
+
+## License
+
+[MIT](LICENSE) © 2026 DontforgetAntaiku.
+
+`mc9py` is an independent project. **Micro-Cap® is a trademark of Spectrum Software**; this project is not affiliated with, endorsed
+by or sponsored by Spectrum Software, and it **does not contain or distribute MC9** - you need your own licensed copy and must follow its
+license terms. The circuit template bundled with the package holds only the small shape and pin descriptions that MC9 itself writes into
+every circuit it saves. Third-party libraries: [Pillow](https://python-pillow.org) (HPND), [`mcp`](https://github.com/modelcontextprotocol/python-sdk)
+(MIT, optional), MkDocs Material (MIT, docs only).

mc9py-0.2.0/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

mc9py-0.2.0/docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

mc9py-0.2.0/docs/faq.md

@@ -0,0 +1,35 @@
+# FAQ and gotchas
+
+## Does it modify my circuits?
+No. `mc9.open()` copies the file into the work folder; `Circuit.export()` writes to a new path and refuses to overwrite.
+
+## My band edge differs from what I read with MC9's cursors.
+With MC9's default AC `Sweep type = Auto` the numeric table is coarse and linear, and cursors interpolate between its points - band
+edges can be off by more than 10 %. `mc9` always sweeps logarithmically with 401+ points. Double `points` to confirm convergence.
+
+## "Node has no DC path to ground" / "label not found" / "model missing"
+These are MC9's own error dialogs. When a run fails the library saves `<circuit>_<analysis>_FAILED.png`; read the dialog in it.
+Typical causes: a node connected only through capacitors; a curve like `v(Out)` for a node that is not named; a model name that
+is not in MC9's library.
+
+## Why are voltage boxes overlapping each other in my schematic screenshot?
+MC9 draws them (centred on a pin of each node) and AC boxes are ~12 grid units wide. Space voltage nodes >= 14 grid units apart and
+build with `labels="ac"`. `Schematic.audit("ac")` lists the collisions before you run anything.
+
+## Why is THD computed by a DFT and not taken from MC9's Distortion analysis?
+MC9's distortion *numeric* table is a corrupted FFT buffer under Wine. The Distortion *window* is fine, so `c.distortion()` plus
+`c.shot()` gives MC9's own figure, while `measure.thd` gives numbers.
+
+## Cursor tables are cut off at the bottom.
+MC9 clips the lowest table when plots are stacked. Use one plot per page for figures with cursors.
+
+## Can I use it without a display / on a server?
+On Linux yes - the display is virtual (Xvfb). On Windows MC9 needs a desktop session.
+
+## Does it work with the standard English MC9?
+The Windows backend does not depend on the language. The Linux backend needs a one-time calibration for editions other than the
+Russian GUAP build; see [Supporting other MC9 editions](internals/calibration.md). Reports are welcome.
+
+## Is it legal to automate MC9?
+`mc9py` only drives your own licensed copy through its normal user interface and files. It contains no MC9 code or binaries.
+The component definitions in `mc9/templates/base.cir` are the small shape/pin descriptions that MC9 itself writes into every circuit it saves.