🐙 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:

• 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 · Installation · Client Setup · Standard MCP Workflow · Tool Quick Reference · Testing · WeChat

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/                  # 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

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.

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')
"

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_ru

... View full README on GitHub