fpgaZeroMCP

Instructions

Implementation Reference

• tools/lsp.py:35-58 (handler)

  Main handler function that executes get_diagnostics tool logic. Takes HDL code and language as input, creates a temp file, and routes to appropriate diagnostic backend (Verilator/Verible for Verilog/SV, GHDL for VHDL).

  def get_diagnostics(code: str, language: str = "verilog") -> dict:
      """Return structured diagnostics (line, col, severity, message) for HDL code.
  
      Verilog/SV: tries Verilator first, falls back to verible-verilog-lint.
      VHDL:       uses GHDL.
      """
      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 _ghdl_diagnostics(tmpfile)
          result = _verilator_diagnostics(tmpfile, language)
          if "error" in result:
              # Verilator missing — try Verible
              return _verible_lint(tmpfile)
          return result
      finally:
          os.unlink(tmpfile)

• server.py:277-298 (registration)

  Tool registration defining get_diagnostics with MCP types.Tool. Specifies tool name, description, and inputSchema with 'code' (required) and 'language' (optional, enum: verilog/systemverilog/vhdl).

  types.Tool(
      name="get_diagnostics",
      description=(
          "Return structured lint diagnostics (line, column, severity, message) for HDL source. "
          "Verilog/SystemVerilog: uses Verilator (primary) with verible-verilog-lint as fallback. "
          "VHDL: uses GHDL. "
          "All tools are part of OSS CAD Suite."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "code": {"type": "string", "description": "HDL source code"},
              "language": {
                  "type": "string",
                  "enum": ["verilog", "systemverilog", "vhdl"],
                  "default": "verilog",
                  "description": "HDL language variant",
              },
          },
          "required": ["code"],
      },
  ),

• server.py:482-487 (handler)

  Request routing/handler dispatch that calls get_diagnostics function asynchronously via asyncio.to_thread with code and language arguments from the tool request.

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

• tools/lsp.py:87-103 (helper)

  Helper function _verilator_diagnostics that executes Verilator lint tool for Verilog/SystemVerilog diagnostics with 30s timeout.

  def _verilator_diagnostics(tmpfile: str, language: str) -> dict:
      flags = ["-g2012"] if language == "systemverilog" else []
      try:
          r = subprocess.run(
              ["verilator", "--lint-only", "--error-limit", "50"] + flags + [tmpfile],
              capture_output=True, text=True, timeout=30,
          )
          diags = _parse_verilator(r.stdout + r.stderr, tmpfile)
          return {
              "success":     r.returncode == 0,
              "tool":        "verilator",
              "diagnostics": diags,
          }
      except FileNotFoundError:
          return {"error": "'verilator' not found"}
      except subprocess.TimeoutExpired:
          return {"error": "Verilator timed out after 30 s."}

• tools/lsp.py:131-151 (helper)

  Helper function _verible_lint that provides fallback diagnostic backend using verible-verilog-lint when Verilator is unavailable.

  def _verible_lint(tmpfile: str) -> dict:
      try:
          r = subprocess.run(
              ["verible-verilog-lint", tmpfile],
              capture_output=True, text=True, timeout=30,
          )
          diags = _parse_verible(r.stdout + r.stderr, tmpfile)
          return {
              "success":     r.returncode == 0,
              "tool":        "verible-verilog-lint",
              "diagnostics": diags,
          }
      except FileNotFoundError:
          return {
              "error": (
                  "'verilator' and 'verible-verilog-lint' not found. "
                  "Install OSS CAD Suite."
              )
          }
      except subprocess.TimeoutExpired:
          return {"error": "verible-verilog-lint timed out after 30 s."}