ngspice-mcp

A Model Context Protocol (MCP) server that provides access to ngspice circuit simulation functionality through a standardized protocol interface. This server enables AI language models to interact with ngspice in a controlled and structured way.

Features

• Integration with ngspice's shared library interface
• Standardized MCP protocol implementation
• Synchronous operation with structured data access
• Comprehensive output capture and redirection
• Vector data handling with multiple representation formats
• Support for both server and library usage modes
• Built-in test suite

Requirements

• D compiler (DMD/LDC)
• ngspice shared library
• MCP server library (d-mcp-server)
• D build system (dub)

Installation

1. Ensure system requirements are installed

2. Clone the repository

3. Build using dub:

dub build --config=server

Usage

The server can be started with:

./ngspice-mcp [options]

Command Line Options

• `--working-dir`, `-d`: Set the working directory for circuit files (default: current directory)

Available Tools

Circuit Loading

• `loadCircuit`: Load circuit netlists directly
• `loadNetlistFromFile`: Load netlists from files

Example netlist:

RC Circuit
R1 in out 1k
C1 out 0 1u
.end

Simulation

• `runSimulation`: Execute simulation commands

Common commands:

• `op`: DC operating point
• `dc source start stop step`
• `ac dec points fstart fend`
• `tran step tstop`

Data Access

• `getPlotNames`: List available simulation plots
• `getVectorNames`: List vectors in a specific plot
• `getVectorData`: Retrieve vector data with options for:
  • Magnitude-phase representation
  • Rectangular (real-imaginary) representation
  • Both representations
  • Optional interval selection

Resources

• `stdout://`: Standard output stream from ngspice
• `stderr://`: Error output stream from ngspice
• `usage://`: Comprehensive usage guide

Development

Project Structure

ngspice-mcp/
├── source/
│   ├── app.d           # Main application
│   ├── bindings/       # ngspice C API bindings
│   ├── database/       # SQLite database handling
│   ├── parser/         # Netlist parsing
│   └── server/         # MCP server implementation
├── resources/          # Resource files
└── bin/               # Build outputs

Build Configurations

1. Server Mode

dub build --config=server

2. Library Mode

dub build --config=library

3. Unit Tests

dub test --config=unittest

Testing

Run the test suite:

dub test

Tests cover:

• ngspice bindings
• Server functionality
• Tool validation
• Resource handling
• Error cases

Technical Details

Architecture

The server implements several key components:

1. NgspiceServer: Core server implementation

2. Output System

3. Vector Processing

Database System

• Model parameter storage
• Efficient indexing and querying
• Transaction support
• Concurrent access handling

License

MIT License - see dub.json for details.

Copyright © 2024, Garret Noble

Contributing

Contributions are welcome! Please ensure:

1. Code follows project style and standards

2. Tests are included for new functionality

3. Documentation is updated as needed

4. Commit messages are clear and descriptive