@hybridlabor-api/bdb-hardware-pcb 0.1.0

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

@@ -0,0 +1,211 @@
+"""Hierarchical schematic analysis tools for KiCad MCP Server."""
+
+from pathlib import Path
+
+from ..parsers.netlist_parser import NetlistParser
+from ..parsers.schematic_parser import SchematicParser
+from ..server import mcp
+
+
+def _find_component_location(file_path: str, reference: str, sheets: list[dict]) -> tuple[object | None, str]:
+    """Find a component across the main sheet and sub-sheets.
+
+    Returns (component_or_None, sheet_name).
+    """
+    parser = SchematicParser(file_path)
+    for component in parser.get_components():
+        if component.reference == reference:
+            return component, "Main Schematic"
+
+    project_dir = Path(file_path).parent
+    for sheet in sheets:
+        sheet_path = project_dir / sheet.get("file", "")
+        if sheet_path.exists():
+            try:
+                for component in SchematicParser(str(sheet_path)).get_components():
+                    if component.reference == reference:
+                        return component, sheet.get("name", sheet.get("file", ""))
+            except Exception:
+                continue
+    return None, ""
+
+
+@mcp.tool()
+async def trace_hierarchical_connection(
+    file_path: str,
+    reference: str,
+    pin_number: str = ""
+) -> str:
+    """Trace component connections across hierarchical schematics.
+
+    This tool traces connections through the entire schematic hierarchy,
+    including sub-sheets, to show complete signal paths.
+
+    Args:
+        file_path: Path to main .kicad_sch file
+        reference: Component reference designator (e.g., 'U1', 'R5')
+        pin_number: Optional pin number to trace (if empty, trace all pins)
+
+    Returns:
+        Complete connection trace through hierarchy
+    """
+    try:
+        from .pin_analysis import _ensure_netlist
+
+        parser = SchematicParser(file_path)
+        sheets = parser.get_sheets()
+
+        # Search the main sheet AND sub-sheets (previously only the root was
+        # searched, so any component placed in a sub-sheet was "Not Found").
+        target_component, location = _find_component_location(file_path, reference, sheets)
+
+        if not target_component:
+            refs = [c.reference for c in parser.get_components()][:10]
+            return f"# Component Not Found\n\nComponent '{reference}' not found in schematic hierarchy.\n\nAvailable components: {', '.join(refs)}..."
+
+        lines = [
+            f"# Connection Trace for {target_component.reference}",
+            "",
+            f"**Component:** {target_component.reference}",
+            f"**Value:** {target_component.value}",
+            f"**Location:** {location}",
+            f"**File:** {file_path}",
+            "",
+        ]
+
+        # The authoritative pin<->net map lives in the netlist. SchematicParser
+        # nets carry no pin list (SchematicNet.pins is always empty), so tracing
+        # via them always reported "no connections".
+        netlist_path = await _ensure_netlist(Path(file_path))
+        if netlist_path is None:
+            lines.append("⚠️ No netlist available — cannot resolve connections. Run `generate_netlist()` first.")
+            return "\n".join(lines)
+
+        nl = NetlistParser(str(netlist_path))
+        comp = nl.get_components().get(reference)
+        if not comp or not comp.pins:
+            lines.append("No connections found for this component.")
+            return "\n".join(lines)
+
+        pins_to_trace = [pin_number] if pin_number else list(comp.pins.keys())
+        for pn in pins_to_trace:
+            conn = nl.trace_connection(reference, str(pn))
+            net_name = conn.get("net") if isinstance(conn, dict) else None
+            connected = conn.get("connected_to", []) if isinstance(conn, dict) else []
+            lines.append(f"## Pin {pn}")
+            lines.append(f"**Net:** {net_name or '(unconnected)'}")
+            if connected:
+                lines.append(f"**Connected to ({len(connected)} pins):**")
+                for ref, p in connected[:15]:
+                    lines.append(f"  - {ref}:{p}")
+                if len(connected) > 15:
+                    lines.append(f"  - ... and {len(connected) - 15} more")
+            else:
+                lines.append("**No external connections**")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    except FileNotFoundError:
+        return f"Error: File not found: {file_path}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+async def analyze_hierarchical_nets(
+    file_path: str,
+    filter_pattern: str = "",
+    show_hierarchy: bool = True
+) -> str:
+    """Analyze all nets in hierarchical schematic design.
+
+    This tool analyzes network connections across the entire hierarchy,
+    showing how signals flow between main schematic and sub-sheets.
+
+    Args:
+        file_path: Path to main .kicad_sch file
+        filter_pattern: Optional regex pattern to filter net names
+        show_hierarchy: Whether to show hierarchical structure (default: True)
+
+    Returns:
+        Complete hierarchical net analysis
+    """
+    try:
+        import re
+
+        from .pin_analysis import _ensure_netlist
+
+        parser = SchematicParser(file_path)
+        sheets = parser.get_sheets()
+
+        netlist_path = await _ensure_netlist(Path(file_path))
+        if netlist_path is None:
+            return "# No Netlist Available\n\nCannot analyze nets without a netlist. Run `generate_netlist()` first."
+
+        nl = NetlistParser(str(netlist_path))
+
+        # docstring promises a regex; honour it (was a plain substring check).
+        try:
+            flt = re.compile(filter_pattern, re.IGNORECASE) if filter_pattern else None
+        except re.error:
+            flt = None
+
+        # NetlistNet.pins is a list[(ref, pin)] that is actually populated,
+        # unlike SchematicNet.pins which is always empty.
+        hierarchical_nets = {}
+        for name, net in nl.get_nets().items():
+            if flt and not flt.search(name):
+                continue
+            hierarchical_nets[name] = {
+                "location": "Netlist (whole board)",
+                "pins": net.pins,
+            }
+
+        if not hierarchical_nets:
+            return f"# No Nets Found\n\nNo nets found matching pattern: {filter_pattern if filter_pattern else 'all'}"
+
+        lines = [
+            "# Hierarchical Net Analysis",
+            "",
+            f"**File:** {file_path}",
+            f"**Total nets:** {len(hierarchical_nets)}",
+            f"**Filter:** {filter_pattern if filter_pattern else 'none'}",
+            f"**Hierarchical sheets:** {len(sheets)}",
+            "",
+            "## Network Summary",
+            "",
+        ]
+
+        power_nets, signal_nets, interface_nets = [], [], []
+        for net_name, net_info in hierarchical_nets.items():
+            up = net_name.upper()
+            if any(p in up for p in ["VDD", "VSS", "GND", "VCC", "VBAT", "VPP", "+3V", "+5V"]):
+                power_nets.append((net_name, net_info))
+            elif any(i in up for i in ["I2C", "SPI", "UART", "SDA", "SCL", "MOSI", "MISO", "TX", "RX"]):
+                interface_nets.append((net_name, net_info))
+            else:
+                signal_nets.append((net_name, net_info))
+
+        def _emit(title: str, group: list, limit: int) -> None:
+            if not group:
+                return
+            lines.append(f"### {title}")
+            for net_name, net_info in sorted(group)[:limit]:
+                lines.append(f"**{net_name}** ({net_info['location']})")
+                lines.append(f"  Connections: {len(net_info['pins'])} pins")
+                lines.append("")
+            if len(group) > limit:
+                lines.append(f"*... and {len(group) - limit} more*")
+            lines.append("")
+
+        _emit("Power Nets", power_nets, 20)
+        _emit("Interface Nets", interface_nets, 30)
+        _emit(f"Signal Nets (showing first 20 of {len(signal_nets)})", signal_nets, 20)
+
+        return "\n".join(lines)
+
+    except FileNotFoundError:
+        return f"Error: File not found: {file_path}"
+    except Exception as e:
+        return f"Error: {e}"

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

