Content
# Tool List
> **v0.2.0** — Verilog / SystemVerilog / UVM Code Intelligent Analysis Tool
Parse HDL source code (`.sv` / `.svh` / `.v` / `.vh`) into a queryable code graph, supporting definition jump, reference search, module hierarchy analysis, signal drive tracking, UVM factory/TLM/config_db analysis, impact assessment, and integration with MCP and LSP.
```
┌──────────────┐
│ LSP / CLI │
└──────┬───────┘
│
┌────────▼────────┐
│ Query Engine │
│ (stack-graph) │
└────────┬────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌─────▼─────┐ ┌────▼────┐ ┌───────▼──┐
│ RocksDB │ │ SQLite │ │ Tantivy │
│ (graph) │ │(meta) │ │ (search) │
└───────────┘ └─────────┘ └──────────┘
│
┌─────▼─────────────────────────┐
│ tree-sitter-systemverilog │
│ (816 grammar rules) │
└───────────────────────────────┘
```
---
## Table of Contents
- [Features](#features)
- [Version Information](#version-information)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Command Reference](#cli-command-reference)
- [MCP Server](#mcp-server)
- [LSP Server](#lsp-server)
- [Architecture](#architecture)
- [Development](#development)
- [Documentation](#documentation)
- [License](#license)
## Features
| Feature | Description |
|------|------|
| **Module Hierarchy Tree** | View the complete instantiation structure of the design |
| **Definition Jump** | Locate the declaration position of any identifier (module, class, port, signal, function) |
| **Reference Search** | Find all usage points of a signal/module/class in the project |
| **Signal Flow Tracking** | Track the drivers (writes) and reads of a signal |
| **Call Graph Analysis** | View the callers and callees of a function/task |
| **Impact Analysis** | BFS assess the impact scope of a modification (depth 3) |
| **UVM Support** | Factory registration/override, TLM port connection, config_db tracking, class inheritance hierarchy |
| **MCP Server** | Provide 15 code analysis tools for AI assistants like Claude, Cursor |
| **LSP Server** | Integrate with VS Code / Neovim / Emacs |
| **SCIP Export** | Compatible with Sourcegraph and GitHub Code Search |
| **Incremental Indexing** | Real-time update (100ms debounce) when files change |
| **Graph Consistency Check** | Detect dangling edges, unresolved instances, isolated nodes |
| **Multi-format Export** | SCIP / JSON / Markdown three formats |
## Version Information
| Component | Version | Description |
|------|------|------|
| `hdl-graph-cli` | 0.2.0 | CLI main binary |
| `hdl-graph-mcp` | 0.2.0 | MCP server |
| `hdl-graph-core` | 0.2.0 | Core data structure |
| `hdl-graph-grammar` | 0.2.0 | tree-sitter SystemVerilog grammar |
| `hdl-graph-parse` | 0.2.0 | CST traversal and node extraction |
| `hdl-graph-storage` | 0.2.0 | RocksDB persistence + InMemoryGraph |
| `hdl-graph-query` | 0.2.0 | Query engine and exporter |
| `hdl-graph-lsp` | 0.2.0 | LSP language server |
| `hdl-graph-types` | 0.2.0 | Shared type definitions |
| `hdl-graph-build` | 0.2.0 | Build assistant |
| `hdl-graph-web` | 0.2.0 | Web interface |
| VS Code extension | 0.2.0 | Editor extension |
| `rmcp-sdk` | 1.7.0 | MCP protocol SDK (embedded) |
## Installation
### Homebrew (macOS)
```bash
brew install hdl-graph/tap/hdl-graph
```
### Cargo
```bash
cargo install hdl-graph-cli
```
### Debian / Ubuntu
```bash
sudo dpkg -i hdl-graph_0.2.0_amd64.deb
```
### VS Code Extension
Install `hdl-graph.vsix` from marketplace, or manually:
```bash
# Download .vsix file
code --install-extension hdl-graph-0.2.0.vsix
```
### Offline Installation (No Internet)
For servers without internet access, like Rocky Linux / CentOS / RHEL:
```bash
# 1. Transfer offline package
scp hdl-graph-offline-v0.2.0-*.tar.gz user@server:/tmp/
# 2. Extract and install
ssh user@server
cd /tmp && tar xzf hdl-graph-offline-v0.2.0-*.tar.gz
cd hdl-codegraph && bash install.sh
# 3. Verify
hdl-graph --version
```
The installation script automatically completes: system dependency check → Rust toolchain installation → Cargo offline configuration → compilation → installation to `/usr/local/bin`.
Custom installation path: `bash install.sh --prefix=/opt/tools`
See [OFFLINE_INSTALL.md](OFFLINE_INSTALL.md) for details.
### Build from Source
```bash
git clone https://github.com/hedge88/hdl-codegraph.git
cd hdl-codegraph
cargo build --release
```
The compiled product is located at `target/release/hdl-graph` and `target/release/hdl-graph-mcp`.
### System Requirements
| Item | Minimum Requirement |
|------|----------|
| Operating System | macOS / Linux (Rocky 8+, CentOS 7+, RHEL 7+) |
| Architecture | x86_64, aarch64 |
| Disk | 3 GB (during compilation) |
| Memory | 2 GB |
| System Dependency | gcc, g++, cmake, make, clang-devel |
## Quick Start
```bash
# 1. Initialize project configuration
hdl-graph init .
# 2. Index HDL source code
hdl-graph index
# 3. Query symbol definition
hdl-graph query def my_fifo
# 4. Find all references
hdl-graph query refs clk
# 5. View module hierarchy
hdl-graph query hierarchy top_module
# 6. Search symbol
hdl-graph search apb_*
# 7. UVM factory analysis
hdl-graph uvm factory my_driver
# 8. Track signal drive
hdl-graph query drivers data_out
# 9. Assess modification impact
hdl-graph query impact config_reg
```
## CLI Command Reference
### Global Options
The following options apply to all subcommands:
| Option | Type | Default | Description |
|------|------|--------|------|
| `--project <dir>` | Path | `.` | HDL project root directory |
| `--include-dirs <dirs>` | Vec | Empty | Extra scan directories (can be specified multiple times) |
| `--uvm-home <dir>` | Path | None | UVM library directory path |
| `--defines <DEF>` | Vec | Empty | Preprocessor macro definitions (can be specified multiple times) |
| `--jobs <N>` | usize | CPU cores | Number of parallel indexing tasks |
| `--format <fmt>` | text/json | `text` | Output format |
| `--db <path>` | Path | Memory | Graph database file path |
| `-v, --verbose` | flag | false | Enable debug logging |
### Basic Commands
#### `hdl-graph init [dir]`
Initialize `.hdl-graph/` project configuration directory, generate default `config.toml`.
```bash
hdl-graph init . # Initialize in current directory
hdl-graph init ./myproj # Initialize in specified directory
```
#### `hdl-graph index [--watch]`
Parse HDL source code and build code graph index. Scan `.sv`, `.svh`, `.v`, `.vh` files, use tree-sitter to parse, extract nodes and edges.
```bash
hdl-graph index # Build index
hdl-graph index --watch # Listen to file changes, incremental update (100ms debounce)
```
#### `hdl-graph search <pattern>`
Search symbols by name pattern, support case-insensitive substring matching and glob wildcard (`*`, `?`).
```bash
hdl-graph search fifo # Search for symbols containing "fifo"
hdl-graph search apb_* # Search for symbols starting with "apb_"
hdl-graph search *_driver # Search for symbols ending with "_driver"
```
#### `hdl-graph stats`
Display graph statistics: number of files, total nodes/edges, and counts by type (module, port, signal, instance, always block, assignment, class, package, function, etc.).
```bash
hdl-graph stats
```
#### `hdl-graph check [--ci]`
Run graph consistency check, report issues:
- **Dangling edges** — Edges with non-existent source or target nodes
- **Unresolved instances** — Module instances with undefined `module_type`
- **Isolated nodes** — Nodes without any connected edges (excluding SourceFile)
- **Unresolved parent class** — Classes with undefined parent class
```bash
hdl-graph check # Display check results
hdl-graph check --ci # CI mode (exit with non-zero code on failure)
```
#### `hdl-graph files [glob]`
List indexed files and their statistics (number of nodes, modules, classes, instances, signals). Support glob pattern filtering.
```bash
hdl-graph files # List all files
hdl-graph files "*.sv" # List only .sv files
hdl-graph files "rtl/*" # List only files in rtl/ directory
```
#### `hdl-graph watch`
Start LSP language server (stdio mode) for editor integration.
```bash
hdl-graph watch
```
#### `hdl-graph version`
Print version number.
```bash
hdl-graph version
# Output: hdl-graph 0.2.0
```
### Query Commands (`hdl-graph query`)
#### `query def <symbol> [scope]`
Find the definition location of a symbol. Support module, class, package, port, signal, instance, etc.
```bash
hdl-graph query def my_module
hdl-graph query def data_in
hdl-graph query def apb_slave "file:100"
```
#### `query refs <symbol> [scope]`
Find all references of a symbol in the project. Track References, Drives, Extends, Calls, ConfigSets, ConfigGets, Instantiates, Connects, FactoryRegisters, FactoryOverrides, TLMBinds.
```bash
hdl-graph query refs clk
hdl-graph query refs reset_n
```
#### `query hierarchy <name>`
Display the instantiation hierarchy of a module or class, show subtree format.
```bash
hdl-graph query hierarchy top_module
hdl-graph query hierarchy my_env
```
#### `query calls <name>`
Display the call graph of a function or task, list all call sites.
```bash
hdl-graph query calls my_function
hdl-graph query calls run_phase
```
#### `query drivers <signal>`
Track the drivers (writes) and reads of a signal, recursively traverse containment relationships.
```bash
hdl-graph query drivers data_out
hdl-graph query drivers fifo_wr_en
```
#### `query inst <module_type>`
Find all instantiation locations of a module type in the project, display instance name, parent module, and file path.
```bash
hdl-graph query inst fifo
hdl-graph query inst apb_slave
```
#### `query explore <name>`
Explore the details of a module or class, return port, signal, instance, always block, assignment, function/task, etc.
```bash
hdl-graph explore my_module
hdl-graph explore my_class
```
#### `query impact <symbol>`
Analyze the impact scope of a modification (BFS depth 3). Track References, Drives, Calls, Instantiates, Connects, ConfigSets, ConfigGets, FactoryRegisters, FactoryOverrides, TLMBinds.
```bash
hdl-graph query impact config_reg
hdl-graph query impact my_driver
```
#### `query node <symbol>`
Get detailed information of a symbol, including: type, node ID, parent scope, source file, type-specific attributes.
```bash
hdl-graph query node my_signal
hdl-graph query node apb_if
```
### UVM Commands (`hdl-graph uvm`)
#### `uvm factory <type_name>`
Display UVM type factory registration, type override, and `type_id::create` calls.
```bash
hdl-graph uvm factory my_driver
hdl-graph uvm factory my_scoreboard
```
#### `uvm tlm <component>`
Display UVM component's TLM port connections, list port name, direction, and connection target.
```bash
hdl-graph uvm tlm my_agent
hdl-graph uvm tlm my_env
```
#### `uvm config <path>`
Display `uvm_config_db` set/get operations matching the path. Support `*` wildcard.
```bash
hdl-graph uvm config "*.driver.vif"
hdl-graph uvm config "env.agent.*"
```
#### `uvm hierarchy`
Display UVM class inheritance hierarchy (extends tree), recursively show from root class.
```bash
hdl-graph uvm hierarchy
```
### Export Commands (`hdl-graph export`)
#### `export scip <output>`
Export SCIP JSON format, compatible with Sourcegraph and GitHub Code Search.
```bash
hdl-graph export scip index.scip
```
#### `export json <output>`
Export complete graph as JSON, including all nodes, edges, files, and metadata.
```bash
hdl-graph export json graph.json
```
#### `export markdown <output> [--per-module]`
Export as readable Markdown documentation. `--per-module` option generates separate files for each module/class.
```bash
hdl-graph export markdown docs/ # Single file
hdl-graph export markdown docs/ --per-module # One file per module
```
## MCP Server
The `hdl-graph` built-in MCP (Model Context Protocol) server provides HDL code analysis capabilities for AI assistants like Claude, Cursor. The server communicates through stdio and automatically indexes all HDL files in the project during startup.
### Start
```bash
# Basic start
hdl-graph-mcp /path/to/hdl/project
# Specify extra scan directories
hdl-graph-mcp /path/to/hdl/project /path/to/includes
```
### MCP Tool List (15 tools)
# Tool List
## Symbol Query
| Tool | Parameters | Description |
|------|------------|--------------|
| `hdl_def` | `symbol: string` | Find the definition location of a symbol (module, class, port, signal, function). Returns type, name, and node ID |
| `hdl_search` | `query: string` | Search for symbols by pattern. Supports glob wildcards (`*` and `?`), case-insensitive |
| `hdl_node` | `symbol: string` | Get detailed information about a symbol: type, parent scope, source file, type-specific attributes, all outgoing and incoming edges |
| `hdl_files` | `pattern?: string` | List indexed files and node/module/class/instance/signal statistics for each file. Optional glob filtering |
## Structure Analysis
| Tool | Parameters | Description |
|------|------------|--------------|
| `hdl_hierarchy` | `name: string` | Display the instantiation hierarchy tree of modules/classes/packages/interfaces, including instances, ports, signals, and sub-blocks |
| `hdl_explore` | `name: string` | Explore module or class details: ports (including direction), signals (including type), instances (including module type), always blocks, assignments, functions/tasks |
| `hdl_inst` | `module_type: string` | Find all instantiation locations of a module type in the project, returning instance name, parent module, and file path |
## Relationship Tracking
| Tool | Parameters | Description |
|------|------------|--------------|
| `hdl_callers` | `symbol: string` | Find all callers and references of a symbol. Track References, Drives, Calls, Instantiates, Connects, etc. edges |
| `hdl_callees` | `name: string` | Display call targets of functions/tasks, listing all called functions |
| `hdl_drivers` | `signal: string` | Track drivers (writes) and reads of a signal. Recursively traverse always blocks, assignments, and modules |
| `hdl_impact` | `symbol: string` | Analyze the impact of modifying a symbol. BFS depth 3, grouping and reporting all affected nodes by level |
## UVM Analysis
| Tool | Parameters | Description |
|------|------------|--------------|
| `hdl_uvm` | `analysis: string`, `query?: string` | Comprehensive UVM analysis. `analysis` values: `factory` (factory registration/override), `tlm` (TLM port connection), `config` (config_db set/get), `hierarchy` (class inheritance hierarchy) |
## Graph Management
| Tool | Parameters | Description |
|------|------------|--------------|
| `hdl_stats` | — | Get graph statistics: node/edge counts by type (modules, signals, instances, UVM components, etc.) |
| `hdl_check` | — | Run graph consistency checks: dangling edges, unresolved module instances, isolated nodes, unresolved parent classes |
| `hdl_export` | `format: string`, `output: string` | Export code graph. `format` values: `scip` (Sourcegraph), `json` (full graph), `markdown` (documentation) |
### Client Configuration
#### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"hdl-graph": {
"command": "hdl-graph-mcp",
"args": ["/path/to/your/hdl/project"]
}
}
}
```
#### Claude Code
Create `.mcp.json` in the project root:
```json
{
"mcpServers": {
"hdl-graph": {
"command": "hdl-graph-mcp",
"args": ["."]
}
}
}
```
#### Cursor
Add MCP server in Cursor settings:
```json
{
"mcpServers": {
"hdl-graph": {
"command": "hdl-graph-mcp",
"args": ["/path/to/your/hdl/project"]
}
}
}
```
## LSP Server
hdl-graph has a built-in LSP (Language Server Protocol) server, started by the `hdl-graph watch` command, supporting editors like VS Code, Neovim, and Emacs.
### VS Code
Automatically configured after installing the `hdl-graph.vsix` extension. Or manually add in `settings.json`:
```json
{
"hdl-graph.serverPath": "hdl-graph"
}
```
### Neovim
Configure with `nvim-lspconfig`:
```lua
require('lspconfig').hdl_graph.setup {
cmd = { 'hdl-graph', 'watch' },
filetypes = { 'systemverilog', 'verilog' },
root_dir = require('lspconfig.util').find_git_ancestor,
}
```
## Architecture
```
hdl-codegraph/
├── crates/
│ ├── hdl-graph-cli ← CLI main binary (entry point)
│ ├── hdl-graph-mcp ← MCP server (AI tool integration)
│ ├── hdl-graph-core ← Core data structures (Graph trait, Node, Edge, Symbol)
│ ├── hdl-graph-grammar ← tree-sitter SystemVerilog grammar (816 grammar rules)
│ ├── hdl-graph-parse ← CST traversal and node extraction
│ ├── hdl-graph-storage ← RocksDB persistence + InMemoryGraph
│ ├── hdl-graph-query ← Query engine and SCIP/JSON/Markdown export
│ ├── hdl-graph-lsp ← LSP language server
│ ├── hdl-graph-build ← Build helper
│ ├── hdl-graph-types ← Shared type definitions
│ └── hdl-graph-web ← Web interface
├── rmcp-sdk/ ← MCP SDK (embedded dependency)
├── vscode-extension/ ← VS Code extension
├── tests/ ← Integration tests and fixtures
├── docs/ ← Documentation
├── scripts/ ← Build and packaging scripts
└── install.sh ← One-click installation script
```
### Core Dependencies
| Dependency | Version | Purpose |
|------------|---------|---------|
| `tree-sitter` | 0.25 | Incremental parser |
| `rocksdb` | 0.24 | Persistence storage |
| `rmcp` | 1.7.0 | MCP protocol (embedded rmcp-sdk) |
| `clap` | 4 | CLI argument parsing |
| `tokio` | 1 | Asynchronous runtime |
| `tower-lsp` | 0.20 | LSP protocol |
| `serde` / `serde_json` | 1 | Serialization |
| `sha2` | 0.10 | File hash (incremental indexing) |
| `notify` | 7 | File change listening |
## Development
### Build
```bash
git clone https://github.com/hedge88/hdl-codegraph.git
cd hdl-codegraph
# Build all crates
cargo build --release
# Build CLI only
cargo build --release -p hdl-graph-cli
# Build MCP server only
cargo build --release -p hdl-graph-mcp
```
### Test
```bash
# Run all tests
cargo test --workspace
# Run specific crate tests
cargo test -p hdl-graph-parse
```
### VS Code Extension Development
```bash
cd vscode-extension
npm install
npm run compile
# Press F5 to start debugging
```
## Project Status
| Phase | Progress |
|------|----------|
| Phase 1: Basic Architecture | ✅ Completed |
| Phase 2: SystemVerilog | ✅ Completed |
| Phase 3: UVM | ✅ Completed |
| Phase 4: Production Ready | 🟢 In Progress |
## Documentation
- [CHANGELOG.md](CHANGELOG.md) — Version change log
- [OFFLINE_INSTALL.md](OFFLINE_INSTALL.md) — Offline installation guide
- [docs/user-guide.md](docs/user-guide.md) — User guide
- [docs/developer-guide.md](docs/developer-guide.md) — Developer guide
- [PORTING.md](PORTING.md) — Cross-platform porting guide
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available