wave-mcp：开源、免 License 的 RTL 波形调试 MCP Server

English | 简体中文

wave-mcp 是腾讯蓬莱实验室验证团队开源的一款 RTL 波形调试 MCP Server，为 LLM 提供波形调试工具集： 读 FST 波形 + RTL 网表，提供层次探索、信号查询、驱动分析、值/X 态追踪、波形对比与浏览器波形查看器等 34 个 MCP 工具。 MIT 开源，无需任何商用 License，支持任意并发。

FST 直读，VCD / FSDB 自动转 FST：Verilator --trace-fst、Icarus 直接产 FST 就能读； 手上只有 VCD 或 FSDB 也没关系，prepare_session 自动转换后再建 session（FSDB 转换不占 Verdi license）。 它不跑仿真器，你用自己的流程跑出波形，把结果交给它即可。

为什么是 wave-mcp

芯片验证占据开发周期 50% 以上的时间，波形调试是其中最高频的动作。而 LLM 时代， 工程师希望让 AI Agent 直接读波形、查信号、追 X 态根因，但市面上的商用调试 MCP 需要昂贵的 License，且并发受限。

wave-mcp 用纯开源技术栈（pylibfst + pyslang）提供完整波形调试能力： 免 License、数据准确、真实芯片项目背书。

生产级验证

在真实生产级芯片项目（几十个模块）上完整验证，并把 OpenTitan、香山纳入测试集：

特性

• 波形查询：设计层次、实例、信号（位宽/方向/类型，含总线聚合）、信号值（点查询 / 区间，随机访问）。
• 静态分析（pyslang 网表）：连接、驱动、扇入/扇出、声明位置（文件:行号）。
• 无波形静态分析：open_static_session 只凭 RTL 源码建 session，仿真前即可分析设计结构。
• 值追踪：trace_value 沿驱动链反向遍历、可跨模块下钻，每个节点带真实 FST 值；trace_x 追 X 根因。
• 网表自愈：从 pyslang 诊断自动补 +incdir+ / 包源并重编；失败时优雅降级，其余工具不受影响。
• 一致性校验：源码或波形变了但网表没更新会报警，绝不静默给错结果。
• 波形对比：diff_waveforms 对 pass/fail 两份波形定位首个分歧时刻，按分歧时间排序信号，时钟对齐采样过滤毛刺。
• 波形查看器：open_wave_view 让 agent 分析完直接弹浏览器波形，嫌疑信号 + 游标钉在出错时刻 + 分析说明弹窗；双波形 lockstep 对比；get_view_state 反向感知用户在看什么。
• 部署友好：stdio（一人一进程，零运维）/ HTTP 多会话 / 离线自包含包（隔离网）。

系统要求

Linux x86_64 开箱即用（以上 Python 依赖均有预编译 wheel）； 其他平台仅 pylibfst 需源码编译（cmake+gcc+zlib），波形查看器暂不支持，详见 Q6。

标准环境直接 pip install wave-mcp。环境受限时按下表对号入座：

Docker 流水线默认产出 glibc 2.28 与 2.17 两档 bundle，覆盖以上全部受限场景；打包机只需 docker，目标机不需要。

快速开始

1. 安装

pip install wave-mcp

2. 跑一个示例

# 示例 A：Verilator 快启（counter 设计，产真实 FST，无需商用仿真器）
python examples/verilator_quickstart/run.py      # 需 verilator>=5

# 示例 B：静态分析（UART 设计，无需波形、无需仿真器，展示仿真前分析）
python examples/static_analysis/run.py

# 示例 C：极小内置样例（手写 VCD → vcd2fst → FST，零依赖）
python examples/make_sample.py

3. 打开你的波形

# 一条命令：波形(.fst/.vcd) + filelist → session（自动转 FST + 建网表）
wave-session --fst sim/dump.fst --top top_tb --filelist rtl.f --out sessions/my_module

