Xcelium MCP Server

Instructions

Implementation Reference

• src/xcelium_mcp/server.py:308-382 (handler)

  The run_debugger_mode function, registered as an MCP tool, gathers simulation state, signal values, breakpoints, and provides a debugging checklist. It then attempts to take a screenshot and returns the report along with an optional image.

  async def run_debugger_mode() -> list:
      """Comprehensive debug snapshot: simulation state + signal values + screenshot + debugging guide.
  
      Returns a combined text report and waveform screenshot for AI-assisted hardware debugging.
      """
      bridge = _get_bridge()
      sections: list[str] = []
  
      # 1. Simulation state
      sections.append("## Simulation State")
      for label, cmd in [("Position", "where"), ("Scope", "scope")]:
          try:
              val = await bridge.execute(cmd)
              sections.append(f"- **{label}**: `{val}`")
          except TclError as e:
              sections.append(f"- **{label}**: error — {e}")
  
      # 2. Signal values in current scope (up to 50)
      sections.append("\n## Signal Values (current scope)")
      try:
          sig_list = await bridge.execute("scope -describe *")
          lines = sig_list.strip().splitlines()[:50]
          if lines:
              for line in lines:
                  # Try to get the value of each signal
                  sig_name = line.split()[0] if line.split() else ""
                  if sig_name:
                      try:
                          val = await bridge.execute(f"value {sig_name}")
                          sections.append(f"- `{sig_name}` = `{val}`")
                      except TclError:
                          sections.append(f"- `{sig_name}` = (could not read)")
          else:
              sections.append("(no signals in current scope)")
      except TclError as e:
          sections.append(f"(could not list signals: {e})")
  
      # 3. Active breakpoints
      sections.append("\n## Active Breakpoints")
      try:
          bp_list = await bridge.execute("stop -show")
          sections.append(f"```\n{bp_list}\n```")
      except TclError:
          sections.append("(no breakpoints or command not available)")
  
      # 4. Hardware debugging checklist
      sections.append(textwrap.dedent("""
      ## Hardware Debugging Checklist
      - [ ] **X/Z values**: Check for uninitialized or multi-driven signals
      - [ ] **Clock**: Verify clock is toggling at expected frequency
      - [ ] **Reset**: Confirm reset sequence completed correctly
      - [ ] **FSM state**: Check state machine is not stuck
      - [ ] **CDC**: Look for metastability on clock domain crossings
      - [ ] **Timing**: Verify setup/hold on critical paths
      - [ ] **FIFO**: Check for overflow/underflow conditions
  
      ## Suggested Next Steps
      - `get_signal_value` — read specific signals of interest
      - `find_drivers` — trace X/Z values to their source
      - `waveform_add_signals` — add signals to waveform for visual inspection
      - `sim_run` with duration — step the simulation forward
      - `set_breakpoint` — set conditional breakpoints on suspicious signals
      """))
  
      report = "\n".join(sections)
  
      # 5. Try to capture a screenshot
      try:
          ps_path = await bridge.screenshot()
          png_bytes = await ps_to_png(ps_path)
          screenshot = Image(data=png_bytes, format="png")
          return [report, screenshot]
      except Exception as e:
          report += f"\n\n*(Screenshot unavailable: {e})*"
          return [report]