sv-nav-mcp 0.1.1

SystemVerilog Navigation MCP service for AI agents

sv-nav

SystemVerilog navigation MCP service for AI agents.

Wraps slang-server LSP capabilities into an MCP (Model Context Protocol) service, providing semantic APIs — AI agents can query by signal name and hierarchy path instead of file URI + line/column, and get structured, deduplicated results without dealing with LSP protocol details.

Installation

pip install sv-nav-mcp

Requirements

• Python >= 3.11
• slang-server binary in PATH

Configuration

Add to your project's .claude/settings.json or global ~/.claude/settings.json:

{
  "mcpServers": {
    "sv-nav": {
      "command": "sv-nav-mcp"
    }
  }
}

With verbose logging (output to stderr):

{
  "mcpServers": {
    "sv-nav": {
      "command": "sv-nav-mcp",
      "args": ["--verbose"]
    }
  }
}

Tools

Lifecycle

Tool	Description
sv_init	Initialize with top_module and build_file (.f). Required first call.
sv_refresh	Refresh file content after external changes. Optional file to refresh a single file.
sv_reinit	Full server restart. Expensive, use sparingly.

Navigation

Tool	Description
sv_search	Search symbols by regex. Global or scoped to a module/hierarchy path.
sv_definition	Get symbol definition with hover content. For modules/instances, also returns ports and params.
sv_refs	Find all references to a symbol or module.
sv_hierarchy	Browse instance hierarchy tree (Build mode).

Tracing

Tool	Description
sv_cone	Trace signal driver/load cone, automatically merging duplicate nodes (Build mode).

Diagnostics

Tool	Description
sv_diagnostics	Get compilation errors and warnings. Returns summary grouped by diagnostic code, supports filtering by code and severity.

sv_definition: Elaborated vs Declaration Data

The data level depends on the context parameter:

• Hierarchy path context (e.g. "top.cpu"): Returns elaborated data — instance-specific parameter values, resolved types (e.g. logic[7:0] instead of logic[W-1:0]). elaborated=True.
• Module name context (e.g. "cpu"): Returns declaration data — source-level defaults, no type/value enrichment. elaborated=False.
• No context: Global module search, declaration data.

Build File Format (.f)

sv_init requires a build file listing source files:

// One source file path per line
// Lines starting with // are comments
// Environment variables ($VAR, ${VAR}) are expanded
// +incdir+ directives and lines with unresolvable vars are skipped
rtl/module_a.sv
rtl/module_b.sv
$SHARED_DIR/util.sv

• Relative paths resolve from the .f file's directory
• No dependency ordering required

Typical Workflow

1. sv_init(top_module="ibex_core", build_file="rtl/ibex_core.f")
2. sv_search to find symbols of interest
3. sv_definition to get definition details and internal structure
4. sv_refs to find all usages
5. sv_cone to trace signal drivers/loads
6. sv_diagnostics to check for errors

License

MIT