# AI use cases for Wave MCP (Tencent/wave-mcp)

Repo: [Tencent/wave-mcp](https://github.com/Tencent/wave-mcp) | Use cases: 4 | Page: https://dedupedai.com/use-cases/tencent-wave-mcp/

wave-mcp is an open-source, license-free MCP server and CLI that lets AI agents and engineers debug RTL simulation waveforms (FST, with VCD and FSDB converted automatically) against a SystemVerilog netlist.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Find the first divergence between pass and fail waveforms: https://dedupedai.com/use-cases/tencent-wave-mcp/find-first-divergence-pass-fail-waveforms/
- Trace an X value back to its root cause: https://dedupedai.com/use-cases/tencent-wave-mcp/trace-x-value-to-root-cause/
- Review signal drivers and gating conditions before simulating: https://dedupedai.com/use-cases/tencent-wave-mcp/review-drivers-before-simulation/
- Script waveform signal checks from the terminal: https://dedupedai.com/use-cases/tencent-wave-mcp/script-waveform-checks-from-terminal/

## How to find the first divergence between pass and fail waveforms with Wave MCP

Repo: [Tencent/wave-mcp](https://github.com/Tencent/wave-mcp) | Difficulty: Advanced | Time: 1 hour | Basis: From the README

Compare a passing and a failing run, then trace the first differing signal back to its drivers.

**Who it is for:** A verification engineer whose regression case passes with one seed and fails with another and needs the failure point fast.

**The problem:** Scrolling two waveforms side by side to find where they split is slow, and it is easy to miss the signal that actually diverged first.

**The outcome:** The first divergence time, the ranked list of diverging signals, their fan-in sources, and a dual-waveform viewer opened at the divergence moment.

### Steps

1. `pip install wave-mcp`
2. `wave-session --fst sim/dump.fst --top top_tb --filelist rtl.f` (run once for the passing waveform and once for the failing one, with different --fst paths and output directories)
3. Call the `diff_waveforms` tool with the pass and fail waveforms
4. Call the `signal_fanin` tool on the first diverging signal it reports
5. `wave-view pass.fst fail.fst --labels pass fail`

### Prompt to paste into your agent

```text
Using the wave-mcp MCP server, call diff_waveforms on <pass_wave> and <fail_wave>, then call signal_fanin on the first diverging signal it reports. Return the first divergence time, the top diverging signals and their fan-in sources. Verify that the reported time matches a value change of that signal in <fail_wave>.
```

### Caveat

Driver and fan-in results depend on the pyslang netlist built from your filelist, and the browser viewer needs the separately built Surfer and surver assets described in SELF_BUILD.md.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/tencent-wave-mcp/find-first-divergence-pass-fail-waveforms/

## How to trace an X value back to its root cause with Wave MCP

Repo: [Tencent/wave-mcp](https://github.com/Tencent/wave-mcp) | Difficulty: Intermediate | Time: 45 minutes | Basis: From the README

Follow an unknown (X) value on a signal backward through its drivers to where it starts.

**Who it is for:** A designer who sees an X on an output after reset and needs to know which upstream logic introduced it.

**The problem:** Following X propagation by hand through many modules and hierarchy levels takes hours, and the source is often several modules away.

**The outcome:** A chain of driver nodes, each with its real FST value at that time, ending at the point where the X originates.

### Steps

1. `pip install wave-mcp`
2. `wave-session --fst sim/dump.fst --top top_tb --filelist rtl.f`
3. `python -m wave_mcp.server --session sessions/my_module`
4. `wave-mcp query signal_values --session sessions/my_module --paths top.u_tx.tx_serial` to confirm the X appears on the signal (inferred, check the README)
5. Call the `trace_x` tool on that signal and time, then open the result with `open_wave_view`

### Prompt to paste into your agent

```text
Using the wave-mcp MCP server, run signal_values on <signal_path> to confirm an X value, then call trace_x on that signal at <time>. Return the driver chain from the output back to the earliest node that is X, with each node's value and source location. Verify that the earliest X node has a value of X in the FST at its reported time.
```

### Caveat

Trace results are only as complete as the netlist: if the filelist, include directories or defines differ from the simulation, the driver chain can be wrong, and Wave MCP warns when the netlist and sources are out of sync.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/tencent-wave-mcp/trace-x-value-to-root-cause/

## How to review signal drivers and gating conditions before simulating with Wave MCP

Repo: [Tencent/wave-mcp](https://github.com/Tencent/wave-mcp) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Read an RTL design's drivers, fan-in and hierarchy from source alone, with no waveform yet.

**Who it is for:** An RTL reviewer or designer who wants to understand a block's logic before the testbench or a simulation run exists.

**The problem:** Reading a large RTL block by hand to find every assignment to a signal and the conditions guarding it is slow and error prone.

**The outcome:** For a chosen signal, each driver with its type, source file and line, statement snippet, source of the right-hand value, and the gating conditions that control it.

### Steps

1. `pip install wave-mcp`
2. `python examples/static_analysis/run_demo.py` to see the static analysis on the bundled UART design
3. Call the `open_static_session` tool with your top module and filelist_path, with no waveform
4. Call the `signal_drivers` tool on the signal you want to review
5. Call `signal_fanin` on the same signal to see what feeds it

### Prompt to paste into your agent

```text
Using the wave-mcp MCP server, call open_static_session with top <top_module> and filelist_path <filelist>, then call signal_drivers and signal_fanin on <signal_path>. Return every driver with its file, line and gating conditions, and list the signals that feed it. Verify that the line numbers match the source file.
```

### Caveat

Value and trace tools return a needs-waveform message in static mode, so this use case covers structure only and not runtime behavior.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/tencent-wave-mcp/review-drivers-before-simulation/

## How to script waveform signal checks from the terminal with Wave MCP

Repo: [Tencent/wave-mcp](https://github.com/Tencent/wave-mcp) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Run the same Wave MCP tools from shell scripts for CI or quick checks, without an agent.

**Who it is for:** A DV team member who wants repeatable signal checks in a CI script or a quick terminal check after each simulation.

**The problem:** Writing a custom waveform parser for each check is costly, and opening a viewer for every run does not scale.

**The outcome:** Structured JSON output from any of the 37 tools, usable in a script that fails the job when a signal value is not as expected.

### Steps

1. `pip install wave-mcp`
2. `wave-session --fst sim/dump.fst --top top_tb --filelist rtl.f`
3. `wave-mcp query --list` to see all tool names and their parameters
4. `wave-mcp query signal_values --session sessions/my_module --paths top.u_tx.tx_serial` (inferred, check the README)
5. `wave-mcp query signal_drivers --session sessions/my_module --json-args '{"paths": "top.u_tx.tx_serial"}'` (inferred, check the README)

### Prompt to paste into your agent

```text
Using the wave-mcp CLI, run `wave-mcp query signal_values --session <session_dir> --paths <signal_path> --json` and parse the JSON output. Report whether the signal ever holds the expected value <expected> in the window you specify. Verify the exit code and that the JSON contains the queried path.
```

### Caveat

The CLI runs the same tools as the MCP server, but you still need a built session directory, so the first run depends on the wave-session step succeeding with your filelist.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/tencent-wave-mcp/script-waveform-checks-from-terminal/