fpgaZeroMCP

Instructions

Implementation Reference

• tools/lsp.py:61-80 (handler)

  Main handler function for format_hdl tool. Takes HDL code and language (verilog/systemverilog/vhdl), writes to a temp file, and delegates to language-specific formatter (_verible_format for Verilog/SV, _vsg_format for VHDL). Returns dict with success status, formatted code, and change indicator.

  def format_hdl(code: str, language: str = "verilog") -> dict:
      """Return formatted HDL code.
  
      Verilog/SV: verible-verilog-format
      VHDL:       vsg  (pip install vsg)
      """
      suffix = HDL_SUFFIX.get(language, ".v")
  
      with tempfile.NamedTemporaryFile(
          suffix=suffix, mode="w", encoding="utf-8", delete=False
      ) as f:
          f.write(code)
          tmpfile = f.name
  
      try:
          if language == "vhdl":
              return _vsg_format(tmpfile, code)
          return _verible_format(tmpfile, code)
      finally:
          os.unlink(tmpfile)

• server.py:299-320 (schema)

  Tool registration schema defining format_hdl with input parameters: 'code' (required string) for HDL source code and 'language' (optional enum: verilog/systemverilog/vhdl, default verilog). Includes description of tool behavior and supported backends.

  types.Tool(
      name="format_hdl",
      description=(
          "Format HDL source code and return the result. "
          "Verilog/SystemVerilog: uses verible-verilog-format. "
          "VHDL: uses vsg (pip install vsg). "
          "Returns the formatted code and whether it changed."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "code": {"type": "string", "description": "HDL source code to format"},
              "language": {
                  "type": "string",
                  "enum": ["verilog", "systemverilog", "vhdl"],
                  "default": "verilog",
                  "description": "HDL language variant",
              },
          },
          "required": ["code"],
      },
  ),

• server.py:488-493 (registration)

  Handler invocation for format_hdl tool. Dispatches to format_hdl function via asyncio.to_thread, passing code and language arguments extracted from the tool call.

  case "format_hdl":
      result = await asyncio.to_thread(
          format_hdl,
          code=arguments["code"],
          language=arguments.get("language", "verilog"),
      )

• tools/lsp.py:174-196 (helper)

  Helper function _verible_format: Executes verible-verilog-format subprocess on temp file for Verilog/SystemVerilog formatting. Returns formatted code, success status, and whether changes were made.

  def _verible_format(tmpfile: str, original: str) -> dict:
      try:
          r = subprocess.run(
              ["verible-verilog-format", tmpfile],
              capture_output=True, text=True, timeout=30,
          )
          if r.returncode == 0:
              return {
                  "success":   True,
                  "tool":      "verible-verilog-format",
                  "formatted": r.stdout,
                  "changed":   r.stdout.strip() != original.strip(),
              }
          return {
              "success":   False,
              "tool":      "verible-verilog-format",
              "stderr":    r.stderr,
              "formatted": original,
          }
      except FileNotFoundError:
          return {"error": "'verible-verilog-format' not found. Install OSS CAD Suite."}
      except subprocess.TimeoutExpired:
          return {"error": "verible-verilog-format timed out after 30 s."}

• tools/lsp.py:245-262 (helper)

  Helper function _vsg_format: Executes vsg (VHDL Style Guide) with --fix flag for VHDL formatting. Reads modified temp file and returns formatted code, success status, and change indicator.

  def _vsg_format(tmpfile: str, original: str) -> dict:
      try:
          # vsg --fix edits the file in place
          r = subprocess.run(
              ["vsg", "--fix", "-f", tmpfile],
              capture_output=True, text=True, timeout=30,
          )
          formatted = Path(tmpfile).read_text(encoding="utf-8")
          return {
              "success":   r.returncode in (0, 1),  # 1 = fixes were applied
              "tool":      "vsg",
              "formatted": formatted,
              "changed":   formatted.strip() != original.strip(),
          }
      except FileNotFoundError:
          return {"error": "'vsg' not found. Install with: pip install vsg"}
      except subprocess.TimeoutExpired:
          return {"error": "vsg timed out after 30 s."}