# @zesun33/mcp-spice

> Model Context Protocol (MCP) server for ngspice batch circuit simulation.

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
[![CI](https://github.com/zesun33/mcp-spice/actions/workflows/ci.yml/badge.svg)](https://github.com/zesun33/mcp-spice/actions/workflows/ci.yml)
[![Protocol: MCP](https://img.shields.io/badge/protocol-MCP_stdio-blueviolet)](https://modelcontextprotocol.io)
[![Runtime: Rootless Podman](https://img.shields.io/badge/runtime-rootless_podman-brightgreen)](#execution-runtime)

`mcp-spice` lets AI coding agents and IDEs (**Cursor**, **Windsurf**, **GitHub Copilot / OpenAI Codex**, **Claude Code**, **Google Antigravity**, **OpenCode**, **Cline**) run SPICE netlists with ngspice in batch mode and get `.meas` results back as JSON instead of plot windows or thousand-line logs.

One-step with the rest of the family:

```bash
npx @zesun33/create-hw-agent my-asic
```

Or this server alone after it is on npm:

```bash
npx -y @zesun33/mcp-spice
```

---

## Tools Exposed

| Tool | Parameters | Engine | Description |
| :--- | :--- | :--- | :--- |
| `spice_run` | `netlist: string`, `cwd?: string`, `timeout_ms?: number` | `ngspice -b` | Batch simulate a `.cir`/`.sp` file. Parses `.meas` assignments. Does not plot. |
| `spice_toolchain_info` | *none* | Probe | ngspice version and active runtime/image. |

```json
// Tool Call: spice_run {"netlist": "rc_lowpass.cir"}
{
  "success": true,
  "measurements": [{ "name": "vmid", "value": 0.63 }]
}
```

---

## Execution Runtime

`mcp-spice` runs inside the [`zesun33/spice`](https://github.com/zesun33/eda-docker-images) rootless Podman image.

**Public install (recommended — anyone can pull):**
```bash
podman pull ghcr.io/zesun33/spice:latest
export MCP_SPICE_IMAGE=ghcr.io/zesun33/spice
```

Public GHCR (`ghcr.io/zesun33/spice`) is the default. Local builds still work as `localhost/zesun33/spice` via `MCP_SPICE_IMAGE`. To force host binaries: `export MCP_SPICE_RUNTIME=host`.

---

## Universal Client & AI IDE Setup

| Environment | Setup Location |
| :--- | :--- |
| **AI IDEs** | `.cursor/mcp.json` or `.windsurf/mcp.json` |
| **CLI Agents** | Claude Code / OpenCode MCP config |
| **Desktop** | `claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "spice": {
      "command": "npx",
      "args": ["-y", "@zesun33/mcp-spice"],
      "env": { "MCP_SPICE_IMAGE": "ghcr.io/zesun33/spice" }
    }
  }
}
```

Until the package is on npm, point `command` at `node` and `args` at this repo's `dist/index.js`.

---

## Verification & Testing

```bash
./scripts/verify.sh          # full, needs podman + spice image
./scripts/verify.sh --quick  # CI
```