NgSpice MCP Integration

I developed a Model Context Protocol (MCP) server that enables AI language models to interact with NgSpice, a powerful open-source circuit simulation engine. This integration allows AI models to perform circuit analysis and simulation through a standardized, type-safe interface.

Project Overview

NgSpice is an industrial-strength circuit simulator that implements Berkeley SPICE. While powerful, its interface can be complex and challenging to interact with programmatically. This project bridges that gap by providing a well-structured API through the Model Context Protocol, making circuit simulation capabilities accessible to AI language models.

Key Features

Type-Safe Implementation

I developed the server in D, leveraging the language's strong type system to create a robust and reliable interface. The implementation ensures type safety while maintaining the flexibility needed for the dynamic JSON-based protocol.

NgSpice Integration

• Comprehensive bindings to NgSpice's shared library interface
• Support for circuit loading from both strings and files
• Full access to simulation capabilities and vector data
• Working directory management for circuit files

Advanced Data Handling

• Multiple vector data representation formats:
  • Magnitude-phase for AC analysis
  • Rectangular (real-imaginary) for complex values
  • Scientific notation for precise numeric representation
• Efficient interval-based data selection using binary search
• Support for different simulation types (DC, AC, transient)

Thread-Safe Output System

• Concurrent output capture with mutex protection
• Sliding window buffer for efficient memory use
• Automatic truncation of large outputs
• Separate stdout and stderr streams with error detection

Technical Implementation

Architecture

The project is structured around several key components:

1. Core Server

   • Extends the base MCP server with NgSpice-specific functionality
   • Implements comprehensive tool registration and handling
   • Manages resource lifecycle and notification system

2. Vector Processing

   • Handles complex number representations
   • Provides flexible data interval selection
   • Implements scientific notation formatting
   • Supports multiple data representation formats

3. Output Management

   • Thread-safe output buffering
   • Resource-based access to captured output
   • Automatic stream classification (stdout/stderr)
   • Buffer size management with truncation markers

Tool Interface

The server provides a comprehensive set of tools:

• Circuit loading from strings or files
• Simulation command execution
• Plot and vector name enumeration
• Vector data retrieval with format options
• Working directory management

Challenges & Solutions

Thread-Safe Output Handling

Capturing NgSpice's output required careful consideration of concurrent access. I implemented a thread-safe buffer system using mutexes to prevent race conditions while maintaining efficient memory use through a sliding window approach.

Complex Data Representation

Circuit simulation often produces complex numbers that need different representations depending on the analysis type. I solved this by implementing a flexible system that can present data in:

• Magnitude and phase format for AC analysis
• Real and imaginary components for mathematical analysis
• Both formats when needed for comprehensive analysis

NgSpice Integration

Integrating with NgSpice's shared library required careful handling of callbacks and state management. I implemented a robust binding system that:

• Manages NgSpice initialization and cleanup
• Handles simulation state and errors
• Provides proper cleanup on server exit
• Redirects output streams appropriately

Data Interval Selection

To handle large datasets efficiently, I implemented an interval selection system using binary search, allowing clients to request specific ranges of data while maintaining memory efficiency and performance.

Visit the GitHub repository for complete documentation, examples, and source code.