🐙 TraceWeave

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

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

Architecture · Installation · Client Setup · Standard MCP Workflow · Tool Quick Reference · Testing · WeChat

• 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

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/                  # Utility scripts such as link_verdi_runtime.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
    ├── log_parser.py
    ├── analyzer.py
    ├── signal_driver.py
    ├── structural_scanner.py
    ├── x_trace.py
    ├── cycle_query.py
    ├── schemas.py
    └── problem_hints.py

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.

Prepare the repo-local runtime:

export VERDI_HOME=/tools/synopsys/verdi/O-2018.09-SP2-11
bash scripts/link_verdi_runtime.sh

Verify the runtime can be loaded:

python3 -c "
import ctypes
d = 'third_party/verdi_runtime/linux64'
ctypes.CDLL(d + '/libnsys.so', ctypes.RTLD_GLOBAL)
ctypes.CDLL(d + '/libnffr.so')
print('FSDB runtime load OK')
"

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.

Add this to ~/.claude.json:

{
  "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"
      }
    }
  }
}

Environment variables must be set explicitly in the config. Claude Code does not automatically source your shell profile.

Verify the connection:

claude mcp list
# Should show TraceWeave (connected)

Add this to ~/.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"

If the file already contains other configuration, append this block instead of overwriting it.

Verify the connection:

codex mcp list
# Should show TraceWeave with Status: enabled

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.

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

1. Call get_sim_paths(verif_root, case_name?).
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.
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.

• get_diagnostic_snapshot: Read-only summary of cached session data and suggested next calls

• get_sim_paths: Discover compile logs, sim logs, waveforms, simulator, and cases
• build_tb_hierarchy: Build testbench hierarchy, source grouping, and interface metadata
• scan_structural_risks: Scan compiled RTL/TB sources for structural risk patterns

• parse_sim_log: Parse and normalize runtime failures into grouped summaries and failure_events
• diff_sim_failure_results: Compare two simulation runs
• get_error_context: Extract raw log context around a specific line

• search_signals: Resolve full hierarchical signal paths
• 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
• get_signals_by_cycle: Sample signals cycle-by-cycle on a clock edge
• get_waveform_summary: Return waveform metadata

• analyze_failures: Focus on one grouped failure and return log plus waveform context
• analyze_failure_event: Rank likely instances, source files, and signals for a specific failure_event
• recommend_failure_debug_next_steps: Return the default next debug target
• explain_signal_driver: Trace a waveform signal back to likely RTL driver logic
• trace_x_source: Trace X/Z propagation upstream

Run the full test suite from the repo root:

python3.11 -m pytest

Run a single file:

python3.11 -m pytest tests/test_server.py

Run a single test:

python3.11 -m pytest tests/test_server.py -k diagnostic_snapshot

Recommended change flow:

1. Make the code change.
2. Run the relevant tests first.
3. Run the full suite if the change affects shared behavior.
4. Restart the MCP client so it reconnects to the updated server.

Follow the WeChat public account: