Metadata-Version: 2.4
Name: sv-nav-mcp
Version: 0.1.1
Summary: SystemVerilog Navigation MCP service for AI agents
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# sv-nav

SystemVerilog navigation MCP service for AI agents.

Wraps [slang-server](https://github.com/MikePopoloski/slang) 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

```bash
pip install sv-nav-mcp
```

## Requirements

- Python >= 3.11
- [slang-server](https://github.com/MikePopoloski/slang) binary in PATH

## Configuration

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

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

With verbose logging (output to stderr):

```json
{
  "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
