mcltspice

MCP server for LTspice circuit simulation automation.

Project Layout

src/mcltspice/       # Package source (server.py is the FastMCP entry point)
tests/               # pytest suite (asyncio_mode=auto)
docs/                # Starlight docs site (Astro + Docker)

Development

uv run pytest tests/ -m "not integration"   # Unit tests (no LTspice needed)
uv run pytest tests/ -m integration          # Integration tests (needs Wine + LTspice)
uv run ruff check src/ tests/               # Lint
uv run mcltspice                             # Run MCP server locally

Versioning

Date-based: YYYY.MM.DD with .N suffix for same-day patches (e.g. 2026.02.14.1).

Bump in pyproject.toml before publishing.

Publishing to PyPI

rm -rf dist/ && uv build
uv publish --token "$(python3 -c "
import configparser; c=configparser.ConfigParser()
c.read('$HOME/.pypirc'); print(c['pypi']['password'])
")"

The sdist is kept slim (~100KB) via [tool.hatch.build.targets.sdist] include list in pyproject.toml.

Verify: uv pip install --dry-run --refresh mcltspice==<version>

Production Deployment

Git Remotes

Remote	URL	Purpose
`origin`	`git@git.supported.systems:warehack.ing/mcltspice.git`	Private (primary)
`mcp`	`git@git.supported.systems:MCP/mcltspice.git`	Org mirror

Push to both: git push origin main && git push mcp main

Docs Site (mcltspice.warehack.ing)

The production docs site runs as a Docker container behind caddy-docker-proxy on a remote server.

Server access:

ssh -A warehack-ing@mcltspice.warehack.ing

Project location on server: ~/mcltspice/

Deploy steps:

ssh -A warehack-ing@mcltspice.warehack.ing
cd mcltspice
git pull
cd docs
make prod

make prod builds the Astro static site inside Docker, serves it via an internal Caddy on :8080, and the external caddy-docker-proxy handles TLS at mcltspice.warehack.ing.

Server .env (already configured, don't change):

COMPOSE_PROJECT_NAME=mcltspice-docs
MODE=prod
SITE_DOMAIN=mcltspice.warehack.ing

One-liner from local machine:

ssh -A warehack-ing@mcltspice.warehack.ing "cd mcltspice && git pull && cd docs && make prod"

Full Release Checklist

Bump version in pyproject.toml
Commit and push to both remotes
Build and publish to PyPI
SSH to server, pull, make prod
Verify: curl -sI https://mcltspice.warehack.ing/

Data Shape Convention

raw_parser.py returns data with shape (n_vars, n_points) -- each row is one variable's full time series. Index as data[var_idx] (row), never data[:, var_idx] (column).

svg_plot.py

Pure SVG generation, no matplotlib. Key internals:

_render_subplot() draws grid, axes, labels, and one data path
_build_path_d() maps data arrays to SVG path coordinates
plot_timeseries_multi() overlays multiple traces using _render_subplot for the first trace + raw <path> elements for the rest
_OVERLAY_COLORS is an 8-color palette; _render_legend() draws the legend box
from __future__ import annotations is used here (safe -- no FastMCP tool definitions in this file)

3.3 KiB Raw Blame History