fpgaZeroMCP

Instructions

Implementation Reference

• registry/github.py:120-149 (handler)

  The search_repos function is the handler that implements the search_github_cores tool. It queries GitHub's API for FPGA IP repositories, filters by language and topic, and returns formatted results with repo names, stars, descriptions, licenses, and topics.

  def search_repos(
      query: str,
      language: str | None = None,
      max_results: int = 10,
  ) -> list[dict]:
      """Search GitHub for open-source FPGA IP repositories (license checked at import)."""
      q = f"{query} topic:fpga"
      if language and language in _LANGUAGE_MAP:
          q += f" language:{_LANGUAGE_MAP[language]}"
  
      try:
          data = _get(f"{GITHUB_API}/search/repositories", params={
              "q": q, "sort": "stars", "order": "desc",
              "per_page": min(max_results, 30),
          })
      except httpx.HTTPStatusError as e:
          return [{"error": f"GitHub API error {e.response.status_code}: {e.response.text}"}]
  
      results = []
      for item in data.get("items", [])[:max_results]:
          results.append({
              "repo":           item["full_name"],
              "description":    item.get("description") or "",
              "stars":          item["stargazers_count"],
              "license":        (item.get("license") or {}).get("spdx_id", "unknown"),
              "topics":         item.get("topics", []),
              "default_branch": item.get("default_branch", "main"),
              "url":            item["html_url"],
          })
      return results

• server.py:181-208 (registration)

  Registration of the search_github_cores tool with MCP. Defines the tool name, description, and inputSchema with query (required), language (optional enum), and max_results (optional integer) parameters.

  types.Tool(
      name="search_github_cores",
      description=(
          "Search GitHub for open-source MIT-licensed FPGA IP cores. "
          "Returns repo names, star counts, descriptions and topics. "
          "Use import_github_core to download a result into the local registry."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Search terms, e.g. 'uart verilog' or 'riscv softcore'",
              },
              "language": {
                  "type": "string",
                  "enum": ["verilog", "systemverilog", "vhdl"],
                  "description": "Filter by HDL language (optional)",
              },
              "max_results": {
                  "type": "integer",
                  "default": 10,
                  "description": "Maximum number of results to return",
              },
          },
          "required": ["query"],
      },
  ),

• server.py:448-455 (handler)

  Handler case statement that dispatches search_github_cores calls. Imports search_repos from registry.github and calls it asynchronously via asyncio.to_thread with the provided arguments.

  case "search_github_cores":
      from registry.github import search_repos
      result = await asyncio.to_thread(
          search_repos,
          query=arguments["query"],
          language=arguments.get("language"),
          max_results=arguments.get("max_results", 10),
      )

• registry/github.py:57-61 (helper)

  The _get helper function makes HTTP GET requests to GitHub API with proper headers, timeout, and error handling. Used by search_repos to fetch repository search results.

  def _get(url: str, params: dict | None = None) -> dict | list:
      with httpx.Client(timeout=15) as client:
          resp = client.get(url, headers=_HEADERS, params=params)
          resp.raise_for_status()
          return resp.json()

• registry/github.py:38-42 (schema)

  The _LANGUAGE_MAP dictionary maps user-friendly language names (verilog, systemverilog, vhdl) to GitHub API language filter values. Used by search_repos to construct the search query.

  _LANGUAGE_MAP = {
      "verilog":       "Verilog",
      "systemverilog": "SystemVerilog",
      "vhdl":          "VHDL",
  }