Ngspice MCP

🚀 ngspice-mcp Server

An MCP (Model Context Protocol) server that provides access to ngspice circuit simulation capabilities. This server enables interaction between AI language models and ngspice through a standardized protocol interface, making it more structured and controlled.

🚀 Quick Start

The ngspice - mcp server allows AI language models to interact with ngspice in a structured and controlled manner. It integrates ngspice shared library interfaces and implements the MCP protocol.

✨ Features

• Integrate the ngspice shared library interface.
• Implement the standard version of the MCP protocol.
• Synchronous operations with structured data access.
• Comprehensively capture output and perform redirection.
• Process vector data and support multiple representation formats.
• Support both server mode and library mode usage.
• Include a built - in test suite.

📦 Installation

System Requirements

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

Installation Steps

1. Install the system's essential components.
2. Clone the code repository.
3. Build using dub:

dub build --config=server

💻 Usage Examples

Starting the Server

./ngspice-mcp [options]

Command - line Options

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

Available Tools

Circuit Loading

• loadCircuit: Directly load a circuit netlist.
• loadNetlistFromFile: Load a netlist from a file.

Example netlist:

RC 回路
R1 in out 1k
C1 out 0 1u
.end

Simulation Execution

• runSimulation: Execute simulation commands.

Common commands include:

• 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: Get the names of vectors in a specific plot.
• getVectorData: Retrieve vector data, supporting:
  • Magnitude - phase representation
  • Real - imaginary representation
  • Display both representations simultaneously
  • Optional interval selection

Resource Access

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

📚 Documentation

Project Structure

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

Build Configurations

1. Server Mode

dub build --config=server

2. Library Mode

dub build --config=library

3. Unit Testing

dub test --config=unittest

Testing

Run the test suite:

dub test

The test coverage includes:

• Verification of ngspice bindings.
• Testing of server functions.
• Testing of tool availability.
• Evaluation of data processing correctness.

🔧 Technical Details

System Architecture

The system consists of the following key components:

1. Main Program (app.d)
   • Receive and parse user input commands.
   • Initialize relevant service modules.
   • Coordinate communication between components.
2. ngspice Bindings (bindings/)
   • Wrap the ngspice dynamic library interface.
   • Provide high - level functions for easy invocation of simulation capabilities.
   • Handle interactions with native code.
3. Database Handling (database/)
   • Manage input and output data of simulations.
   • Save and retrieve historical results.
   • Perform complex data query operations.
4. Netlist Parser (parser/)
   • Parse circuit netlist file formats.
   • Validate syntax correctness.
   • Provide an abstract circuit representation model.
5. Server Implementation (server/)
   • Implement the MCP protocol interface.
   • Handle client connections and requests.
   • Provide support for remote call services.

Database System

The database module manages data during the simulation process, with the following main functions:

1. Data Storage
   • Persist circuit configurations, parameters, and results to an SQLite database.
   • Support transaction processing to ensure data consistency.
2. Data Query
   • Provide flexible combinations of query conditions.
   • Support complex data correlation analysis.
   • Optimize the performance of common query paths.
3. Data Processing
   • Perform necessary data conversion and calculations.
   • Manage data validity periods and version control.
   • Handle archiving and cleaning of historical data.

Usage Instructions

1. Install Dependencies

dub fetch d-mcp-server ngspice

2. Build the Project

dub build --config=server

3. Run an Example

./ngspice-mcp --working-dir examples/

4. Access Interfaces

• HTTP interface: http://localhost:8080
• gRPC interface: localhost:50051

🤝 Contribution Guidelines

Contributions to the code and documentation are welcome!

• Submit bug fixes.
• Add new features.
• Improve test cases.
• Enhance documentation.

Please follow these steps to contribute:

1. Fork the project repository.
2. Create a new feature branch.
3. Submit code changes.
4. Submit a Pull Request.

📄 License

This project is licensed under the MIT License.

📞 Contact

If you have any questions or suggestions, please contact:

• Email: contact@ngspice - mcp.com
• GitHub: https://github.com/yourusername/ngspice-mcp

Thank you for using the ngspice - mcp server!