by gokeshenzhen
Provides a workflow‑oriented debug server that parses compile and simulation logs, discovers simulation artifacts, builds testbench hierarchies, and analyzes FSDB/VCD waveforms to pinpoint failure causes.
TraceWeave delivers an MCP‑compatible server that orchestrates the entire post‑simulation debugging workflow for ASIC/FPGA verification. It automatically discovers compile logs, simulation logs, and waveform files, normalizes failure events, correlates them with testbench hierarchy, and performs deep waveform queries (FSDB or VCD) to generate actionable recommendations.
mcp & pyyaml packages.
pip install mcp pyyaml --user
VERDI_HOME to an external installation.{
"command": "python3.11",
"args": ["/path/to/TraceWeave/server.py"]
}
get_sim_paths, build_tb_hierarchy, parse_sim_log, analyze_failure_event, etc.). The server maintains session state and caches intermediate results.custom_patterns.yaml.schemas.py.custom_patterns.yaml to add new regexes without code changes.| Scenario | How TraceWeave helps |
|---|---|
| Simulation failure with obscure error messages | Normalizes log entries, points to the exact time stamp, and fetches corresponding waveform snapshots. |
| Large regression suites with many cases | get_sim_paths lists available cases; session caching avoids re‑parsing unchanged logs. |
| Debugging X/Z propagation | x_trace follows the unknown value chain to the root cause. |
| Identifying structural RTL bugs | scan_structural_risks highlights potential multi‑driver or slice‑overlap issues before simulation. |
| Need to locate driver of a failing signal | explain_signal_driver returns the RTL file, line, and instance hierarchy responsible for the signal. |
Q: Do I need a Verdi license to use TraceWeave?
A: Only if you want FSDB parsing. The server works with VCD files alone; FSDB support requires the libnsys.so and libnffr.so libraries from a Verdi installation or the bundled runtime.
Q: Can I add my own error regexes?
A: Yes. Edit custom_patterns.yaml and add patterns with named capture groups (message, time, source_file, etc.). No code restart is required.
Q: How does the server handle multiple simulators?
A: get_sim_paths detects the simulator (VCS or Xcelium) from log content and sets the simulator field. Subsequent tools adapt their parsing accordingly.
Q: What if a previously parsed log changes on disk?
A: The server checks file modification times; stale cache entries are marked stale:true and will be re‑parsed on the next request.
Q: Is there a way to see what has already been computed in the current session?
A: Call get_diagnostic_snapshot; it returns a concise view of available results, stale items, and suggested next tool calls.
TraceWeave is a workflow-oriented debug server rather than a loose set of parsers. The main product shape is:
Architecture · 安装 · Client Setup · Standard MCP Workflow · 工具速查 · 单元测试 · 公众号
docs/architecture.mdAGENTS.md first, then follow its first-read file listserver.pyconfig.pysrc/analyzer.pysrc/log_parser.pysrc/fsdb_parser.pyTraceWeave/
├── config.py ← 环境变量、默认行为和发现规则常量
├── server.py ← MCP 主入口、session/workflow gate
├── custom_patterns.yaml ← 工程师自定义报错格式(不改代码,改此文件)
├── fsdb_wrapper.cpp ← FSDB native 绑定 C++ 源码
├── build_wrapper.sh ← 编译 libfsdb_wrapper.so 的脚本
├── scripts/ ← 工具脚本(如 link_verdi_runtime.sh)
├── tests/ ← 单元测试和集成测试(见下方测试文件结构)
└── src/
├── path_discovery.py ← 仿真产物路径自动发现
├── compile_log_parser.py ← 编译/elab log 解析与 simulator 识别
├── tb_hierarchy_builder.py ← testbench hierarchy 和文件分组
├── vcd_parser.py ← VCD 纯 Python 解析
├── fsdb_parser.py ← FSDB 信号值查询(libnffr.so)
├── fsdb_signal_index.py← FSDB 信号路径搜索(scope 树索引,GB 级友好)
├── log_parser.py ← failure_event 归一化、group 摘要和 run diff
├── analyzer.py ← failure_event + 波形 + hierarchy 联合分析与推荐
├── signal_driver.py ← 从波形信号路径回溯最可能的 RTL 驱动位置
├── structural_scanner.py ← 源码结构风险扫描
├── x_trace.py ← X/Z 传播链追踪
├── cycle_query.py ← 按 clock 边沿对齐的周期级信号采样
├── schemas.py ← 结构化输出契约
└── problem_hints.py ← failure symptom hints 支撑逻辑
需要 Python 3.11+。
pip install mcp pyyaml --user
如果需要 FSDB 解析,有两种运行时来源:
third_party/verdi_runtime/linux64/libnsys.so 和 libnffr.soVERDI_HOME 提供 share/FsdbReader/linux64如果两者都没有,本 MCP 仍可工作,但不支持 FSDB 解析;后续工作流应优先使用 .vcd 波形。
准备仓库本地 runtime:
export VERDI_HOME=/tools/synopsys/verdi/O-2018.09-SP2-11
bash scripts/link_verdi_runtime.sh
目录约定见 third_party/verdi_runtime/README.md。
验证 FSDB runtime 可以加载:
python3 -c "
import ctypes, os
d = 'third_party/verdi_runtime/linux64'
ctypes.CDLL(d + '/libnsys.so', ctypes.RTLD_GLOBAL)
ctypes.CDLL(d + '/libnffr.so')
print('FSDB runtime 加载 OK')
"
任何支持 stdio transport 的 MCP client 都可以接这个 server。最小接入要素是:
python3python3.11["/home/robin/Projects/mcp/TraceWeave/server.py"]third_party/verdi_runtime/linux64,则至少显式提供 VERDI_HOME。没有这两者时仅支持 VCD,不支持 FSDB。如果客户端本身支持 server instructions,它会直接拿到本仓库内置的标准调试 workflow;否则也可以按下面的 Standard MCP Workflow 手动编排工具调用。
编辑 ~/.claude.json,添加 mcpServers 段:
{
"mcpServers": {
"traceweave": {
"command": "python3.11",
"args": ["/home/robin/Projects/mcp/TraceWeave/server.py"],
"env": {
"VERDI_HOME": "/tools/synopsys/verdi/O-2018.09-SP2-11",
"VCS_HOME": "/tools/synopsys/vcs/O-2018.09-SP2-11",
"XLM_ROOT": "/tools/cadence/XCELIUM1803",
"PATH": "/tools/synopsys/verdi/O-2018.09-SP2-11/bin:/tools/synopsys/vcs/O-2018.09-SP2-11/bin:/tools/cadence/XCELIUM1803/tools/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
必须在 env 里显式写环境变量,Claude Code 不会自动 source ~/.bashrc
配置后验证:
claude mcp list
# 应显示 traceweave (connected)
编辑 ~/.codex/config.toml,添加以下配置:
[mcp_servers.traceweave]
command = "python3.11"
args = ["/home/robin/Projects/mcp/TraceWeave/server.py"]
cwd = "/home/robin/Projects/mcp/TraceWeave"
[mcp_servers.traceweave.env]
VERDI_HOME = "/tools/synopsys/verdi/O-2018.09-SP2-11"
VCS_HOME = "/tools/synopsys/vcs/O-2018.09-SP2-11"
XLM_ROOT = "/tools/cadence/XCELIUM1803"
PATH = "/tools/synopsys/verdi/O-2018.09-SP2-11/bin:/tools/synopsys/vcs/O-2018.09-SP2-11/bin:/tools/cadence/XCELIUM1803/tools/bin:/usr/local/bin:/usr/bin:/bin"
如果 ~/.codex/config.toml 已存在其他内容,只追加 mcp_servers.traceweave 这一段即可,不要覆盖已有配置。
配置后验证:
codex mcp list
# 应显示 traceweave,且 Status 为 enabled
建议再做一次功能验证:
verif/、sim log 和 wave 的工程目录启动 codexget_sim_paths、parse_sim_log、search_signals 等 MCP tool 调用,而不是只用 shell 手工读文件这是当前 MCP server 实际支持的通用调试链路,适用于 Codex、Claude Code 等支持 MCP 的客户端:
get_sim_paths(verif_root, case_name?),自动发现 compile_logs / sim_logs / wave_files / simulator
返回里还包含 discovery_mode 和可能的 case_dirphase == "elaborate" 的 compile log,并行调用 build_tb_hierarchy 和 scan_structural_risks(两者独立解析同一份 compile log,默认不应省略 scan_structural_risks;仅当用户显式要求跳过时才跳过)sim_logs 非空,用 sim_logs[0].path 和 simulator 调用 parse_sim_log
也可以显式选择同一 case 下的其他 sim log;snapshot 会按当前 session-compatible 规则判断结果是否属于当前 session
当前返回不仅有 groups,还包含版本字段、runtime-only 计数器、标准化后的 failure_events、时间归一化字段,以及 rerun diff hintsfsdb_runtime.enabled == false,优先选 .vcd;否则可用 .fsdb 或 .vcdfailure_events[0].time_ps 作为波形时间锚点failure_events[0] 或选中的 event 调用 analyze_failure_eventrecommend_failure_debug_next_stepssearch_signals + analyze_failuresparse_sim_log 返回 previous_log_detected == true,优先考虑调用 diff_sim_failure_resultsexplain_signal_driverget_diagnostic_snapshot 查看当前 session 已有哪些结果可复用、哪些步骤缺失
该 tool 只读缓存,不会触发任何子步骤get_error_context、get_signal_transitions、get_signals_around_time、get_signal_at_time、get_waveform_summary推荐的默认顺序:
get_sim_pathsbuild_tb_hierarchy + scan_structural_risks(并行,默认必做)parse_sim_logrecommend_failure_debug_next_steps 或 analyze_failure_eventsearch_signals + analyze_failuresexplain_signal_driverget_diagnostic_snapshotdiff_sim_failure_results客户端如果额外具备工程构建、RTL 读取、testcase 修改能力,可以在上面的 MCP 工作流外层再包一层自动化循环。例如:
make SV_CASE=case0Session 概览
| 工具 | 典型使用场景 |
|---|---|
get_diagnostic_snapshot |
冷启动加速器:只读聚合当前 session 缓存,返回各步骤的 available/stale 状态、精简摘要和缺失步骤的建议调用 |
路径与层级(无需波形)
| 工具 | 典型使用场景 |
|---|---|
get_sim_paths |
第一步,自动发现 compile/sim/wave 路径,或列出可用 case |
build_tb_hierarchy |
从 elaborate log 构建完整 testbench hierarchy:top module、UVM component tree、class hierarchy、interfaces |
scan_structural_risks |
对 RTL/TB 源码做 Scope 1 正则静态结构风险扫描(slice_overlap、multi_drive 等);不依赖波形 |
日志分析
| 工具 | 典型使用场景 |
|---|---|
parse_sim_log |
快速拿到 group 摘要、标准化 failure_events、时间归一化字段和 rerun hints |
diff_sim_failure_results |
比较两次仿真的已解决 / 持续 / 新增失败 |
get_error_context |
按行号从 sim log 提取前后原始上下文;配合 parse_sim_log 返回的 first_line 使用 |
失败分析
| 工具 | 典型使用场景 |
|---|---|
recommend_failure_debug_next_steps |
给出默认优先看哪个失败/信号/实例,附 role-based 排名理由 |
analyze_failures |
核心:报错 + 波形联合分析;.fsdb 可用性受 fsdb_runtime.enabled 约束 |
analyze_failure_event |
从单个 failure_event 出发,联动实例、信号和源码候选 |
驱动与溯源
| 工具 | 典型使用场景 |
|---|---|
explain_signal_driver |
从可疑波形信号回溯最可能的 RTL driver 位置和驱动类型;支持 recursive 多跳追踪 |
trace_x_source |
从出现 X/Z 的信号出发,沿驱动逻辑追踪传播链;遇到实例端口边界时停止并列出连接 |
波形查询
| 工具 | 典型使用场景 |
|---|---|
search_signals |
从 RTL 信号名找波形完整路径;.fsdb 可用性受 fsdb_runtime.enabled 约束 |
get_signal_at_time |
查特定时刻单个信号值;.fsdb 可用性受 fsdb_runtime.enabled 约束 |
get_signal_transitions |
查信号完整跳变历史;.fsdb 可用性受 fsdb_runtime.enabled 约束 |
get_signals_around_time |
查多个信号在某时刻的快照;.fsdb 可用性受 fsdb_runtime.enabled 约束 |
get_signals_by_cycle |
按时钟边沿对齐的周期级多信号采样,适合状态机和流水线逐拍对比;.fsdb 可用性受 fsdb_runtime.enabled 约束 |
get_waveform_summary |
查波形文件基本信息;.fsdb 可用性受 fsdb_runtime.enabled 约束 |
parse_sim_log 关键字段schema_version / contract_version / failure_events_schema_version:响应和 failure_events 的版本信息groups[].xprop_priority:当本次 log 存在 X/Z 症状时,标记每个 failure group 的 X/Z 传播优先级;取值为 high / normal。整体无 X/Z 时,该字段在 Python 对象里为 None,JSON 输出时通常省略parser_capabilities:当前 parser build 支持的结构化提取能力runtime_total_errors / runtime_fatal_count / runtime_error_count:runtime-only 顶层计数器parser_capabilities 当前可包含 mixed_log_detection,表示 mixed compile+runtime log 也只返回 runtime failuresfailure_events[].raw_time:log 中原始时间 tokenfailure_events[].raw_time_unit:归一化后的单位,可能是 ps/ns/us/ms/s/ticks/unknownfailure_events[].time_ps:归一化后的 ps 时间;缺失时为 nullfailure_events[].time_parse_status:exact / inferred / missingfailure_events[].log_phase:当前固定为 runtimefailure_events[].failure_source:失败来源分类,如 assertion / scoreboard / checkerfailure_events[].failure_mechanism:失败机理分类,如 protocol / mismatch / timeoutfailure_events[].transaction_hint:从 log 文本或结构化字段提取的事务提示failure_events[].expected / failure_events[].actual:优先从结构化字段,其次从 message 中提取failure_events[].missing_fields:当前 event 里相关但未成功提取的一等字段failure_events[].field_provenance:每个非空一等字段的来源,取值为 observed / derived / heuristicprevious_log_detected / candidate_previous_logs / suggested_followup_tool:rerun-aware diff hintrecommend_failure_debug_next_steps 关键新增字段recommendation_strategy:当前为 role_rank_v2_structuralfailure_window_center_ps:本次推荐所围绕的失败时间correlated_structural_risks[]:按主失败实例路径、当前 problem_hints 和风险等级重排后的静态结构风险recommended_signals[] 额外包含 role、reason_codes、confidenceget_diagnostic_snapshot 语义说明get_sim_paths 定义当前 session anchor:verif_root、case_dir、simulator、compile_logstale=true 表示缓存存在,但不属于当前 session context;不是文件 mtime 过期检测quick_ref 顶层字段只会从 stale=false 的 section 提升suggested_call 只在当前 prerequisite 已满足且参数可直接调用时提供编辑 custom_patterns.yaml,在 patterns: 下追加:
patterns:
- name: my_bus_checker
severity: ERROR
description: "自定义总线协议 checker"
regex: 'BUS_ERROR\s+\[(?P<message>[^\]]+)\]\s+src=(?P<source_file>\S+)\s+line=(?P<source_line>\d+)\s+inst=(?P<instance_path>\S+)\s+@\s+(?P<time>[\d.]+)\s*(?P<time_unit>ns|ps)'
建议至少包含命名捕获组 (?P<message>...),并尽量补充:
(?P<time>...) / (?P<time_unit>...)(?P<source_file>...) / (?P<source_line>...)(?P<instance_path>...)这些字段会直接进入标准化 failure_event,提升 analyze_failure_event 和 recommend_failure_debug_next_steps 的效果。
修改后无需重启,下次调用 parse_sim_log 时自动生效。
get_sim_paths 不再依赖硬编码的 verif/work/work_<case>/ 目录结构,而是按目录语义自动识别:
COMPILE_LOG_PATTERNS = ["*comp*.log", "*elab*.log"]
SIM_LOG_PATTERNS = ["*run*.log", "xm*.log", "sim*.log", "vcs.log"]
WAVE_PATTERNS = ["*.fsdb", "*.vcd"]
返回结果包含:
discovery_mode:root_dir / case_dir / unknowncase_dir:当前锁定的 case 目录;没有锁定时为 nullcompile_logs / sim_logs / wave_files:候选文件列表simulator:根据找到的日志自动识别 vcs 或 xceliumfsdb_runtime:当前是否支持 FSDB 解析,以及 runtime 来源available_cases:当输入是 root 目录且不传 case_name 时返回可用 case 目录hints:缺失文件、空日志、过小波形、老文件等可操作提示当前自动发现的核心规则:
verif_root 目录本身直接包含 sim log 或 waveform,则视为 case_dirverif_root 本身不含 sim/wave,但一级子目录里有,则视为 root_dirsim_logs / wave_files 始终严格绑定到一个 case,不会再混入其他 case 的文件compile_logs 允许共享编译回退:
root_dir + case_name:先 root 顶层,再目标 case 本地case_dir:先当前目录,再父目录顶层discovery_mode = "unknown" 和明确 hints最常见的返回示例:
{
"verif_root": "/path/to/verif/work",
"case_name": "case0",
"config_source": "auto",
"discovery_mode": "root_dir",
"case_dir": "/path/to/verif/work/work_case0",
"simulator": "xcelium",
"fsdb_runtime": {
"enabled": true,
"source": "verdi_home",
"lib_dir": "/tools/.../share/FsdbReader/linux64",
"missing_libs": [],
"message": "Using FSDB runtime from VERDI_HOME=/tools/..."
},
"compile_logs": [
{
"path": "/path/to/verif/work/elab.log",
"phase": "elaborate",
"size": 52340,
"mtime": "2026-03-14 10:30:00",
"age_hours": 2.5
}
],
"sim_logs": [
{
"path": "/path/to/verif/work/work_case0/irun.log",
"size": 88000,
"mtime": "2026-03-14 11:00:00",
"age_hours": 2.0
}
],
"wave_files": [
{
"path": "/path/to/verif/work/work_case0/top_tb.fsdb",
"format": "fsdb",
"size": 1200000000,
"mtime": "2026-03-14 11:00:00",
"age_hours": 2.0
}
],
"available_cases": [],
"hints": []
}
如果项目结构固定,也可以在 verif/.mcp.yaml 中显式指定模板:
compile_log: work/elab.log
case_dir: work/work_{case}
sim_log: irun.log
wave_file: top_tb.fsdb
注意:
root_dir 场景下不传 case_name 时,sim_logs / wave_files 会保持为空,客户端应先看 available_casescase_name 可以省略fsdb_runtime.enabled == false 时,.fsdb 文件虽然仍会被发现,但后续工具调用应优先选 .vcdbuild_wrapper.sh 只在重新编译 libfsdb_wrapper.so 时需要 VERDI_HOMEtests/
├── conftest.py ← pytest 路径配置,自动加载
├── test_log_parser.py ← log 解析器测试
├── test_compile_log_parser.py ← 编译/elab log 解析测试
├── test_fsdb_parser.py ← FSDB 波形解析器测试
├── test_fsdb_runtime.py ← FSDB runtime 加载测试
├── test_vcd_parser.py ← VCD 解析器测试
├── test_tb_hierarchy_builder.py ← testbench hierarchy 构建测试
├── test_path_discovery.py ← 路径发现测试
├── test_analyzer.py ← 联合分析器端到端测试
├── test_signal_driver.py ← 信号驱动回溯测试
├── test_structural_scanner.py ← 结构风险扫描测试
├── test_x_trace.py ← X/Z 传播链追踪测试
├── test_cycle_query.py ← 周期级信号采样测试
├── test_schemas.py ← 输出 schema 验证测试
├── test_problem_hints.py ← problem hints 支撑逻辑测试
├── test_server.py ← MCP server 工具注册测试
└── test_diagnostic_snapshot.py ← diagnostic snapshot 缓存测试
test_log_parser.py
run.log 则额外做集成验证,断言 UVM_ERROR 数量与 log 末尾汇总一致(否则自动跳过)test_fsdb_parser.py
top_tb.fsdb,验证 C++ wrapper 调用链路完整test_analyzer.py
# 安装 pytest(只需一次)
pip3.11 install pytest --user
# 在 TraceWeave/ 目录下运行全部测试
cd /home/robin/Projects/mcp/TraceWeave
python3.11 -m pytest tests/ -v
# 只跑某个文件
python3.11 -m pytest tests/test_log_parser.py -v
# 只跑某个测试类
python3.11 -m pytest tests/test_fsdb_parser.py::TestGetTransitions -v
修改代码
↓
python3.11 -m pytest tests/ -v
↓
全部 passed → 重启客户端 → 让客户端重新连接 MCP
↓
有 FAILED → 看报错信息 → 修复代码 → 重新跑测试
测试中写断言时注意:
| log 中的时间 | 换算结果 |
|---|---|
1661.000 ns |
1661000 ps(× 1000) |
270000 ps |
270000 ps(不变) |
270 NS(Xcelium) |
270000 ps(× 1000) |
欢迎关注我的公众号:
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.
{
"mcpServers": {
"traceweave": {
"command": "python3.11",
"args": [
"/home/robin/Projects/mcp/TraceWeave/server.py"
],
"env": {
"VERDI_HOME": "/tools/synopsys/verdi/O-2018.09-SP2-11",
"VCS_HOME": "/tools/synopsys/vcs/O-2018.09-SP2-11",
"XLM_ROOT": "/tools/cadence/XCELIUM1803",
"PATH": "/tools/synopsys/verdi/O-2018.09-SP2-11/bin:/tools/synopsys/vcs/O-2018.09-SP2-11/bin:/tools/cadence/XCELIUM1803/tools/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}claude mcp add traceweave python3.11 /home/robin/Projects/mcp/TraceWeave/server.py