MCP/mcltspice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add SpiceBook docs -- reference page, tutorial, and updated indexes

Browse Source 
New pages:
- reference/spicebook: all 5 SpiceBook tools with params, returns, examples
- tutorials/publish-to-spicebook: end-to-end workflow guide

Updated pages:
- reference/index: add SpiceBook LinkCard, bump tool/resource/prompt counts
- reference/resources: add spicebook://status resource
- reference/prompts: add publish_to_spicebook prompt
- tutorials/index: add Publish to SpiceBook LinkCard
- sidebar: SpiceBook entry with "New" badge
This commit is contained in:
Ryan Malloy 2026-02-20 16:15:37 -07:00
parent 71dfdc8d94
commit 6acf08f80d
7 changed files with 367 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/astro.config.mjs
View File

@ -40,6 +40,7 @@ export default defineConfig({
{ label: 'Overview', slug: 'tutorials' },
{ label: 'Design a Filter', slug: 'tutorials/design-a-filter' },
{ label: 'Monte Carlo Yield', slug: 'tutorials/monte-carlo-yield' },
{ label: 'Publish to SpiceBook', slug: 'tutorials/publish-to-spicebook' },
],
},
{
@ -54,6 +55,7 @@ export default defineConfig({
{ label: 'Stability & Power', slug: 'reference/stability-power' },
{ label: 'Schematic & Netlist', slug: 'reference/schematic-netlist' },
{ label: 'Library & Templates', slug: 'reference/library-templates' },
{ label: 'SpiceBook', slug: 'reference/spicebook', badge: { text: 'New', variant: 'note' } },
{ label: 'Resources', slug: 'reference/resources' },
{ label: 'Prompts', slug: 'reference/prompts' },
],

16
docs/src/content/docs/reference/index.mdx
View File

@ -5,7 +5,7 @@ description: Complete reference for all mcltspice tools, resources, and prompts.
import { LinkCard } from '@astrojs/starlight/components';
mcltspice exposes 37 tools, 5 resources, and 7 prompts. This section documents every one of them with parameter types, defaults, return values, and usage notes.
mcltspice exposes 42 tools, 6 resources, and 8 prompts. This section documents every one of them with parameter types, defaults, return values, and usage notes.
## Tools by category
@ -51,16 +51,22 @@ mcltspice exposes 37 tools, 5 resources, and 7 prompts. This section documents e
href="/reference/library-templates/"
/>
<LinkCard
title="SpiceBook (5 tools)"
description="Publish circuits as interactive notebooks on SpiceBook, run remote ngspice simulations, list and manage published notebooks."
href="/reference/spicebook/"
/>
## Resources and prompts
<LinkCard
title="Resources (5 URIs)"
description="Read-only data sources exposed via MCP resource URIs --- symbols, examples, status, templates, and template detail."
title="Resources (6 URIs)"
description="Read-only data sources exposed via MCP resource URIs --- symbols, examples, status, templates, template detail, and SpiceBook status."
href="/reference/resources/"
/>
<LinkCard
title="Prompts (7 prompts)"
description="Guided workflows for filter design, power supply analysis, debugging, optimization, Monte Carlo, circuit creation, and troubleshooting."
title="Prompts (8 prompts)"
description="Guided workflows for filter design, power supply analysis, debugging, optimization, Monte Carlo, circuit creation, troubleshooting, and SpiceBook publishing."
href="/reference/prompts/"
/>

31
docs/src/content/docs/reference/prompts.mdx
View File

@ -7,7 +7,7 @@ import { Aside, Code } from '@astrojs/starlight/components';
MCP prompts are conversation starters. Each prompt generates an initial message that guides the LLM through a multi-step workflow, telling it which tools to call and in what order. Think of them as runbooks --- they encode best practices so the LLM does not have to figure out the workflow from scratch.
mcltspice provides 7 prompts covering filter design, power supply analysis, debugging, optimization, Monte Carlo yield analysis, building circuits from descriptions, and troubleshooting simulation failures.
mcltspice provides 8 prompts covering filter design, power supply analysis, debugging, optimization, Monte Carlo yield analysis, building circuits from descriptions, troubleshooting simulation failures, and publishing to SpiceBook.
<Aside type="note">
Prompt support varies by client. In Claude Code, prompts appear as suggested workflows. In other MCP clients, they may be listed in a prompt library or triggered from a menu.
@ -225,3 +225,32 @@ A diagnostic checklist for simulation failures and convergence issues. Works thr
- Unexpected clipping: check supply voltages and headroom
- Oscillation in DC circuits: add small feedback capacitors
- Model not found: verify `.lib` / `.include` paths
---
## publish_to_spicebook
Guides through publishing a circuit as an interactive notebook on [SpiceBook](https://spicebook.warehack.ing): verify locally in LTspice, test ngspice compatibility, publish with metadata, and verify the result.
<table class="param-table">
<thead>
<tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>circuit_description</td><td><code>str</code></td><td><code>""</code></td><td>Description of the circuit to publish. If empty, the prompt asks the LLM to describe it.</td></tr>
<tr><td>netlist_path</td><td><code>str</code></td><td><code>""</code></td><td>Path to the netlist or schematic. If empty, the prompt asks the LLM to identify or create one first.</td></tr>
</tbody>
</table>
**Workflow steps:**
1. **Verify locally** --- simulate with `simulate` or `simulate_netlist`, check results with `get_waveform` and `analyze_waveform`
2. **Test ngspice compatibility** --- run `spicebook_simulate` to dry-run the converted netlist on SpiceBook's engine; review any conversion warnings
3. **Publish** --- use `spicebook_publish` with title, description, and tags; optionally set `run=True` for immediate simulation
4. **Verify** --- use `spicebook_get` to confirm the notebook was created; share the URL
**Tips included in the prompt:**
- Add tags like `"filter"`, `"amplifier"`, `"power"` for discoverability
- The converter handles `.backanno`, `Rser=`, and Windows paths automatically
- Use `spicebook_list` to see all published notebooks
- Use `spicebook_delete` to clean up test notebooks

15
docs/src/content/docs/reference/resources.mdx
View File

@ -7,7 +7,7 @@ import { Aside } from '@astrojs/starlight/components';
MCP resources are read-only data sources that clients can attach to conversations for context. Unlike tools, resources are not invoked with parameters --- they are referenced by URI and return structured data. A client might attach `ltspice://status` at the start of a session so the LLM knows what is available without making a tool call.
mcltspice exposes 5 resources.
mcltspice exposes 6 resources.
<Aside type="note">
Resource support varies by MCP client. Claude Code currently reads resources when they are referenced in conversation context. Other clients may list available resources in a sidebar or attach them automatically.
@ -151,3 +151,16 @@ If the template exists in only one format (netlist or schematic), only that key
<Aside type="tip">
Use `ltspice://templates` to discover all available template names, then query `ltspice://template/{name}` for the one you need.
</Aside>
---
## spicebook://status
Current SpiceBook service status --- URL and reachability. Attaching this resource lets the LLM know whether SpiceBook is available for publishing without making a tool call.
```
SpiceBook URL: https://spicebook.warehack.ing
Status: reachable
```
If SpiceBook is unreachable (network issue, service down), the status will show `unreachable`. The URL can be changed via the `SPICEBOOK_URL` environment variable.

194
docs/src/content/docs/reference/spicebook.mdx Normal file
View File

@ -0,0 +1,194 @@
---
title: SpiceBook Integration
description: Publish circuits as interactive notebooks, run remote ngspice simulations, and manage notebooks on SpiceBook.
---
import { Aside } from '@astrojs/starlight/components';
These tools bridge mcltspice with [SpiceBook](https://spicebook.warehack.ing), a web notebook service for SPICE circuits. You can publish LTspice designs as interactive, runnable notebooks --- shareable via URL --- and test ngspice compatibility without leaving your MCP session.
<Aside type="tip">
The `publish_to_spicebook` prompt walks through the full workflow: verify locally, test ngspice compatibility, then publish. See [Prompts](/reference/prompts/#publish_to_spicebook).
</Aside>
---
### spicebook_publish
Publish an LTspice netlist as an interactive SpiceBook notebook. Reads the netlist from a string or file, converts it from LTspice dialect to ngspice (stripping `.backanno`, `Rser=`, Windows paths), builds notebook cells with an intro and the netlist, and creates the notebook via SpiceBook's compose endpoint.
<table class="param-table">
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
<tbody>
<tr><td>netlist_text</td><td>`str | None`</td><td>`None`</td><td>Netlist as a string. Mutually exclusive with `netlist_path`.</td></tr>
<tr><td>netlist_path</td><td>`str | None`</td><td>`None`</td><td>Path to a `.cir`, `.net`, `.sp`, `.spice`, or `.asc` file on disk.</td></tr>
<tr><td>title</td><td>`str`</td><td>`"Untitled Circuit"`</td><td>Notebook title, shown in the listing and intro cell.</td></tr>
<tr><td>description</td><td>`str | None`</td><td>`None`</td><td>Circuit description, rendered in the intro markdown cell.</td></tr>
<tr><td>tags</td><td>`list[str] | None`</td><td>`None`</td><td>Tags for categorization and search (e.g. `["filter", "audio"]`).</td></tr>
<tr><td>run</td><td>`bool`</td><td>`False`</td><td>If `True`, SpiceBook runs the simulation immediately on publish.</td></tr>
</tbody>
</table>
**Returns:** A dict with `notebook_id`, `url` (direct link to the notebook), `cell_count`, and `conversion_warnings` (list of strings describing any LTspice-to-ngspice changes).
<details>
<summary>Example</summary>
```json
{
"notebook_id": "rc-lowpass-filter-a3b2c1d4",
"url": "https://spicebook.warehack.ing/notebooks/rc-lowpass-filter-a3b2c1d4",
"cell_count": 2,
"conversion_warnings": [
"Stripped Rser= from: C1 out 0 100n Rser=0.1"
]
}
```
</details>
<Aside type="note">
The converter handles four LTspice-to-ngspice incompatibilities automatically: `.backanno` directives, `.options plotwinsize=0`, `.lib`/`.include` with Windows paths, and `Rser=` parasitic ESR on capacitors and inductors. Standard SPICE passes through untouched. Any changes are reported in `conversion_warnings`.
</Aside>
---
### spicebook_simulate
Run a netlist via SpiceBook's ngspice engine without creating a notebook. Useful for testing whether a netlist is ngspice-compatible before publishing. The netlist is converted from LTspice dialect first.
<table class="param-table">
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
<tbody>
<tr><td>netlist_text</td><td>`str | None`</td><td>`None`</td><td>Netlist as a string. Mutually exclusive with `netlist_path`.</td></tr>
<tr><td>netlist_path</td><td>`str | None`</td><td>`None`</td><td>Path to a netlist file on disk.</td></tr>
</tbody>
</table>
**Returns:** The simulation result from SpiceBook's ngspice engine, plus `conversion_warnings` if any LTspice constructs were modified.
<details>
<summary>Example</summary>
```json
{
"stdout": "...",
"stderr": "",
"returncode": 0,
"conversion_warnings": []
}
```
</details>
---
### spicebook_list
List all notebooks on SpiceBook. No parameters.
**Returns:** A dict with `notebooks` (array of notebook summaries) and `count`.
<details>
<summary>Example</summary>
```json
{
"notebooks": [
{
"id": "rc-lowpass-filter-a3b2c1d4",
"metadata": {
"title": "RC Lowpass Filter",
"tags": ["filter", "analog"],
"modified": "2026-02-15T21:45:24Z"
}
}
],
"count": 1
}
```
</details>
---
### spicebook_get
Retrieve a full SpiceBook notebook with all cells and outputs.
<table class="param-table">
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
<tbody>
<tr><td>notebook_id</td><td>`str`</td><td>---</td><td>The notebook ID to retrieve.</td></tr>
</tbody>
</table>
**Returns:** The complete notebook object including `metadata` (title, tags, engine, timestamps), `cells` (array of cell objects with type, source, and outputs), and `spicebook_version`.
<details>
<summary>Example</summary>
```json
{
"spicebook_version": "2026-02-13",
"metadata": {
"title": "RC Lowpass Filter",
"engine": "ngspice",
"tags": ["filter"],
"created": "2026-02-15T21:45:24Z",
"modified": "2026-02-15T21:45:24Z"
},
"cells": [
{
"id": "cell-abc123",
"type": "markdown",
"source": "# RC Lowpass Filter\n\nFirst-order filter with fc = 1.59 kHz",
"outputs": []
},
{
"id": "cell-def456",
"type": "spice",
"source": "V1 in 0 AC 1\nR1 in out 1k\nC1 out 0 100n\n.ac dec 100 1 1meg\n.end",
"outputs": []
}
]
}
```
</details>
---
### spicebook_delete
Delete a SpiceBook notebook.
<table class="param-table">
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
<tbody>
<tr><td>notebook_id</td><td>`str`</td><td>---</td><td>The notebook ID to delete.</td></tr>
</tbody>
</table>
**Returns:** `{"deleted": true, "notebook_id": "..."}` on success.
---
## Configuration
SpiceBook tools read two environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `SPICEBOOK_URL` | `https://spicebook.warehack.ing` | Base URL of the SpiceBook instance. |
| `SPICEBOOK_TIMEOUT` | `30` | HTTP request timeout in seconds. |
No authentication is required.
## Error handling
All SpiceBook tools return structured error dicts on failure:
- **Unreachable:** `{"error": "SpiceBook not reachable at <url>", "hint": "Check connectivity or set SPICEBOOK_URL env var"}`
- **Timeout:** `{"error": "SpiceBook request timed out"}`
- **HTTP error:** `{"error": "HTTP <status>", "detail": "<response body>"}`

1
docs/src/content/docs/tutorials/index.mdx
View File

@ -10,4 +10,5 @@ Tutorials walk you through complete workflows from start to finish. Each one bui
<CardGrid>
<LinkCard title="Design a Filter" href="/tutorials/design-a-filter/" description="Build an RC lowpass filter, measure its bandwidth, and iterate toward a target cutoff frequency." />
<LinkCard title="Monte Carlo Yield" href="/tutorials/monte-carlo-yield/" description="Run statistical analysis on component tolerances to estimate manufacturing yield." />
<LinkCard title="Publish to SpiceBook" href="/tutorials/publish-to-spicebook/" description="Convert an LTspice circuit to ngspice and publish it as an interactive notebook on SpiceBook." />
</CardGrid>

115
docs/src/content/docs/tutorials/publish-to-spicebook.mdx Normal file
View File

@ -0,0 +1,115 @@
---
title: Publish to SpiceBook
description: Design a circuit in LTspice, verify it works, and publish it as an interactive notebook on SpiceBook.
---
import { Steps, Aside, Code } from '@astrojs/starlight/components';
## Goal
Take an LTspice circuit, convert it to ngspice format, and publish it as an interactive notebook on [SpiceBook](https://spicebook.warehack.ing) --- shareable via URL and runnable in the browser.
## Workflow
<Steps>
1. **Create and simulate the circuit locally**
Start by building the circuit with mcltspice and verifying it works in LTspice. Here we use the built-in RC lowpass template:
```json
// create_from_template
{
"template": "rc_lowpass",
"params": { "r": "10k", "c": "1n" }
}
```
Then simulate:
```json
// simulate_netlist
{
"netlist_path": "/tmp/rc_lowpass.cir"
}
```
Confirm the simulation succeeds and check the frequency response with `measure_bandwidth` to verify the cutoff is around 15.9 kHz (1 / (2 * pi * 10k * 1n)).
2. **Test ngspice compatibility**
LTspice and ngspice have dialect differences. Before publishing, do a dry run on SpiceBook's ngspice engine:
```json
// spicebook_simulate
{
"netlist_path": "/tmp/rc_lowpass.cir"
}
```
Check the result for errors. If `conversion_warnings` appears, the converter handled known LTspice-isms automatically (`.backanno`, `Rser=`, Windows paths). If the simulation fails, adjust the netlist to remove any unsupported constructs.
3. **Publish the notebook**
Once ngspice compatibility is confirmed, publish with a descriptive title and tags:
```json
// spicebook_publish
{
"netlist_path": "/tmp/rc_lowpass.cir",
"title": "RC Lowpass Filter - 15.9 kHz Cutoff",
"description": "First-order RC lowpass with R=10k, C=1n. AC analysis from 1 Hz to 1 MHz.",
"tags": ["filter", "lowpass", "analog", "first-order"]
}
```
The response includes a direct URL to the notebook:
```json
{
"notebook_id": "rc-lowpass-filter-15-9-khz-cutoff-a1b2c3d4",
"url": "https://spicebook.warehack.ing/notebooks/rc-lowpass-filter-15-9-khz-cutoff-a1b2c3d4",
"cell_count": 2,
"conversion_warnings": []
}
```
4. **Verify the published notebook**
Retrieve the notebook to confirm it was created correctly:
```json
// spicebook_get
{
"notebook_id": "rc-lowpass-filter-15-9-khz-cutoff-a1b2c3d4"
}
```
The notebook is now live at the URL and can be shared with anyone. Visitors can view the netlist, modify it, and run simulations directly in the browser.
</Steps>
<Aside type="tip">
Set `run: true` in `spicebook_publish` to have SpiceBook execute the simulation immediately on publish. The notebook will already have simulation results when visitors open it.
</Aside>
## Managing notebooks
Use `spicebook_list` to see all published notebooks, and `spicebook_delete` to remove any that are no longer needed --- useful for cleaning up test notebooks.
## What gets converted
The publish tool automatically converts four LTspice-specific constructs to ngspice-compatible equivalents:
| LTspice construct | What happens |
|---|---|
| `.backanno` | Stripped (LTspice annotation directive) |
| `.options plotwinsize=0` | Stripped (LTspice buffer setting) |
| `.lib` / `.include` with Windows paths | Commented out with a warning |
| `Rser=` on capacitors or inductors | Stripped with a warning |
All changes are reported in `conversion_warnings` so you know exactly what was modified. Standard SPICE passes through untouched.
## Key takeaway
The full workflow --- design, simulate, verify, publish --- can happen in a single MCP session. SpiceBook notebooks are interactive: anyone with the URL can view, edit, and re-run the circuit without installing LTspice.