@@ -0,0 +1,320 @@
+"""Netlist generation and analysis tools for KiCad MCP Server."""
+
+import hashlib
+import tempfile
+from pathlib import Path
+
+from ..parsers.netlist_parser import NetlistParser
+from ..server import mcp
+from ..utils.kicad_cli import run_kicad_cli
+
+
+def netlist_cache_path(sch_path: Path) -> Path:
+    """Deterministic per-schematic netlist path in the temp directory.
+
+    Keying only on the file stem made two different projects that both have
+    e.g. a ``main.kicad_sch`` overwrite each other's exported netlist, so a
+    short digest of the resolved schematic path is mixed into the name.
+    """
+    digest = hashlib.sha256(str(sch_path.resolve()).encode("utf-8")).hexdigest()[:8]
+    return Path(tempfile.gettempdir()) / f"{sch_path.stem}_{digest}.xml"
+
+
+def _find_root_schematic(sch_path: Path) -> Path | None:
+    """If sch_path is a sub-sheet, return the root schematic instead.
+
+    KiCad convention: root schematic has the same stem as the .kicad_pro file.
+    Sub-sheets lack the hierarchy context needed to resolve unnamed wire-only
+    nets, so we redirect to the root schematic for complete netlist export.
+    """
+    pro_files = list(sch_path.parent.glob("*.kicad_pro"))
+    if len(pro_files) != 1:
+        return None
+    root_sch = pro_files[0].with_suffix(".kicad_sch")
+    if root_sch.exists() and root_sch.resolve() != sch_path.resolve():
+        return root_sch
+    return None
+
+
+@mcp.tool()
+async def generate_netlist(
+    schematic_path: str,
+) -> str:
+    """Generate KiCad netlist from schematic file.
+
+    Args:
+        schematic_path: Path to .kicad_sch file
+
+    Returns:
+        Path to generated .xml netlist file
+    """
+    try:
+        sch_path = Path(schematic_path)
+        if not sch_path.exists():
+            return f"❌ Schematic file not found: {schematic_path}"
+
+        # Detect sub-sheet and redirect to root schematic.
+        # Sub-sheets lack hierarchy context to resolve unnamed wire-only nets.
+        subsheet_note = ""
+        root_sch = _find_root_schematic(sch_path)
+        if root_sch:
+            subsheet_note = (
+                f"\n\n⚠️ **Note:** `{sch_path.name}` is a hierarchical sub-sheet. "
+                f"Switched to root schematic `{root_sch.name}` for complete netlist "
+                f"(unnamed wire-only nets require full hierarchy context to resolve)."
+            )
+            sch_path = root_sch
+
+        # KiCad 7+ uses kicad-cli for headless netlist export
+        # Output to temp directory to avoid read-only volume issues
+        netlist_path = netlist_cache_path(sch_path)
+
+        # Try to use KiCad's netlist export
+        # Note: Requires a KiCad installation — kicad-cli is located via
+        # PATH or the detected install directory (see utils.kicad_cli).
+        try:
+            # Use kicad-cli for headless export (no display required)
+            result = await run_kicad_cli(
+                [
+                    "sch",
+                    "export",
+                    "netlist",
+                    "--format",
+                    "kicadxml",
+                    "--output",
+                    str(netlist_path),
+                    str(sch_path),
+                ],
+                timeout=30,
+            )
+
+            if result.returncode == 0 and netlist_path.exists():
+                return f"""✅ Netlist generated successfully
+
+**Output:** {netlist_path}
+
+You can now use netlist-based tools:
+- `trace_netlist_connection()` - Trace component connections via netlist
+- `get_netlist_nets()` - List all nets
+- `get_netlist_components()` - List all components with their nets
+{subsheet_note}"""
+            else:
+                # Fallback: return instructions
+                return f"""⚠️ Automatic netlist generation failed.
+
+KiCad command line tools may not be available.
+
+**Manual export steps:**
+1. Open schematic in KiCad: {sch_path}
+2. Go to: Tools → Generate Netlist
+3. Select: "KiCad XML" format
+4. Save to: {netlist_path}
+
+**Alternative:**
+Use KiCad Schematic Editor GUI to export netlist.
+"""
+
+        except FileNotFoundError:
+            return """⚠️ kicad-cli not found (PATH or KiCad install directory).
+
+Please:
+1. Install KiCad 7+ (https://www.kicad.org/)
+2. Ensure kicad-cli is in system PATH, or set the KICAD_CLI
+   environment variable to its full path
+3. Or use KiCad GUI to export netlist manually
+
+**Manual export:**
+Open schematic → Tools → Generate Netlist → KiCad XML format
+"""
+
+    except Exception as e:
+        return f"❌ Error generating netlist: {e}"
+
+
+@mcp.tool()
+async def trace_netlist_connection(
+    netlist_path: str,
+    reference: str,
+    pin_number: str = "",
+) -> str:
+    """Trace component connections using netlist file (most accurate).
+
+    Args:
+        netlist_path: Path to .xml netlist file
+        reference: Component reference (e.g., 'R16')
+        pin_number: Optional pin number (e.g., '1'). If empty, trace all pins.
+
+    Returns:
+        Detailed connection information from netlist
+    """
+    try:
+        parser = NetlistParser(netlist_path)
+
+        if pin_number:
+            result = parser.trace_connection(reference, pin_number)
+
+            if "error" in result:
+                return f"❌ {result['error']}"
+
+            lines = [
+                f"## Netlist Connection Trace: {reference}",
+                "",
+                f"**Pin:** {result['pin']}",
+                f"**Net:** {result['net']}",
+                "",
+                "### Connected Components:",
+                "",
+            ]
+
+            if result['connected_to']:
+                lines.append("| Reference | Pin |")
+                lines.append("|-----------|-----|")
+                for ref, pin in result['connected_to']:
+                    lines.append(f"| {ref} | {pin} |")
+            else:
+                lines.append("No other components on this net.")
+
+            return "\n".join(lines)
+
+        else:
+            result = parser.trace_connection(reference)
+
+            if "error" in result:
+                return f"❌ {result['error']}"
+
+            lines = [
+                f"## Netlist Connection Trace: {reference}",
+                "",
+                f"**Total Nets:** {len(result['nets'])}",
+                "",
+            ]
+
+            for net_name, net_info in result['nets'].items():
+                lines.append(f"### Net: {net_name}")
+                lines.append(f"**Pin:** {net_info['pin']}")
+                lines.append("")
+
+                if net_info['connected_to']:
+                    lines.append("| Reference | Pin |")
+                    lines.append("|-----------|-----|")
+                    for ref, pin in net_info['connected_to']:
+                        lines.append(f"| {ref} | {pin} |")
+                else:
+                    lines.append("No other components on this net.")
+
+                lines.append("")
+
+            return "\n".join(lines)
+
+    except FileNotFoundError as e:
+        return f"❌ File not found: {e}"
+    except Exception as e:
+        return f"❌ Error tracing netlist: {e}"
+
+
+@mcp.tool()
+async def get_netlist_nets(
+    netlist_path: str,
+    filter_pattern: str = "",
+) -> str:
+    """Get all nets from netlist file.
+
+    Args:
+        netlist_path: Path to .xml netlist file
+        filter_pattern: Optional regex pattern to filter net names
+
+    Returns:
+        List of all nets with their connections
+    """
+    try:
+        parser = NetlistParser(netlist_path)
+        nets = parser.get_nets()
+
+        lines = [
+            f"## Nets from Netlist: {netlist_path}",
+            "",
+            f"**Total Nets:** {len(nets)}",
+            "",
+        ]
+
+        for net_name, net in sorted(nets.items()):
+            if filter_pattern:
+                import re
+                if not re.search(filter_pattern, net_name, re.IGNORECASE):
+                    continue
+
+            lines.append(f"### {net_name}")
+            lines.append(f"**Code:** {net.code}")
+            lines.append(f"**Connections:** {len(net.pins)} pins")
+
+            if net.pins:
+                lines.append("")
+                lines.append("| Reference | Pin |")
+                lines.append("|-----------|-----|")
+                for ref, pin in net.pins[:10]:  # Show first 10
+                    lines.append(f"| {ref} | {pin} |")
+                if len(net.pins) > 10:
+                    lines.append(f"| ... | ({len(net.pins) - 10} more) |")
+
+            lines.append("")
+
+        return "\n".join(lines)
+
+    except FileNotFoundError as e:
+        return f"❌ File not found: {e}"
+    except Exception as e:
+        return f"❌ Error reading netlist: {e}"
+
+
+@mcp.tool()
+async def get_netlist_components(
+    netlist_path: str,
+    filter_ref: str = "",
+) -> str:
+    """Get all components from netlist with their network connections.
+
+    Args:
+        netlist_path: Path to .xml netlist file
+        filter_ref: Optional reference filter (e.g., 'R', 'U', 'C')
+
+    Returns:
+        List of components with their net connections
+    """
+    try:
+        parser = NetlistParser(netlist_path)
+        components = parser.get_components()
+
+        lines = [
+            f"## Components from Netlist: {netlist_path}",
+            "",
+            f"**Total Components:** {len(components)}",
+            "",
+        ]
+
+        for ref, comp in sorted(components.items()):
+            if filter_ref and not ref.startswith(filter_ref):
+                continue
+
+            lines.append(f"### {ref}")
+            lines.append(f"**Value:** {comp.value}")
+            lines.append(f"**Library:** {comp.library}")
+            if comp.footprint:
+                lines.append(f"**Footprint:** {comp.footprint}")
+
+            if comp.pins:
+                lines.append("")
+                lines.append("**Pin Connections:**")
+                lines.append("")
+                lines.append("| Pin | Net |")
+                lines.append("|-----|-----|")
+                for pin_num, net_name in sorted(comp.pins.items()):
+                    lines.append(f"| {pin_num} | {net_name} |")
+
+            lines.append("")
+
+        return "\n".join(lines)
+
+    except FileNotFoundError as e:
+        return f"❌ File not found: {e}"
+    except Exception as e:
+        return f"❌ Error reading netlist: {e}"

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

