fpgaZeroMCP

Instructions

Implementation Reference

• tools/litex.py:57-79 (handler)

  The litex_soc function that generates LiteX SoC without building gateware. It accepts board, args, output_dir, and timeout parameters, and returns a dict with success status, command info, and output directory.

  def litex_soc(
      board: str,
      args: list[str] | None = None,
      output_dir: str | None = None,
      timeout: int = 300,
  ) -> dict:
      """Generate LiteX SoC without building gateware."""
      with tempfile.TemporaryDirectory() as tmpdir:
          out_dir = Path(output_dir) if output_dir else Path(tmpdir) / "soc"
          out_dir.mkdir(parents=True, exist_ok=True)
  
          soc_args = list(args or [])
          # Ensure we don't accidentally build
          if "--build" in soc_args:
              soc_args = [a for a in soc_args if a != "--build"]
          if "--no-compile" not in soc_args:
              soc_args.append("--no-compile")
          if "--output-dir" not in soc_args:
              soc_args += ["--output-dir", str(out_dir)]
  
          result = _run_litex(board, soc_args, timeout)
          result["output_dir"] = str(out_dir)
          return result

• server.py:349-376 (schema)

  Tool registration defining the inputSchema for litex_soc with properties: board (required string), args (optional array of strings), output_dir (optional string), and timeout (optional integer with default 300).

  types.Tool(
      name="litex_soc",
      description=(
          "Generate LiteX SoC without building gateware. "
          "Returns logs and output directory."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "board": {"type": "string", "description": "LiteX board target"},
              "args": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Extra LiteX CLI args",
              },
              "output_dir": {
                  "type": "string",
                  "description": "Optional output directory",
              },
              "timeout": {
                  "type": "integer",
                  "default": 300,
                  "description": "Timeout in seconds",
              },
          },
          "required": ["board"],
      },
  ),

• server.py:502-509 (handler)

  The case handler that dispatches calls to litex_soc function using asyncio.to_thread with arguments extracted from the tool call arguments.

  case "litex_soc":
      result = await asyncio.to_thread(
          litex_soc,
          board=arguments["board"],
          args=arguments.get("args"),
          output_dir=arguments.get("output_dir"),
          timeout=arguments.get("timeout", 300),
      )

• tools/litex.py:17-32 (helper)

  Helper function _run_litex that executes the LiteX command using subprocess.run with timeout handling. Used by litex_soc to run the actual board target.

  def _run_litex(board: str, args: list[str] | None, timeout: int) -> dict:
      cmd = _build_litex_cmd(board, args)
      try:
          result = subprocess.run(
              cmd, capture_output=True, text=True, timeout=timeout
          )
          return {
              "success": result.returncode == 0,
              "cmd": cmd,
              "stdout": result.stdout,
              "stderr": result.stderr,
          }
      except FileNotFoundError:
          return {"success": False, "error": "LiteX entrypoint not found."}
      except subprocess.TimeoutExpired:
          return {"success": False, "error": f"LiteX timed out after {timeout} s."}

• tools/litex.py:11-14 (helper)

  Helper function _build_litex_cmd that constructs the LiteX command list from board name and arguments.

  def _build_litex_cmd(board: str, args: list[str] | None) -> list[str]:
      if not board:
          raise ValueError("board is required")
      return [sys.executable, "-m", f"litex_boards.targets.{board}"] + (args or [])