# 启动 MCP Server（stdio，推荐：一人一进程）
python -m wave_mcp.server --session sessions/my_module

或者在你的 Code Agent 里直接用 MCP 工具 prepare_session，见下文集成示例。

CLI 模式

不挂 Code Agent 时，也能在终端直接调用全部 34 个工具（与 MCP 同名同参数）：

wave-mcp query --list                            # 列出全部 34 个工具

wave-mcp query signal_values --session sessions/my_module \
    --full_path top.u_tx.tx_serial              # 查询信号值变化

wave-mcp query signal_drivers --session sessions/my_module \
    --json-args '{"full_path": "top.u_tx.tx_serial"}'   # JSON 传参

• 参数按工具签名自动生成，wave-mcp query <工具名> --help 查看
• 默认输出人读文本，加 --json 输出完整结构化结果
• 适合 CI 脚本、开发调试、快速验证；每次新增工具自动获得 CLI 接口

Code Agent 集成

prepare_session 是 MCP 统一入口，Code Agent 想分析波形时第一步调它， 传入仿真产出的波形，一次完成"（转换 →）建网表 → 建 session → 打开"：

prepare_session({
  "out_dir":      "sessions/my_module",
  "wave_path":    "sim/dump.fst",          // .fst 直读 / .vcd 自动转
  "top":          "top_tb",
  "filelist_path":"rtl.f",                 // 与仿真同一份 filelist
  "mode":         "speed"                  // VCD->FST：speed/balanced/size
})
// 返回 ready 后即可调 signal_values / list_child_instances / signal_drivers ...

接入配置（stdio，各家 Agent 的 MCP 配置）：

{
  "mcpServers": {
    "wave-mcp": {
      "command": "python",
      "args": ["-m", "wave_mcp.server", "--session", "/abs/path/to/sessions/my_module"]
    }
  }
}

• Claude Code：写入 .mcp.json（claude mcp add 或手工配置）
• Cursor：写入 .cursor/mcp.json
• VS Code Copilot：写入 .vscode/mcp.json
• 其余 Agent（Gemini CLI / Qwen Code / OpenHands 等）：按各自的 mcpServers 配置填入上述 JSON 即可

无波形静态分析（仿真前即可用）

波形里有值，没有连接关系：信号这一拍是 0，波形本身回答不了它被谁驱动、驱动语句又被什么 条件门控。wave-mcp 在建 session 时就把这层关系从 RTL 源码里提出来：pyslang 完整精化 （参数、generate、interface 全展开）后持久化成一份静态设计数据库，驱动、扇入扇出、 连通、声明查询都跑在这份库上，不依赖仿真器，也不依赖任何商用工具。

open_static_session 只凭 RTL 源码建网表并打开 session，不需要任何波形、不跑仿真。 适合仿真前理解代码：查接口、查驱动/扇入扇出、浏览层次、做 code review。

open_static_session({
  "out_dir":      "sessions/my_module",
  "top":          "uart",
  "filelist_path":"rtl.f"
})
// 连接/驱动/层次/文件/声明类工具全部可用；值/追踪类工具返回明确的 "needs waveform" 提示

之后仿真产出波形时，用同一个 out_dir 调 prepare_session 升级为完整 session，已建好的网表直接复用。

每条驱动记录都带完整语境：驱动类型、源码位置、语句片段、右值来源、以及压在这条语句上的 全部门控条件（可 4 值求值的表达式树）。以示例 B 的 UART 为例：

# wave-mcp query signal_drivers --session ... --full_path uart_top.u_tx.tx_serial
drivers:
  - kind: nonblocking
    file: examples/static_analysis/uart_top.sv
    line: 91
    snippet: tx_serial <= shift_reg[0];
    rhs: uart_top.u_tx.shift_reg
    control: uart_top.u_tx.state, uart_top.u_tx.tick, ...
    guard:                          # 这条语句头上压着的全部条件
      - {cond: !rst_n, expect: 0}
      - {cond: tick, expect: 1}
      - {cond: state == DATA, expect: 1}

