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
- Tool registration and handling
- Resource management
- Output stream capture
- Vector data processing

2. Output System
- Stdout/stderr capture
- Stream buffering
- Resource notification

3. Vector Processing
- Complex number handling
- Scientific notation formatting
- Interval selection
- Multiple representation formats

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