# 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

```bash
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

```bash
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:**
```bash
ssh -A warehack-ing@mcltspice.warehack.ing
```

**Project location on server:** `~/mcltspice/`

**Deploy steps:**
```bash
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:**
```bash
ssh -A warehack-ing@mcltspice.warehack.ing "cd mcltspice && git pull && cd docs && make prod"
```

### Full Release Checklist

1. Bump version in `pyproject.toml`
2. Commit and push to both remotes
3. Build and publish to PyPI
4. SSH to server, pull, `make prod`
5. 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)