fpgaZeroMCP

Instructions

Implementation Reference

• tools/litex.py:35-54 (handler)

  The main handler function that executes the litex_build tool logic. It accepts board, args, output_dir, and timeout parameters, creates a temporary directory, adds --build and --output-dir flags, runs the LiteX command via _run_litex helper, and returns the result with output directory.

  def litex_build(
      board: str,
      args: list[str] | None = None,
      output_dir: str | None = None,
      timeout: int = 600,
  ) -> dict:
      """Run LiteX board target with --build. Returns logs and output directory."""
      with tempfile.TemporaryDirectory() as tmpdir:
          out_dir = Path(output_dir) if output_dir else Path(tmpdir) / "build"
          out_dir.mkdir(parents=True, exist_ok=True)
  
          build_args = list(args or [])
          if "--build" not in build_args:
              build_args.append("--build")
          if "--output-dir" not in build_args:
              build_args += ["--output-dir", str(out_dir)]
  
          result = _run_litex(board, build_args, timeout)
          result["output_dir"] = str(out_dir)
          return result

• server.py:322-348 (registration)

  MCP tool registration defining the litex_build tool with its schema. Specifies the tool name, description, inputSchema properties (board, args, output_dir, timeout), and required fields.

      name="litex_build",
      description=(
          "Run LiteX board target with --build. "
          "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": 600,
                  "description": "Timeout in seconds",
              },
          },
          "required": ["board"],
      },
  ),

• server.py:494-501 (handler)

  Handler invocation code that routes litex_build tool calls. Uses asyncio.to_thread to execute the litex_build function asynchronously with arguments from the MCP request.

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

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

  Helper function _run_litex that executes the actual subprocess command. Handles subprocess execution with timeout, captures stdout/stderr, and returns success status with results or error messages.

  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 line by creating a Python module invocation for the specified board target with provided 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 [])