FSDB MCP Server

A Model Context Protocol (MCP) server for reading and querying FSDB (Fast Signal Database) waveform files. This server provides programmatic access to FSDB files through the MCP protocol, enabling AI assistants and other clients to query waveform data, signals, scopes, and value changes.

Features

• Open and manage FSDB files - Open, close, and get information about FSDB waveform files
• Browse hierarchy - Navigate through scope hierarchies and list signals
• Search functionality - Search for signals and scopes by name pattern across the hierarchy
• Query signals - Get detailed signal information including ranges, types, and properties
• Read waveform data - Extract signal values at specific times or get value changes over time ranges
• Multiple format support - View values in binary, decimal, hexadecimal, or real formats
• Smart limits - Automatic truncation of large results to prevent memory issues (configurable)

Prerequisites

• Python 3.10 or higher (required for MCP SDK compatibility)
• Synopsys Verdi with NPI (Native Programming Interface) support
• VERDI_HOME environment variable set to your Verdi installation directory
• pynpi library (included with Verdi)
• Valid Verdi license

Note: The MCP SDK requires Python 3.10 or higher.

Installation

For detailed installation instructions, see INSTALL.md.

Quick Start

1. Set up the environment:

export VERDI_HOME=/path/to/verdi
export LD_LIBRARY_PATH=$VERDI_HOME/share/NPI/lib/linux64:$VERDI_HOME/platform/linux64/bin:$LD_LIBRARY_PATH

2. Create and activate virtual environment (Python 3.10+):

python3.10 -m venv venv
source venv/bin/activate

3. Install dependencies:

pip install --upgrade pip
pip install mcp

4. Test the installation:

python test_fsdb.py

Usage

Running the Server

Start the MCP server:

python server.py

The server communicates via stdin/stdout using the MCP protocol.

Available Tools

The server provides the following tools:

1. fsdb_is_fsdb

Check if a file is a valid FSDB file.

Parameters:

• path (string): Path to the file to check

Example:

{
  "path": "/path/to/waveform.fsdb"
}

2. fsdb_open

Open an FSDB waveform file.

Parameters:

• path (string): Path to the FSDB file

Returns: File information including time range, version, and properties

3. fsdb_close

Close an opened FSDB file.

Parameters:

• path (string): Path to the FSDB file to close

4. fsdb_get_info

Get detailed information about an opened FSDB file.

Parameters:

• path (string): Path to the FSDB file

Returns: File metadata including:

• Time range (min_time, max_time)
• Scale unit
• Version and simulation date
• Flags (has_glitch, has_assertion, etc.)

5. fsdb_list_scopes

List scopes in the FSDB file hierarchy.

Parameters:

• path (string): Path to the FSDB file
• scope_path (string, optional): Parent scope path to list children of

Returns: List of scopes with name, full_name, def_name, and type

Example:

{
  "path": "/path/to/waveform.fsdb",
  "scope_path": "tb_top.cpu"
}

6. fsdb_list_signals

List signals in a scope.

Parameters:

• path (string): Path to the FSDB file
• scope_path (string, optional): Scope path to list signals from

Returns: List of signals with properties

7. fsdb_get_signal_info

Get detailed information about a signal.

Parameters:

• path (string): Path to the FSDB file
• signal_path (string): Full signal path (e.g., "top.module1.signal_name")

Returns: Signal properties including:

• Name and full name
• Type information (is_real, is_string, etc.)
• Range information (left_range, right_range, range_size)
• Direction and other attributes

8. fsdb_get_signal_value

Get signal value at a specific time.

Parameters:

• path (string): Path to the FSDB file
• signal_path (string): Full signal path
• time (integer): Time point to query
• format (string, optional): Value format - "bin", "dec", "hex", or "real" (default: "hex")

Returns: Signal value at the specified time

Example:

{
  "path": "/path/to/waveform.fsdb",
  "signal_path": "tb_top.cpu.clk",
  "time": 1000,
  "format": "hex"
}

9. fsdb_get_signal_changes

Get signal value changes in a time range.

Parameters:

• path (string): Path to the FSDB file
• signal_path (string): Full signal path
• start_time (integer): Start time
• end_time (integer): End time
• format (string, optional): Value format - "bin", "dec", "hex", or "real" (default: "hex")

Returns: List of value changes with time and value

Example:

{
  "path": "/path/to/waveform.fsdb",
  "signal_path": "tb_top.cpu.data",
  "start_time": 0,
  "end_time": 10000,
  "format": "hex"
}

10. fsdb_search

Search for signals and scopes by name pattern in the FSDB file.

Parameters:

• path (string): Path to the FSDB file
• pattern (string): Search pattern (case-insensitive substring match)
• search_type (string, optional): Type of items to search - "signals", "scopes", or "all" (default: "all")
• scope_path (string, optional): Scope path to limit search (e.g., "top.module1"). If not provided, searches entire hierarchy.

