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

English | 简体中文

wave-mcp 是腾讯蓬莱实验室验证团队开源的一款 RTL 波形调试 MCP Server，为 LLM 提供波形调试工具集： 读 FST 波形 + RTL 网表，提供层次探索、信号查询、驱动分析、值/X 态追踪、波形对比与浏览器波形查看器等 37 个 MCP 工具。 Apache-2.0 开源，无需任何商用 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、香山纳入测试集：

维度	结果
测试规模	一百多个测试 case（生产级项目 + OpenTitan 27 个 IP + 香山 38 个 IP）
数据准确性	225 万信号级验证，值查询正确性 100%
工具调用	310 万多次调用全部通过
驱动分析	驱动 / 扇入 / 连通 / 追溯在生产级项目上全量验证
超大模块	百万级 scope 稳定完成分析
工具覆盖	37 个工具全部验证，含 viewer / diff 的单元与浏览器端到端覆盖

特性

• 波形查询：设计层次、实例、信号（位宽/方向/类型，含总线聚合）、信号值（点查询 / 区间，随机访问）。
• 静态分析（pyslang 网表）：连接、驱动、扇入/扇出、声明位置（文件:行号）。
• 无波形静态分析：open_static_session 只凭 RTL 源码建 session，仿真前即可分析设计结构。
• 值追踪：trace_value 沿驱动链反向遍历、可跨模块下钻，每个节点带真实 FST 值；trace_x 追 X 根因。
• 网表自愈：从 pyslang 诊断自动补 +incdir+ / 包源并重编；失败时优雅降级，其余工具不受影响。
• 一致性校验：源码或波形变了但网表没更新会报警，绝不静默给错结果。
• 波形对比：diff_waveforms 对 pass/fail 两份波形定位首个分歧时刻，按分歧时间排序信号，时钟对齐采样过滤毛刺。
• 波形查看器：open_wave_view 让 agent 分析完直接弹浏览器波形，嫌疑信号 + 游标钉在出错时刻 + 分析说明弹窗；双波形对比两栏同步注入；get_view_state 确认页面连通与状态送达。
• 多会话与可复现：同一设计可开多个独立 session 共享一份已加载数据；每条查询回复带 _query（有效参数）和 _fp（数据集身份/版本 + 问题摘要），两次回答是否来自同一输入同一问题一眼可辨。
• 部署友好：stdio（一人一进程，零运维）/ HTTP（本机免配置，跨机器一个 WAVE_MCP_TOKEN）/ 离线自包含包（隔离网）。

FSDB 转换器（third_party/fsdb2fst）中的部分实现参考了 TraceWeave（MIT），diff_waveforms 的功能优先级亦受其影响，详见 docs/THIRD_PARTY.md。

系统要求

依赖	版本要求	说明
Python	3.10 – 3.13	已测 3.10–3.13 全部通过；mcp SDK 要求 ≥ 3.10
glibc	≥ 2.28	pyslang 预编译 wheel 的要求（对应 Ubuntu 18.10+ / Debian 10+ / CentOS 8+）
mcp	2.x（>=2.0.0,<3）	MCP SDK v2，pip install 自动安装
pylibfst	≥ 0.2.1	FST 波形读取（fstapi，随机访问）
pyslang	≥ 11.0.0	RTL 网表构建（完整 elaboration）
vcd2fst（可选）	GTKWave	仅 VCD→FST 转换需要（apt install gtkwave / brew install gtkwave）
Verilator（示例）	≥ 5	仅 verilator_quickstart 示例需要

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

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

你的环境	方案	参考
无外网（隔离网 / 加密网）	有网机器 deploy/docker_build_all.sh 一键打离线 bundle，拷入后 install.sh 安装	DEPLOY_AIRGAP.md 第 1.0 节
Python < 3.10 或无 Python	无需升级目标机：bundle 自带独立 Python 3.11，与系统 Python 无关	DEPLOY_AIRGAP.md 第 7 节
glibc < 2.28（CentOS 7 / RHEL 7）	pip install 不可用（官方 pyslang wheel 要求 glibc ≥ 2.28）；用 glibc 2.17 档 bundle，全链路兼容老机器；或在容器（如 python:3.11-slim）中运行	DEPLOY_AIRGAP.md 第 1c 节

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

---

快速开始

1. 安装

pip install wave-mcp

2. 跑一个示例

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

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

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

... View full README on GitHub