有了波形后，active_drivers 用 FST 值对 guard 做 4 值求值，直接告诉你某一拍是哪条驱动 语句在起作用；trace_value / trace_x 沿这张图反向遍历、跨模块下钻，每个节点带真实 波形值。静态连接关系与动态波形值在同一套工具里打通，这是纯静态设计数据库给不了的。

驱动分析与追踪是按生产级健壮性打磨的，不是 demo 功能：

• 真实项目全量验证：驱动/扇入/连通/追溯在生产级芯片项目上全量验证，并以 OpenTitan 27 个 IP + 香山 38 个 IP 按子模块层次逐一穷尽测试，覆盖功能正确性交叉校验而非仅 "返回非空"。
• 精化失败不掀桌：单个 top 精化失败（如 UVM 环境拉不到 uvm_pkg）只影响该 top， 健康 DUT 的网表照常提取；缺 +incdir+/包源时从 pyslang 诊断自愈重编；仍失败则明确 降级，值查询等其余工具不受影响，绝不静默给错结果。
• 部分网表也可用：诊断有 error 但仍提取出模块时，以 partial 标志照常服务， session_info 的 netlist_health 如实上报覆盖率，让你知道答案的可信边界。

VCD → FST 转换（vcd2fst 配置，可选）

如果你的仿真器只吐 VCD（如 Questa），建议先转 FST：体积约 VCD 的 1/50，随机访问快。 Xcelium (xrun) 用户推荐跳过 VCD，用 fstdumper 插件直接 dump FST，见 Xcelium 直出 FST 指南（含一套 Xcelium 修复补丁，见指南与仓库 third_party/fstdumper/）。 转换依赖 GTKWave 附带的 vcd2fst 工具：

# Debian/Ubuntu
sudo apt install gtkwave
# macOS
brew install gtkwave

已有 FST 则完全不需要 vcd2fst（如 Verilator --trace-fst 直接 dump FST）。 隔离网环境可用离线 bundle（自带 vcd2fst），见 docs/DEPLOY_AIRGAP.md。

三个转换入口：

# ① 独立转换（后处理）：mode=speed(fastlz,最快) / balanced(lz4) / size(zlib,最小)
wave-vcd2fst --vcd sim/dump.vcd --fst sim/dump.fst --mode speed

# ② 流式转换：把转换时间藏进仿真时间，仿真结束 FST 几乎同时就绪
wave-vcd2fst --stream --vcd sim/dump.vcd --fst sim/dump.fst
#   建 FIFO + 后台起 vcd2fst，然后 TB 里 $dumpfile("sim/dump.vcd") 指向该 FIFO 正常跑仿真

# ③ 建 session 一步到位（自动转 + 打包）
wave-session --vcd sim/dump.vcd --top top_tb --filelist rtl.f --out sessions/mod

通过 MCP 工具使用时无需手动转换：prepare_session 传入 .vcd 会自动走 ① 的转换路径。

工具（34 个，10 大类）

驱动分析与追踪类需要 pyslang 网表建成（prepare_session 时给对 filelist/incdirs/defines）。 查看器类需要安装可选资产包：pip install wave-mcp[viewer]（Surfer WASM + surver，EUPL-1.2 独立分发，核心包保持 MIT）；未安装时相关工具优雅降级返回提示，分析工具不受影响。

波形查看器（wave-view）

# 打开单个波形（几十 GB 的 FST 也是秒开：surver 服务端流式，浏览器按需取数据）
wave-view dump.fst --signals top.u_dma.req_valid --cursor 1523400ps

# 双波形对比视图（上下两个 pane，缩放/游标 lockstep 联动）
wave-view pass.fst fail.fst --labels pass fail

• 命令行打印 URL；桌面环境自动开浏览器，SSH/code agent 场景