@hybridlabor-api/bdb-hardware-pcb 0.1.0

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/tools/visualization.py

@@ -0,0 +1,225 @@
+"""Board visualization export tools.
+
+These wrap kicad-cli's rendering and 3D/2D exporters so that MCP clients
+(and the multimodal LLMs behind them) can *see* a design:
+
+- render_pcb: 3D-rendered PNG/JPEG of the board (top/bottom/isometric views)
+- export_pcb_3d: STEP model for mechanical CAD handoff
+- export_schematic_svg: per-page schematic SVGs
+
+render_pcb returns a FastMCP Image so capable clients display the picture
+inline instead of just a path.
+"""
+
+from pathlib import Path
+
+from fastmcp.utilities.types import Image
+
+from ..server import mcp
+from ..utils.kicad_cli import run_kicad_cli
+
+_RENDER_SIDES = {"top", "bottom", "left", "right", "front", "back"}
+_RENDER_QUALITIES = {"basic", "high", "user", "job_settings"}
+
+
+@mcp.tool()
+async def render_pcb(
+    pcb_path: str,
+    side: str = "top",
+    output_path: str = "",
+    width: int = 1600,
+    height: int = 900,
+    quality: str = "basic",
+    rotate: str = "",
+) -> Image | str:
+    """Render a 3D view of the PCB to a PNG image.
+
+    Produces a photorealistic render of the assembled board via kicad-cli
+    (footprints must have 3D models assigned; otherwise plain board geometry
+    is rendered). Returns the image itself, so multimodal clients show it
+    directly — useful for AI-assisted layout review.
+
+    Args:
+        pcb_path: Path to the .kicad_pcb file.
+        side: Camera side: top, bottom, left, right, front, back.
+        output_path: Output PNG (default: <pcb>_render_<side>.png next to
+            the PCB).
+        width: Image width in pixels.
+        height: Image height in pixels.
+        quality: Render quality: basic (fast) or high (slower, raytraced).
+        rotate: Optional board rotation 'X,Y,Z' in degrees for isometric
+            views, e.g. '-30,0,25'.
+
+    Returns:
+        The rendered image, or an error message string.
+    """
+    try:
+        pcb = Path(pcb_path)
+        if not pcb.exists():
+            return f"❌ PCB file not found: {pcb_path}"
+        if side not in _RENDER_SIDES:
+            return f"❌ Invalid side '{side}'. Options: {', '.join(sorted(_RENDER_SIDES))}"
+        if quality not in _RENDER_QUALITIES:
+            return f"❌ Invalid quality '{quality}'. Options: {', '.join(sorted(_RENDER_QUALITIES))}"
+
+        out = Path(output_path) if output_path else pcb.parent / f"{pcb.stem}_render_{side}.png"
+        out.parent.mkdir(parents=True, exist_ok=True)
+
+        args = [
+            "pcb",
+            "render",
+            "--output",
+            str(out),
+            "--side",
+            side,
+            "--width",
+            str(width),
+            "--height",
+            str(height),
+            "--quality",
+            quality,
+        ]
+        if rotate:
+            args += ["--rotate", rotate]
+        args.append(str(pcb))
+
+        result = await run_kicad_cli(args, timeout=180)
+
+        if result.returncode != 0 or not out.exists():
+            stderr = (result.stderr or b"").decode("utf-8", "replace").strip()
+            return (
+                f"❌ PCB render failed (kicad-cli rc={result.returncode}):\n\n"
+                f"{stderr or '(no stderr, and no output file produced)'}"
+            )
+
+        return Image(path=str(out))
+    except FileNotFoundError:
+        return (
+            "❌ kicad-cli not found (PATH or KiCad install directory). "
+            "Rendering requires KiCad 8+."
+        )
+    except Exception as e:
+        import traceback
+
+        return f"❌ Error rendering PCB: {e}\n\n{traceback.format_exc()}"
+
+
+@mcp.tool()
+async def export_pcb_3d(
+    pcb_path: str,
+    output_path: str = "",
+    board_only: bool = False,
+) -> str:
+    """Export the PCB as a STEP 3D model for mechanical CAD handoff.
+
+    Includes board body, footprints and their assigned 3D models.
+
+    Args:
+        pcb_path: Path to the .kicad_pcb file.
+        output_path: Output .step file (default: <pcb>.step next to the PCB).
+        board_only: Export only the board body, without component models.
+
+    Returns:
+        Confirmation with the output path and file size.
+    """
+    try:
+        pcb = Path(pcb_path)
+        if not pcb.exists():
+            return f"❌ PCB file not found: {pcb_path}"
+
+        out = Path(output_path) if output_path else pcb.parent / f"{pcb.stem}.step"
+        out.parent.mkdir(parents=True, exist_ok=True)
+
+        args = ["pcb", "export", "step", "--output", str(out), "--force", str(pcb)]
+        if board_only:
+            args.insert(-1, "--board-only")
+
+        result = await run_kicad_cli(args, timeout=300)
+
+        if result.returncode != 0 or not out.exists():
+            stderr = (result.stderr or b"").decode("utf-8", "replace").strip()
+            return (
+                f"❌ STEP export failed (kicad-cli rc={result.returncode}):\n\n"
+                f"{stderr or '(no stderr, and no output file produced)'}"
+            )
+
+        size_mb = out.stat().st_size / (1024 * 1024)
+        return f"""✅ STEP 3D model exported.
+
+**PCB:** {pcb_path}
+**Output:** {out}
+**Size:** {size_mb:.1f} MB
+
+Import into Fusion 360 / SolidWorks / FreeCAD for enclosure design."""
+    except FileNotFoundError:
+        return (
+            "❌ kicad-cli not found (PATH or KiCad install directory). "
+            "STEP export requires KiCad 7+."
+        )
+    except Exception as e:
+        import traceback
+
+        return f"❌ Error exporting STEP: {e}\n\n{traceback.format_exc()}"
+
+
+@mcp.tool()
+async def export_schematic_svg(
+    schematic_path: str,
+    output_dir: str = "",
+) -> str:
+    """Export schematic pages to SVG images.
+
+    Renders every page of the (hierarchical) schematic as an SVG file via
+    kicad-cli. SVGs are vector graphics — clients and humans can zoom into
+    any detail without quality loss.
+
+    Args:
+        schematic_path: Path to the root .kicad_sch file.
+        output_dir: Output directory (default: <schematic>_svg/ next to it).
+
+    Returns:
+        Confirmation listing the generated SVG files.
+    """
+    try:
+        sch = Path(schematic_path)
+        if not sch.exists():
+            return f"❌ Schematic file not found: {schematic_path}"
+
+        out_dir = Path(output_dir) if output_dir else sch.parent / f"{sch.stem}_svg"
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        result = await run_kicad_cli(
+            ["sch", "export", "svg", "--output", str(out_dir), str(sch)],
+            timeout=120,
+        )
+
+        if result.returncode != 0:
+            stderr = (result.stderr or b"").decode("utf-8", "replace").strip()
+            return (
+                f"❌ Schematic SVG export failed (kicad-cli rc={result.returncode}):\n\n"
+                f"{stderr or '(no stderr)'}"
+            )
+
+        svgs = sorted(out_dir.glob("*.svg"))
+        if not svgs:
+            return (
+                f"⚠️ kicad-cli reported success but produced no SVG files in {out_dir}."
+            )
+
+        listing = "\n".join(f"- {s.name}" for s in svgs)
+        return f"""✅ Schematic SVG export complete.
+
+**Schematic:** {schematic_path}
+**Output directory:** {out_dir}
+
+**Files generated ({len(svgs)}):**
+{listing}"""
+    except FileNotFoundError:
+        return (
+            "❌ kicad-cli not found (PATH or KiCad install directory). "
+            "SVG export requires KiCad 7+."
+        )
+    except Exception as e:
+        import traceback
+
+        return f"❌ Error exporting schematic SVG: {e}\n\n{traceback.format_exc()}"

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility functions for KiCad MCP Server."""

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/utils/file_handlers.py

@@ -0,0 +1,65 @@
+"""File handling utilities."""
+
+from pathlib import Path
+
+
+def validate_kicad_file(file_path: str, expected_extension: str) -> Path:
+    """Validate that a file exists and has the correct extension.
+
+    Args:
+        file_path: Path to the file
+        expected_extension: Expected file extension (e.g., '.kicad_sch')
+
+    Returns:
+        Resolved Path object
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValueError: If file has wrong extension
+    """
+    path = Path(file_path).resolve()
+
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    if path.suffix.lower() != expected_extension.lower():
+        raise ValueError(
+            f"Expected {expected_extension} file, got {path.suffix}: {file_path}"
+        )
+
+    return path
+
+
+def resolve_project_path(file_path: str, search_paths: list[str] | None = None) -> Path:
+    """Resolve a file path, optionally searching project directories.
+
+    Args:
+        file_path: Relative or absolute file path
+        search_paths: List of directories to search if file_path is relative
+
+    Returns:
+        Resolved Path object
+
+    Raises:
+        FileNotFoundError: If file cannot be found
+    """
+    path = Path(file_path)
+
+    # If absolute path, just resolve it
+    if path.is_absolute():
+        if path.exists():
+            return path.resolve()
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    # If relative path, try current directory first
+    if path.exists():
+        return path.resolve()
+
+    # Search in provided paths
+    if search_paths:
+        for search_dir in search_paths:
+            search_path = Path(search_dir) / path
+            if search_path.exists():
+                return search_path.resolve()
+
+    raise FileNotFoundError(f"File not found: {file_path}")

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/utils/kicad_cli.py

@@ -0,0 +1,103 @@
+"""kicad-cli invocation helpers.
+
+Centralizes two concerns that every kicad-cli call site needs:
+
+1. Locating the executable. On Windows, KiCad's installer does NOT add its
+   bin directory to PATH, so a bare "kicad-cli" only works if the user
+   patched PATH by hand. We fall back to the detected install location
+   (``find_kicad_install``), where kicad-cli sits next to the versioned
+   ``share/kicad`` directory.
+2. Running it off the asyncio event loop. All MCP tools are ``async def``;
+   calling ``subprocess.run`` inline blocks the whole server for the duration
+   of an ERC/DRC/export (up to minutes), so callers must use the async
+   ``run_kicad_cli`` wrapper instead.
+
+The sync ``run_kicad_cli_sync`` variant exists for tests and other
+non-async contexts.
+"""
+
+import asyncio
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from .kicad_version import find_kicad_install
+
+_cached_exe: str | None = None
+
+
+def find_kicad_cli() -> str | None:
+    """Locate the kicad-cli executable.
+
+    Resolution order:
+    1. ``KICAD_CLI`` environment variable (explicit user override).
+    2. ``shutil.which("kicad-cli")`` (PATH lookup — default on Linux/macOS
+       and on Windows installs whose bin dir was added to PATH).
+    3. Known KiCad install locations via ``find_kicad_install()``.
+
+    Returns the executable path, or None when KiCad cannot be found.
+    """
+    global _cached_exe
+    if _cached_exe is not None:
+        return _cached_exe
+
+    override = os.environ.get("KICAD_CLI")
+    if override and Path(override).is_file():
+        _cached_exe = override
+        return _cached_exe
+
+    found = shutil.which("kicad-cli")
+    if found:
+        _cached_exe = found
+        return _cached_exe
+
+    install = find_kicad_install()
+    if install:
+        install_path, _version = install
+        exe_name = "kicad-cli.exe" if os.name == "nt" else "kicad-cli"
+        # Windows: <install>/bin/kicad-cli.exe
+        # macOS: install_path is .../Contents/SharedSupport, the binary is
+        #        in the sibling MacOS directory.
+        # Linux: distro packages put kicad-cli on PATH, which step 2 found.
+        candidates = [
+            install_path / "bin" / exe_name,
+            install_path.parent / "MacOS" / "kicad-cli",
+        ]
+        for candidate in candidates:
+            if candidate.is_file():
+                _cached_exe = str(candidate)
+                return _cached_exe
+
+    return None
+
+
+def run_kicad_cli_sync(
+    args: list[str],
+    timeout: float = 60.0,
+) -> subprocess.CompletedProcess:
+    """Run kicad-cli synchronously (blocking).
+
+    Raises FileNotFoundError when kicad-cli cannot be located, so callers can
+    distinguish "KiCad not installed" from a failed run.
+    """
+    exe = find_kicad_cli()
+    if exe is None:
+        raise FileNotFoundError(
+            "kicad-cli not found in PATH or known KiCad install locations. "
+            "Install KiCad 7+ or set the KICAD_CLI environment variable."
+        )
+    return subprocess.run([exe] + args, capture_output=True, timeout=timeout)
+
+
+async def run_kicad_cli(
+    args: list[str],
+    timeout: float = 60.0,
+) -> subprocess.CompletedProcess:
+    """Run kicad-cli off the event loop (non-blocking for the server).
+
+    Raises FileNotFoundError when kicad-cli cannot be located — same contract
+    as the sync variant, so existing ``except FileNotFoundError`` handlers
+    keep working.
+    """
+    return await asyncio.to_thread(run_kicad_cli_sync, args, timeout)

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/utils/kicad_version.py

@@ -0,0 +1,103 @@
+"""KiCad installation detection and version utilities."""
+
+import re
+from pathlib import Path
+
+_cached_install: tuple[Path, str] | None = None
+
+
+def _parse_version(version_str: str) -> tuple[int, ...]:
+    """Parse version string like '10.0' into tuple for sorting."""
+    try:
+        return tuple(int(x) for x in version_str.split("."))
+    except (ValueError, AttributeError):
+        return (0,)
+
+
+def find_kicad_install() -> tuple[Path, str] | None:
+    """Find the installed KiCad directory and version string.
+
+    Scans known install locations, preferring the newest version.
+
+    Returns:
+        (install_path, version_string) or None if not found
+    """
+    global _cached_install
+    if _cached_install is not None:
+        return _cached_install
+
+    # Windows: C:/Program Files/KiCad/{version}/
+    win_base = Path("C:/Program Files/KiCad")
+    if win_base.is_dir():
+        try:
+            version_dirs = sorted(
+                [d for d in win_base.iterdir() if d.is_dir()],
+                key=lambda d: _parse_version(d.name),
+                reverse=True,
+            )
+            for vd in version_dirs:
+                if (vd / "share" / "kicad").is_dir():
+                    _cached_install = (vd, vd.name)
+                    return _cached_install
+        except OSError:
+            pass
+
+    # macOS: single app bundle
+    mac_base = Path("/Applications/KiCad/KiCad.app/Contents/SharedSupport")
+    if mac_base.is_dir():
+        _cached_install = (mac_base, "macos")
+        return _cached_install
+
+    # Linux: standard paths
+    for linux_base in [
+        Path("/usr/share/kicad"),
+        Path("/usr/local/share/kicad"),
+    ]:
+        if linux_base.is_dir():
+            _cached_install = (linux_base, "linux")
+            return _cached_install
+
+    return None
+
+
+def get_kicad_symbol_dir() -> Path | None:
+    """Get the KiCad symbol library directory (.kicad_sym files)."""
+    kicad = find_kicad_install()
+    if kicad:
+        install_path, version_marker = kicad
+        # find_kicad_install() returns different path shapes per platform:
+        # Windows returns the top-level "<...>/KiCad/<version>" dir, with
+        # symbols nested under "share/kicad/symbols". Linux/macOS instead
+        # already return the "share/kicad" (or SharedSupport) directory
+        # itself, so appending "share/kicad" again pointed at a path that
+        # never exists there.
+        if version_marker in ("linux", "macos"):
+            sym_dir = install_path / "symbols"
+        else:
+            sym_dir = install_path / "share" / "kicad" / "symbols"
+        if sym_dir.is_dir():
+            return sym_dir
+    return None
+
+
+def get_pcb_version() -> str:
+    """Get the correct PCB file version string for the installed KiCad.
+
+    Reads from a template PCB file if available, falls back to '20240130'.
+    """
+    kicad = find_kicad_install()
+    if kicad:
+        install_path, _version = kicad
+        for template_name in ["Arduino_Mega", "EuroCard160mmX100mm"]:
+            template_pcb = (
+                install_path / "share" / "kicad" / "template" / template_name / f"{template_name}.kicad_pcb"
+            )
+            if template_pcb.exists():
+                try:
+                    content = template_pcb.read_text(encoding="utf-8", errors="replace")
+                    m = re.search(r"\(kicad_pcb\s+\(version\s+(\d+)\)", content)
+                    if m:
+                        return m.group(1)
+                except OSError:
+                    pass
+    return "20240130"

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/utils/parts_registry.py

@@ -0,0 +1,197 @@
+"""
+Client for an open parts registry (default: PartReel, https://partreel.com).
+
+Lets tools search a public registry of verified KiCad parts and download
+symbol/footprint/3D files without any account or API key. The registry URL is
+configurable, so any service exposing the same JSON shape works.
+
+Security posture (all enforced here, not in the tools):
+    - Asset downloads are restricted to HTTPS URLs on the registry's own host,
+      its subdomains, or hosts explicitly allowed via PARTS_REGISTRY_ASSET_HOSTS.
+    - Saved filenames are derived from the remote basename but must match the
+      extension allow-list for the requested format (prevents e.g. ``.exe``).
+    - Downloads are size-capped (MAX_ASSET_BYTES) and streamed to disk.
+    - Destination directories are validated by the caller via PathValidator.
+"""
+
+import fnmatch
+import json
+import os
+import urllib.parse
+import urllib.request
+
+DEFAULT_REGISTRY_URL = os.environ.get(
+    "PARTS_REGISTRY_URL", "https://partreel.com/api/v1"
+)
+USER_AGENT = "kicad-mcp-parts-registry"
+MAX_ASSET_BYTES = 50 * 1024 * 1024  # 50 MB cap for any single asset download
+HTTP_TIMEOUT = 30  # seconds
+
+# format name -> allowed file extensions (lowercase)
+FORMAT_EXTENSIONS = {
+    "footprint": (".kicad_mod",),
+    "symbol": (".kicad_sym",),
+    "step": (".step", ".stp"),
+    "preview": (".glb",),
+    "footprint_svg": (".svg",),
+    "symbol_svg": (".svg",),
+}
+
+
+class RegistryError(Exception):
+    """Raised for registry access or validation failures."""
+
+
+class _NoCrossHostRedirect(urllib.request.HTTPRedirectHandler):
+    """Block HTTP redirects to a different host.
+
+    ``asset_url_allowed`` only checks the URL passed in; urllib otherwise
+    silently follows 3xx to any host, letting a compromised registry point
+    asset downloads (or JSON metadata) at an attacker-controlled host.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        orig = (urllib.parse.urlparse(req.full_url).hostname or "").lower()
+        new = (urllib.parse.urlparse(newurl).hostname or "").lower()
+        if orig and new and (new == orig or new.endswith("." + orig)):
+            return super().redirect_request(req, fp, code, msg, headers, newurl)
+        raise RegistryError(f"redirect to disallowed host blocked: {newurl}")
+
+
+_DEFAULT_OPENER = urllib.request.build_opener(_NoCrossHostRedirect)
+
+
+def _fetch(url: str, opener=None) -> bytes:
+    """GET a URL with a size cap. ``opener`` is injectable for tests."""
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    open_fn = opener or _DEFAULT_OPENER.open
+    with open_fn(req, timeout=HTTP_TIMEOUT) as resp:
+        declared = resp.headers.get("Content-Length")
+        data = resp.read(MAX_ASSET_BYTES + 1)
+    # Honour Content-Length so a truncated stream (proxy/server drops the
+    # connection mid-asset) is caught, not silently written as a half-file.
+    if declared and declared.isdigit() and int(declared) > MAX_ASSET_BYTES:
+        raise RegistryError(f"asset exceeds {MAX_ASSET_BYTES} byte limit: {url}")
+    if len(data) > MAX_ASSET_BYTES:
+        raise RegistryError(f"asset exceeds {MAX_ASSET_BYTES} byte limit: {url}")
+    return data
+
+
+def registry_host(registry_url: str = DEFAULT_REGISTRY_URL) -> str:
+    """Hostname of the configured registry."""
+    return urllib.parse.urlparse(registry_url).hostname or ""
+
+
+def extra_asset_hosts() -> list[str]:
+    """Extra allowed asset hosts from PARTS_REGISTRY_ASSET_HOSTS (comma list)."""
+    raw = os.environ.get("PARTS_REGISTRY_ASSET_HOSTS", "")
+    return [h.strip().lower() for h in raw.split(",") if h.strip()]
+
+
+def asset_url_allowed(url: str, registry_url: str = DEFAULT_REGISTRY_URL) -> bool:
+    """True if ``url`` is HTTPS on the registry host, a subdomain of it, or an
+    explicitly allowed extra host."""
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme != "https" or not parsed.hostname:
+        return False
+    host = parsed.hostname.lower()
+    root = registry_host(registry_url).lower()
+    if not root:
+        return False
+    if host == root or host.endswith("." + root):
+        return True
+    return host in extra_asset_hosts()
+
+
+def filename_for_asset(url: str, part_id: str, fmt: str) -> str:
+    """Safe local filename for an asset: the remote basename when its extension
+    matches the format's allow-list, else ``<part_id>.<default ext>``."""
+    exts = FORMAT_EXTENSIONS.get(fmt)
+    if not exts:
+        raise RegistryError(f"unknown format: {fmt}")
+    remote = os.path.basename(urllib.parse.urlparse(url).path)
+    # basename() strips directories; also reject any residual traversal chars
+    if remote and ".." not in remote and remote.lower().endswith(exts):
+        return remote
+    return f"{part_id}{exts[0]}"
+
+
+# Module-level index cache keyed by registry URL. Previously the cache lived on
+# each RegistryClient instance, but the tools build a fresh client per call, so
+# the ~21k-entry index was re-downloaded on every search.
+_INDEX_CACHE: dict[str, list[dict]] = {}
+
+
+class RegistryClient:
+    """Minimal client for the registry's static JSON API.
+
+    The full parts index is fetched once and cached at module level (keyed by
+    registry URL); the tools construct a fresh client per call.
+    """
+
+    def __init__(self, registry_url: str = DEFAULT_REGISTRY_URL, opener=None):
+        self.registry_url = registry_url.rstrip("/")
+        self._opener = opener
+
+    def _get_json(self, url: str):
+        try:
+            return json.loads(_fetch(url, self._opener).decode("utf-8"))
+        except RegistryError:
+            raise
+        except Exception as exc:  # URLError, HTTPError, JSONDecodeError, ...
+            raise RegistryError(f"registry request failed: {exc}") from exc
+
+    def index(self) -> list[dict]:
+        """Full parts index (cached at module level)."""
+        if self.registry_url not in _INDEX_CACHE:
+            doc = self._get_json(f"{self.registry_url}/parts.json")
+            if isinstance(doc, list):
+                parts = doc
+            elif isinstance(doc, dict):
+                raw = doc.get("parts") or []
+                parts = raw if isinstance(raw, list) else []
+            else:
+                parts = []  # null / string / number — don't crash
+            _INDEX_CACHE[self.registry_url] = parts
+        return _INDEX_CACHE[self.registry_url]
+
+    def search(self, query: str, limit: int = 20) -> list[dict]:
+        """Case-insensitive AND-match of query tokens against id, name,
+        family, category, manufacturer and keywords. ``*`` wildcards work."""
+        tokens = [t.lower() for t in query.split() if t.strip()]
+        if not tokens:
+            return []
+        hits = []
+        for part in self.index():
+            if not isinstance(part, dict):
+                continue
+            haystack = " ".join(
+                str(part.get(k, ""))
+                for k in ("id", "name", "family", "category", "manufacturer")
+            ).lower()
+            haystack += " " + " ".join(part.get("keywords") or []).lower()
+            if all(
+                tok in haystack or fnmatch.fnmatch(haystack, f"*{tok}*")
+                for tok in tokens
+            ):
+                hits.append(part)
+                if len(hits) >= limit:
+                    break
+        return hits
+
+    def get_part(self, part_id: str) -> dict:
+        """Full record for one part (includes download URLs in ``files``)."""
+        if not part_id or not all(c.isalnum() or c in "_-" for c in part_id):
+            raise RegistryError(f"invalid part id: {part_id}")
+        return self._get_json(f"{self.registry_url}/parts/{part_id}.json")
+
+    def download_asset(self, url: str, dest_dir: str, part_id: str, fmt: str) -> str:
+        """Download one asset into ``dest_dir`` (must already be validated by
+        the caller). Returns the written file path."""
+        if not asset_url_allowed(url, self.registry_url):
+            raise RegistryError(f"asset host not allowed: {url}")
+        data = _fetch(url, self._opener)
+        path = os.path.join(dest_dir, filename_for_asset(url, part_id, fmt))
+        with open(path, "wb") as f:
+            f.write(data)
+        return path