@@ -0,0 +1,142 @@
+"""Parts registry tools — search and fetch verified KiCad parts.
+
+Backed by an open, no-login registry (default: PartReel, https://partreel.com;
+configurable via PARTS_REGISTRY_URL). Lets the assistant pull real, quality-
+gated footprints/symbols/3D models instead of drawing them from scratch.
+"""
+
+import asyncio
+import json
+import os
+from pathlib import Path
+
+from ..server import mcp
+from ..utils.parts_registry import (
+    FORMAT_EXTENSIONS,
+    RegistryClient,
+    RegistryError,
+)
+
+
+@mcp.tool()
+async def search_parts_registry(query: str, limit: int = 20) -> str:
+    """Search an open registry of 21,000+ verified KiCad parts (no login).
+
+    Matches part id, name, family, category, manufacturer and keywords.
+    Example queries: "usb c connector", "0402 capacitor", "nrf9151".
+
+    Args:
+        query: Search terms (all terms must match; '*' wildcards allowed)
+        limit: Maximum number of results (default 20)
+
+    Returns:
+        JSON list of matches (id, name, family, page URL)
+    """
+    client = RegistryClient()
+    try:
+        hits = await asyncio.to_thread(client.search, query, limit)
+    except RegistryError as exc:
+        return f"❌ Registry search failed: {exc}"
+    if not hits:
+        return f"No registry parts matched '{query}'."
+    rows = [
+        {
+            "id": p.get("id"),
+            "name": p.get("name"),
+            "family": p.get("family"),
+            "category": p.get("category"),
+            "manufacturer": p.get("manufacturer"),
+            "page": p.get("page"),
+        }
+        for p in hits
+    ]
+    return json.dumps({"count": len(rows), "parts": rows}, indent=2)
+
+
+@mcp.tool()
+async def get_registry_part(part_id: str) -> str:
+    """Get the full registry record for one part.
+
+    Includes download URLs (footprint/symbol/3D), datasheet link, dimension
+    provenance and field reports from real builds.
+
+    Args:
+        part_id: Registry part id (from search_parts_registry)
+
+    Returns:
+        JSON part record
+    """
+    client = RegistryClient()
+    try:
+        part = await asyncio.to_thread(client.get_part, part_id)
+    except RegistryError as exc:
+        return f"❌ Registry lookup failed: {exc}"
+    return json.dumps(part, indent=2)
+
+
+@mcp.tool()
+async def download_registry_part(
+    part_id: str, save_dir: str, formats: list[str] | None = None
+) -> str:
+    """Download a registry part's files into a local directory.
+
+    Downloads are HTTPS-only, restricted to the registry's own hosts,
+    capped at 50 MB per file, and saved with extension-checked filenames.
+
+    Args:
+        part_id: Registry part id (from search_parts_registry)
+        save_dir: Existing local directory (e.g. the project library folder)
+        formats: Which files — any of "footprint", "symbol", "step",
+            "preview" (default: footprint + symbol)
+
+    Returns:
+        Saved file paths, or an error
+    """
+    formats = formats or ["footprint", "symbol"]
+    unknown = [f for f in formats if f not in FORMAT_EXTENSIONS]
+    if unknown:
+        return f"❌ Unknown formats: {unknown} (allowed: {sorted(FORMAT_EXTENSIONS)})"
+
+    dest = Path(save_dir)
+    if not dest.is_dir():
+        return f"❌ Not a directory: {save_dir}"
+    # Confine writes to the working dir or the user's home tree
+    # (extend via PARTS_REGISTRY_SAVE_ROOTS, comma-separated).
+    roots = [Path.cwd(), Path.home()]
+    roots += [
+        Path(r.strip())
+        for r in os.environ.get("PARTS_REGISTRY_SAVE_ROOTS", "").split(",")
+        if r.strip()
+    ]
+    real = dest.resolve()
+    if not any(real == r.resolve() or r.resolve() in real.parents for r in roots):
+        return f"❌ save_dir outside allowed roots (cwd/home): {save_dir}"
+
+    client = RegistryClient()
+    try:
+        part = await asyncio.to_thread(client.get_part, part_id)
+    except RegistryError as exc:
+        return f"❌ Registry lookup failed: {exc}"
+
+    files = (part.get("files") if isinstance(part, dict) else None) or {}
+    saved, missing = [], []
+    for fmt in formats:
+        url = files.get(fmt)
+        if not url:
+            missing.append(fmt)
+            continue
+        try:
+            path = await asyncio.to_thread(
+                client.download_asset, url, str(real), part_id, fmt
+            )
+            saved.append(path)
+        except (RegistryError, OSError) as exc:
+            # OSError covers disk-full / permission-denied / Windows reserved
+            # names — surface the partial result instead of losing it.
+            return f"❌ Download failed for {fmt}: {exc} (saved so far: {saved})"
+    out = {
+        "saved": saved,
+        "not_available": missing,
+        "license": part.get("license") if isinstance(part, dict) else None,
+    }
+    return json.dumps(out, indent=2)