Returns: Search results with matching signals and/or scopes

Example:

{
  "path": "/path/to/waveform.fsdb",
  "pattern": "clk",
  "search_type": "signals",
  "scope_path": "tb_top"
}

Resources

The server exposes opened FSDB files as resources with the URI scheme fsdb://. Each opened file can be read as a resource to get its information and top-level scopes.

Example Workflow

1. Check if file is FSDB:

{
  "tool": "fsdb_is_fsdb",
  "arguments": {
    "path": "waveform.fsdb"
  }
}

2. Open the file:

{
  "tool": "fsdb_open",
  "arguments": {
    "path": "waveform.fsdb"
  }
}

3. List top-level scopes:

{
  "tool": "fsdb_list_scopes",
  "arguments": {
    "path": "waveform.fsdb"
  }
}

4. List signals in a scope:

{
  "tool": "fsdb_list_signals",
  "arguments": {
    "path": "waveform.fsdb",
    "scope_path": "tb_top"
  }
}

5. Get signal value changes:

{
  "tool": "fsdb_get_signal_changes",
  "arguments": {
    "path": "waveform.fsdb",
    "signal_path": "tb_top.clk",
    "start_time": 0,
    "end_time": 1000,
    "format": "bin"
  }
}

6. Close the file:

{
  "tool": "fsdb_close",
  "arguments": {
    "path": "waveform.fsdb"
  }
}

Architecture

The server is built on:

• MCP (Model Context Protocol): For standardized communication with AI assistants
• pynpi: Synopsys NPI Python bindings for FSDB access
• waveform.py: High-level Python API for waveform manipulation

Error Handling

The server provides detailed error messages for common issues:

• File not found
• Invalid FSDB file
• File not opened (must open before querying)
• Signal or scope not found
• Invalid time ranges

Limitations

• Requires Synopsys Verdi installation with NPI support
• Only supports FSDB format (not VCD, EVCD, etc.)
• Performance depends on FSDB file size and query complexity
• Must have proper VERDI_HOME and LD_LIBRARY_PATH configuration

Development

Project Structure

fsdb-mcp/
├── server.py                    # Main MCP server implementation
├── requirements.txt             # Python dependencies
├── mcp-config-example.json      # Example MCP configuration
├── update_mcp_config.sh         # Script to update MCP config
├── test.fsdb                    # Example FSDB file for testing
├── waveform.py                  # Symlink to Verdi's waveform module
├── docs/                        # Documentation
│   ├── README.md                # Documentation index
│   ├── INSTALL.md               # Installation guide
│   ├── LIMITS_CONFIG.md         # Return limits configuration
│   ├── TEST_FINAL_REPORT.md     # Complete test report
│   ├── MCP_TEST_SUMMARY.md      # MCP protocol test summary
│   └── README_CN.md             # Chinese README
├── tests/                       # Test scripts
│   ├── README.md                # Test documentation
│   ├── test_server_tools.py     # Direct API tests
│   ├── test_mcp_client.py       # MCP protocol tests
│   └── test_fsdb.py             # Basic FSDB tests
└── venv/                        # Virtual environment

Adding New Features

To add new tools: {{ ... }} 2. Implement tool logic in handle_call_tool() 3. Update documentation

Configuration

Return Limits

The server automatically limits the amount of data returned to prevent memory issues:

• Signals: Max 1000 per query
• Scopes: Max 1000 per query
• Value changes: Max 10000 per query

When results are truncated, the response includes:

{
  "data": [...],
  "total": 5000,
  "returned": 1000,
  "truncated": true
}

To adjust limits, edit server.py:

MAX_SIGNALS_RETURN = 1000
MAX_SCOPES_RETURN = 1000
MAX_CHANGES_RETURN = 10000

See LIMITS_CONFIG.md for detailed information.

Troubleshooting

Issue: "pynpi not available"

• Ensure VERDI_HOME is set correctly
• Check that pynpi library path is accessible
• Verify LD_LIBRARY_PATH includes Verdi libraries

Issue: "Failed to open FSDB file"

• Verify file exists and is readable
• Check file is valid FSDB format using fsdb_is_fsdb
• Ensure Verdi license is available

Issue: "Signal not found"

• Use fsdb_list_signals to see available signals
• Check signal path syntax (use dot notation: "scope.signal")
• Verify scope hierarchy with fsdb_list_scopes

License

This project uses Synopsys Verdi NPI libraries which are subject to Synopsys licensing terms.

Contributing

Contributions are welcome! Please ensure:

• Code follows existing style
• New tools are documented
• Error handling is comprehensive
• Changes are tested with real FSDB files

Support

For issues related to:

• MCP protocol: See MCP documentation
• FSDB/Verdi: Contact Synopsys support
• This server: Open an issue in the repository