feat: add get_pin_net tool for direct net/pin queries

Answers "what net is pin X of component Y on?" without requiring
callers to triangulate from list_schematic_nets or know a wire
coordinate first.

Accepts either {reference, pin} (resolved via PinLocator) or {x, y}
coordinate. Returns net label name (or null for unnamed nets), all
connected pins, wire segments, and the resolved query point.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

python/commands/wire_connectivity.py

@@ -273,3 +273,61 @@ def get_wire_connections(
 
     pins = _find_pins_on_net(net_points, schematic_path, schematic)
     return {"pins": pins, "wires": wires_out}
+
+
+def get_pin_net(schematic: Any, schematic_path: str, x_mm: float, y_mm: float) -> Optional[Dict]:
+    """Return the net name and all connected pins for the wire network at (x_mm, y_mm).
+
+    Returns dict with keys:
+      - "net": str or None (net label/power name, None if unnamed)
+      - "pins": list of {"component": str, "pin": str}
+      - "wires": list of {"start": {"x", "y"}, "end": {"x", "y"}} in mm
+      - "query_point": {"x": float, "y": float}
+    Or None if no wire endpoint found at the query point.
+    """
+    all_wires = _parse_wires(schematic)
+    if not all_wires:
+        return {"net": None, "pins": [], "wires": [], "query_point": {"x": x_mm, "y": y_mm}}
+
+    adjacency, iu_to_wires = _build_adjacency(all_wires)
+    point_to_label, label_to_points = _parse_virtual_connections(schematic, schematic_path)
+
+    visited, net_points = _find_connected_wires(
+        x_mm,
+        y_mm,
+        all_wires,
+        iu_to_wires,
+        adjacency,
+        point_to_label=point_to_label,
+        label_to_points=label_to_points,
+    )
+    if visited is None:
+        return None
+
+    # Resolve net name: first label anchor that falls on this net's IU points
+    net: Optional[str] = None
+    for pt in net_points:
+        label = point_to_label.get(pt)
+        if label is not None:
+            net = label
+            break
+
+    wires_out = [
+        {
+            "start": {
+                "x": all_wires[i][0][0] / _IU_PER_MM,
+                "y": all_wires[i][0][1] / _IU_PER_MM,
+            },
+            "end": {
+                "x": all_wires[i][-1][0] / _IU_PER_MM,
+                "y": all_wires[i][-1][1] / _IU_PER_MM,
+            },
+        }
+        for i in visited
+    ]
+
+    pins: List[Dict] = []
+    if hasattr(schematic, "symbol"):
+        pins = _find_pins_on_net(net_points, schematic_path, schematic)
+
+    return {"net": net, "pins": pins, "wires": wires_out, "query_point": {"x": x_mm, "y": y_mm}}

python/kicad_interface.py

@@ -382,6 +382,7 @@ class KiCADInterface:
             "get_schematic_pin_locations": self._handle_get_schematic_pin_locations,
             "get_net_connections": self._handle_get_net_connections,
             "get_wire_connections": self._handle_get_wire_connections,
+            "get_pin_net": self._handle_get_pin_net,
             "run_erc": self._handle_run_erc,
             "generate_netlist": self._handle_generate_netlist,
             "sync_schematic_to_board": self._handle_sync_schematic_to_board,
@@ -2503,6 +2504,70 @@ class KiCADInterface:
             logger.error(traceback.format_exc())
             return {"success": False, "message": str(e)}
 
+    def _handle_get_pin_net(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Find net name and all connected pins for a reference+pin or coordinate query"""
+        logger.info("Getting pin net")
+        try:
+            from pathlib import Path
+
+            from commands.pin_locator import PinLocator
+            from commands.wire_connectivity import get_pin_net
+
+            schematic_path = params.get("schematicPath")
+            if not schematic_path:
+                return {"success": False, "message": "Missing required parameter: schematicPath"}
+
+            reference = params.get("reference")
+            pin = params.get("pin")
+            x = params.get("x")
+            y = params.get("y")
+
+            has_ref_pin = reference is not None and pin is not None
+            has_coords = x is not None and y is not None
+
+            if not has_ref_pin and not has_coords:
+                return {
+                    "success": False,
+                    "message": "Must supply either {reference, pin} or {x, y}",
+                }
+
+            if has_ref_pin:
+                location = PinLocator().get_pin_location(Path(schematic_path), reference, str(pin))
+                if location is None:
+                    return {
+                        "success": False,
+                        "message": f"Pin {pin} not found on {reference}",
+                    }
+                x, y = location[0], location[1]
+            else:
+                try:
+                    x, y = float(x), float(y)
+                except (TypeError, ValueError):
+                    return {"success": False, "message": "Parameters x and y must be numeric"}
+
+            schematic = SchematicManager.load_schematic(schematic_path)
+            if not schematic:
+                return {"success": False, "message": "Failed to load schematic"}
+
+            if not hasattr(schematic, "wire"):
+                return {"success": False, "message": "Schematic has no wires"}
+
+            result = get_pin_net(schematic, schematic_path, x, y)
+            if result is None:
+                return {
+                    "success": False,
+                    "message": f"No wire found at ({x},{y}) — pin may not be connected",
+                }
+
+            return {"success": True, **result}
+
+        except Exception as e:
+            logger.error(f"Error getting pin net: {str(e)}")
+            import traceback
+
+            logger.error(traceback.format_exc())
+            return {"success": False, "message": str(e)}
+
     def _handle_run_erc(self, params: Dict[str, Any]) -> Dict[str, Any]:
         """Run Electrical Rules Check on a schematic via kicad-cli"""
         logger.info("Running ERC on schematic")

python/schemas/tool_schemas.py

@@ -1523,6 +1523,44 @@ SCHEMATIC_TOOLS = [
             "required": ["schematicPath", "x", "y"],
         },
     },
+    {
+        "name": "get_pin_net",
+        "title": "Get Pin Net",
+        "description": (
+            "Returns the net name and all connected component pins for a query. "
+            "Accepts either a component reference + pin number (e.g. reference='U1', pin='3') "
+            "or a schematic coordinate (x, y in mm). "
+            "If a net label or power symbol is reachable from the query point, its name is "
+            "returned as 'net'; otherwise 'net' is null (unnamed net). "
+            "The 'pins' list contains every component pin on that same net."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "schematicPath": {
+                    "type": "string",
+                    "description": "Path to the schematic file (.kicad_sch)",
+                },
+                "reference": {
+                    "type": "string",
+                    "description": "Component reference (e.g. U1, R1). Pair with pin.",
+                },
+                "pin": {
+                    "type": "string",
+                    "description": "Pin number or name (e.g. '3', 'SDA'). Pair with reference.",
+                },
+                "x": {
+                    "type": "number",
+                    "description": "X coordinate of a wire endpoint in mm. Pair with y.",
+                },
+                "y": {
+                    "type": "number",
+                    "description": "Y coordinate of a wire endpoint in mm. Pair with x.",
+                },
+            },
+            "required": ["schematicPath"],
+        },
+    },
     {
         "name": "get_schematic_pin_locations",
         "title": "Get Schematic Pin Locations",