fpgaZeroMCP

Instructions

Implementation Reference

• registry/resolver.py:103-120 (handler)

  The get_core method implements the tool logic. It retrieves a cached IP core by name, reads all HDL source files from the manifest, and returns a dictionary containing the manifest metadata and file contents.

  def get_core(self, name: str) -> dict:
      """Return the full manifest and HDL source for a named core."""
      if name not in self._cache:
          return {"error": f"Core '{name}' not found. Use list_ip_cores to see available cores."}
  
      manifest, core_dir = self._cache[name]
      files: dict[str, str] = {}
      for filename in manifest.files:
          path = core_dir / filename
          if path.exists():
              files[filename] = path.read_text(encoding="utf-8")
          else:
              files[filename] = f"// ERROR: file '{filename}' not found in registry"
  
      return {
          "manifest": self._manifest_dict(manifest),
          "files":    files,
      }

• server.py:170-180 (registration)

  Tool registration defining the input schema for get_ip_core tool. Accepts a required 'name' parameter (string) to specify the IP core to fetch.

  types.Tool(
      name="get_ip_core",
      description="Fetch the full manifest and HDL source files for a named IP core.",
      inputSchema={
          "type": "object",
          "properties": {
              "name": {"type": "string", "description": "Core name, e.g. 'uart_tx' or 'fifo'"},
          },
          "required": ["name"],
      },
  ),

• server.py:471-474 (handler)

  Handler case statement that routes get_ip_core tool calls to the registry.get_core method, passing the name argument asynchronously via asyncio.to_thread.

  case "get_ip_core":
      result = await asyncio.to_thread(
          registry.get_core, arguments["name"]
      )

• registry/manifest.py:23-35 (schema)

  CoreManifest Pydantic model defines the schema for IP core manifests including name, version, description, author, license, language, category, tags, parameters, ports, and files list.

  class CoreManifest(BaseModel):
      name: str
      version: str
      description: str
      author: str
      license: str
      language: Literal["verilog", "systemverilog", "vhdl"]
      category: str
      tags: list[str] = []
      parameters: dict[str, ParameterSpec] = {}
      ports: dict[str, PortSpec] = {}
      files: list[str]

• registry/resolver.py:44-77 (helper)

  CoreRegistry class initialization and internal helpers. The _load_dir method scans directories for core.json manifests and populates the _cache dictionary that get_core queries.

  class CoreRegistry:
      def __init__(self, cores_dir: Path = CORES_DIR) -> None:
          self._dir   = cores_dir          # built-in / import destination
          self._cache: dict[str, tuple[CoreManifest, Path]] = {}
          self._load_all()
  
      # ------------------------------------------------------------------
      # Internal helpers
      # ------------------------------------------------------------------
  
      def _load_dir(self, directory: Path) -> None:
          """Scan one directory for core.json manifests and add them to cache."""
          if not directory.exists():
              return
          for core_dir in sorted(directory.iterdir()):
              manifest_path = core_dir / "core.json"
              if not manifest_path.exists():
                  continue
              try:
                  manifest = CoreManifest.model_validate(
                      json.loads(manifest_path.read_text(encoding="utf-8"))
                  )
                  # Later paths override earlier ones for the same name
                  self._cache[manifest.name] = (manifest, core_dir)
              except Exception as exc:
                  LOG.warning("Could not load %s: %s", manifest_path, exc)
  
      def _load_all(self) -> None:
          self._cache.clear()
          # Built-in cores first, then extra paths (extra paths win on name clash)
          self._load_dir(self._dir)
          for extra in _extra_core_paths():
              self._load_dir(extra)