ngspice-mcp

ngspice-mcp

2
developer_toolsdatabases

The ngspice-mcp project is an MCP server providing standardized protocol-based access to ngspice's circuit simulation capabilities. It supports structured data access and integrates seamlessly with ngspice, allowing for flexible simulation and data retrieval. Key features include vector data handling and comprehensive output management.

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
  1. Library Mode
dub build --config=library
  1. 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 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