TraceWeave

🐙 TraceWeave

English · 简体中文

MCP server for simulation-failure debug through log parsing and waveform analysis

Waveform + log root-cause MCP — stop debugging by hand, use TraceWeave.

What sets TraceWeave apart: when a Verdi license is available it engages KDB/NPI for accurate cross-hierarchy driver / load / connectivity analysis; without a license it still locates issues via the built-in Static backend, log parsing, and VCD/FSDB waveform reads. It supports driver backtracking, load/fanout lookup, value-at-time queries, cycle-aligned sampling, arbitrary signal-window queries, lightweight X/Z tracing, structural risk scanning, and failure-group diffing — and emits structured next-step debug recommendations for MCP clients.

Workflow illustration; timing and speedup depend on project scale and waveform availability.

TraceWeave is a workflow-oriented debug server rather than a loose collection of parsers. It combines:

• An MCP server with session state, workflow gates, and recommended tool ordering
• Path discovery for compile logs, simulation logs, and waveform artifacts
• Compile-log-driven hierarchy building and source-aware driver correlation
• VCD and FSDB waveform backends with signal search
• Failure-centric recommendations, structural risk scanning, and X/Z propagation tracing
• Structured output schemas designed for MCP clients

[Architecture](docs/architecture.md) · [Installation](#installation) · [Client Setup](#client-setup) · [Standard MCP Workflow](#standard-mcp-workflow) · [Tool Quick Reference](#tool-quick-reference) · [Testing](#testing) · [WeChat](#wechat)

When TraceWeave helps most

TraceWeave is not a universal speedup, and it is honest about that. In blind benchmarking against a capable LLM that only reads source and text logs:

• When the RTL is readable and the bug is a source-visible logic error, an

LLM reading the source is already fast. Here TraceWeave mainly confirms the hypothesis from the waveform — and scan_structural_risks can statically pin the offending line. Useful, but not where the moat is.

• **TraceWeave becomes the decisive — sometimes the only — way to localize when

the answer is not in readable source:**

• the design is encrypted/protected IP or too large to eyeball, so the bug

cannot be read or grep'd; or

• the failure is a **timing / handshake / X / connectivity bug with no static

signature and an opaque symptom** (timeout, stall, divergence — no value pattern in the log).

In those cases the clock-sampled waveform facts — cycle-aligned sampling, inspect_handshake, suggest_protocol_bundles, sweep_handshakes, reconstruct_transactions, verify_window, diff_first_divergence, period, trace_x_source, structural scanning — localize the failing stage and time directly, where reading source or grepping cannot reach. Reading the source is a strong baseline; TraceWeave earns its keep on opaque symptoms and unreadable or large designs.

Architecture

• Architecture map: docs/architecture.md
• New-session bootstrap: read AGENTS.md first, then follow its first-read file list
• Fast path for code understanding:
• server.py
• config.py
• src/analyzer.py
• src/log_parser.py
• src/fsdb_parser.py

Repository Layout

TraceWeave/
├── config.py                 # Environment-sensitive constants and discovery rules
├── server.py                 # MCP entry point, session state, and workflow gating
├── custom_patterns.yaml      # User-extensible log patterns
├── fsdb_wrapper.cpp          # Native FSDB wrapper source
├── build_wrapper.sh          # Builds libfsdb_wrapper.so
├── scripts/                  # setup_fsdb.sh / verify_fsdb.sh
├── tests/                    # Unit and integration tests
└── src/
    ├── path_discovery.py
    ├── compile_log_parser.py
    ├── tb_hierarchy_builder.py
    ├── vcd_parser.py
    ├── fsdb_parser.py
    ├── fsdb_signal_index.py
    ├── waveform_batch.py         # FSDB+VCD time-window batch reader
    ├── log_parser.py
    ├── analyzer.py
    ├── signal_driver.py
    ├── signal_load.py            # Load/fanout finder, Static + NPI
    ├── connectivity_backend.py   # ConnectivityBackend protocol + select_backend
    ├── verdi_backend.py          # KDB / license probe + kdb_hint generator
    ├── verdi_npi_backend.py      # NPI-backed driver/load resolution
    ├── kdb_builder.py            # Auto-build Verdi KDB (vericom + elabcom) for Xcelium flows
    ├── structural_scanner.py
    ├── x_trace.py
    ├── cycle_query.py
    ├── schemas.py
    ├── problem_hints.py
    ├── hierarchy_handles.py      # HandleStore + content-addressed handle for build_tb_hierarchy
    ├── handle_tools.py           # get_tb_subtree / lookup_tb_files / find_tb_instance / ...
    ├── cursor_store.py           # Named, process-scoped time anchors (cursor_set/list/delete)
    ├── timespec.py               # Resolve @cursor / unit literals (12.34ns) to ps on time inputs
    ├── verify_condition.py       # diff_first_divergence, period, inspect_handshake
    ├── window_verify.py          # verify_window: temporal predicate over a clock window
    ├── handshake_suggest.py      # suggest_handshakes / suggest_protocol_bundles
    ├── handshake_sweep.py        # sweep_handshakes: whole-design handshake anomaly sweep
    ├── txn_reconstruct.py        # reconstruct_transactions: id-correlated transaction layer
    └── usage_telemetry.py        # Local-only per-call usage telemetry (opt-out)

Installation

TraceWeave requires Python 3.11+.

pip install mcp pyyaml --user

For FSDB support, one of these runtime sources must be available:

• Repo-local runtime: third_party/verdi_runtime/linux64/libnsys.so and libnffr.so
• External Verdi installation exposed via VERDI_HOME/share/FsdbReader/linux64

If neither is available, TraceWeave still works, but FSDB parsing is disabled and the workflow should prefer .vcd waveforms.

Enable FSDB support (links the Verdi runtime into the repo and builds libfsdb_wrapper.so in one step):

# Example only — replace with your site's Verdi install path
export VERDI_HOME=/tools/synopsys/verdi/O-2018.09-SP2-11
bash scripts/setup_fsdb.sh

Verify the runtime and wrapper load correctly. This script does not require $VERDI_HOME and is safe to run on any host that already has the repo-local artefacts:

bash scripts/verify_fsdb.sh

Client Setup

Generic MCP Client

Any MCP client that supports stdio transport can connect to this server. The minimum configuration is:

• command: python3.11
• args: ["/home/robin/Projects/mcp/TraceWeave/server.py"]
• env: provide either repo-local third_party/verdi_runtime/linux64 or VERDI_HOME if FSDB support is required

If the client supports server instructions, it can follow the built-in workflow directly. Otherwise, use the workflow below.

Claude Code

Neither Claude Code nor Codex inherits your interactive shell env into the spawned MCP stdio server, so list every variable the server needs — tool roots plus the dlopen chain (LD_LIBRARY_PATH is the one most often missed; without it NPI silently falls back to Static and trace_signal_path returns found: false).

Add this to ~/.claude.json:

{
  "mcpServers": {
    "TraceWeave": {
      "command": "python3.11",
      "args": ["/home/robin/Projects/mcp/TraceWeave/server.py"],
      "env": {
        "VERDI_HOME": "/tools/synopsys/verdi/V-2023.12-SP2",
        "NOVAS_HOME": "/tools/synopsys/verdi/V-2023.12-SP2",
        "VCS_HOME": "/tools/synopsys/vcs/V-2023.12-SP2",
        "XLM_ROOT": "/tools/cadence/XCELIUM2603",
        "CDS_INST_DIR": "/tools/cadence/XCELIUM2603",
        "SNPSLMD_LICENSE_FILE": "27000@synopsys-license.example.com",
        "LM_LICENSE_FILE": "5280@license-server.example.com",
        "CDS_LICENSE_FILE": "5280@cadence-license.example.com",
        "LD_LIBRARY_PATH": "/tools/synopsys/verdi/V-2023.12-SP2/share/PLI/IUS/LINUX64:/tools/synopsys/verdi/V-2023.12-SP2/share/PLI/VCS/LINUX64",
        "PATH": "/tools/synopsys/verdi/V-2023.12-SP2/bin:/tools/synopsys/vcs/V-2023.12-SP2/bin:/tools/synopsys/vcs/V-2023.12-SP2/amd64/bin:/tools/cadence/XCELIUM2603/tools/bin/64bit:/tools/cadence/XCELIUM2603/tools/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
      }
    }
  }
}

Verify the connection:

claude mcp list
# Should show TraceWeave (connected)

Codex

Same idea as Claude Code — list everything explicitly. Add to ~/.codex/config.toml:

[mcp_servers.TraceWeave]
command = "python3.11"
args = ["/home/robin/Projects/mcp/TraceWeave/server.py"]
cwd = "/home/robin/Projects/mcp/TraceWeave"
env = {
  VERDI_HOME      = "/tools/synopsys/verdi/V-2023.12-SP2",
  NOVAS_HOME      = "/tools/synopsys/verdi/V-2023.12-SP2",
  VCS_HOME        = "/tools/synopsys/vcs/V-2023.12-SP2",
  XLM_ROOT        = "/tools/cadence/XCELIUM2603",
  CDS_INST_DIR    = "/tools/cadence/XCELIUM2603",
  SNPSLMD_LICENSE_FILE = "27000@synopsys-license.example.com",
  LM_LICENSE_FILE     = "28000@license-server.example.com",
  CDS_LICENSE_FILE    = "28000@cadence-license.example.com",
  LD_LIBRARY_PATH = "/tools/synopsys/verdi/V-2023.12-SP2/share/PLI/IUS/LINUX64:/tools/synopsys/verdi/V-2023.12-SP2/share/PLI/VCS/LINUX64",
  PATH            = "/tools/synopsys/verdi/V-2023.12-SP2/bin:/tools/synopsys/vcs/V-2023.12-SP2/bin:/tools/synopsys/vcs/V-2023.12-SP2/amd64/bin:/tools/cadence/XCELIUM2603/tools/bin/64bit:/tools/cadence/XCELIUM2603/tools/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
}

Verify the connection:

codex mcp list
# Should show TraceWeave with Status: enabled

Functional Verification

After connecting either client, run a quick end-to-end smoke test:

1. Start codex or claude inside a project directory that contains a sim log and waveform files.
2. Submit a direct waveform-debug request, for example: "Call the TraceWeave MCP. Start with get_sim_paths to list the logs and waves for this case."
3. Confirm that the execution log shows actual MCP tool calls such as get_sim_paths, parse_sim_log, and search_signals — not just shell commands reading files manually.

Standard MCP Workflow

This is the default workflow for simulation-log and waveform debug:

1. Call get_sim_paths(verif_root, case_name?). For non-standard layouts you may also pass explicit sim_log / wave_file / compile_log paths; any field you supply is used as-is and the omitted ones are still auto-discovered (a sim_log path also anchors discovery of the matching waveform and compile/elab logs). An explicit path may be absolute or relative — a relative path is resolved against verif_root and each of its ancestors (so a path relative to the repo root also works), and if still not found it is recovered by basename.
2. Choose the phase == "elaborate" compile log.
3. Run build_tb_hierarchy and scan_structural_risks in parallel on that same compile log.
4. If a sim log is present, call parse_sim_log; then, on a failing run with a waveform, call sweep_handshakes for a one-call whole-design protocol-health scan (a default-flow step, like scan_structural_risks at the runtime layer).
5. Use recommend_failure_debug_next_steps or analyze_failure_event.
6. Use search_signals and analyze_failures when you need waveform snapshots for explicit signals.
7. Use explain_signal_driver, trace_x_source, or get_signals_by_cycle for deeper investigation.
8. Use get_diagnostic_snapshot at any time to inspect reusable cached session state.

Important workflow rules:

• scan_structural_risks is part of the default workflow and should not be skipped unless the user explicitly asks to skip it.
• Use the same compile_log for both build_tb_hierarchy and scan_structural_risks.
• Prefer failure_events[].time_ps from parse_sim_log as the waveform time anchor.
• If fsdb_runtime.enabled == false, prefer .vcd over .fsdb.

Tool Quick Reference

Session Overview

• get_diagnostic_snapshot: Read-only summary of cached session data and suggested next calls; mirrors parse_sim_log's protocol_symptom_hint so a scoreboard failure surfaces the protocol-health pointer at session start

Paths and Hierarchy

• get_sim_paths: Discover compile logs, sim logs, waveforms, simulator, and cases. Optional explicit sim_log / wave_file / compile_log overrides win over auto-discovery; omitted fields are still discovered (anchored at the sim_log/wave_file directory)
• build_tb_hierarchy: Build testbench hierarchy server-side; return a slim payload (project, stats, depth-2 tree skeleton, interfaces, ambiguous_basenames, hierarchy_handle). Full data is reachable via the handle tools below.
• scan_structural_risks: Scan compiled RTL/TB sources for structural risk patterns

Hierarchy Handle Tools

All take the hierarchy_handle returned by build_tb_hierarchy. On a stale or unknown handle they return {"error": "handle_expired"}; re-run build_tb_hierarchy to refresh.

• get_tb_subtree(handle, root="", depth=1, max_nodes=500): Slice the component_tree starting at a dotted instance path.
• lookup_tb_files(handle, ...): Query the compiled file set by objective scan facts (basename, name_contains, path_contains, has_module, contains_uvm, file_type). At least one filter is required. Use basename=... to disambiguate multi-version files reported in ambiguous_basenames.
• find_tb_instance(handle, path=... | module=...): Locate an instance by exact path or all instances of a module.
• get_tb_file_detail(handle, path): Return symbols defined in a single compiled file. Unknown paths return file_not_in_compile_set with basename-similar did_you_mean suggestions — verify file membership before any RTL read.
• get_tb_class_hierarchy(handle, root_class?, depth=-1): UVM/SV class inheritance tree built from compile-set scans.
• dump_tb_section(handle, section): Escape hatch for the full raw compile_result, include_tree, filelist_tree, interfaces, files_full, component_tree_full, or class_hierarchy_full. Prefer the targeted tools above.

Log Analysis

• parse_sim_log: Parse and normalize runtime failures into grouped summaries and failure_events; also returns log_snapshot_id so same-path reruns can be compared after the simulator overwrites the log. On a scoreboard/compare-style failure it sets protocol_symptom_hint, a boundary-safe pointer reminding you to check bus-protocol health (run sweep_handshakes once for all interfaces) before reading RTL line-by-line — it never asserts a protocol type or a specific signal.
• diff_sim_failure_results: Compare two simulation runs by paths or by base_snapshot_id / new_snapshot_id. If only new_log_path is supplied after an earlier parse_sim_log of the same path, TraceWeave uses the previous parsed snapshot as the baseline.
• get_error_context: Extract raw log context around a specific line

Waveform Analysis

• search_signals: Resolve full hierarchical signal paths. Each result also carries direction (input/output/inout/implicit/null) and var_type (wire/reg/integer/real/parameter/…), so clients can filter ports/nets/variables in a chosen scope without a separate tool. FSDB populates both fields; VCD populates only var_type and returns direction: null (the VCD format does not encode port direction)
• get_signal_at_time: Query a signal value at a specific timestamp
• get_signal_transitions: Retrieve transitions for a signal over time
• get_signals_around_time: Retrieve context around a failure timestamp. Flags a value_at_center that is a sub-cycle transient (a combinational glitch at the clock edge that settles back within the same cycle — e.g. an interconnect mux re-settling to idle for ~1ns) via transient_note + per-signal `center_transien

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gokeshenzhen
• Source: gokeshenzhen/TraceWeave
• License: MIT

Install and usage instructions live in the source repository linked above.