feat: add unit parameter to add_schematic_component for multi-unit symbols

Allows placing a specific unit (A=1, B=2, C=3, …) of a multi-unit KiCad
symbol rather than always defaulting to unit 1. Required for quad
optocouplers, dual op-amps, and other multi-unit parts where each channel
must be placed independently.

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

python/commands/dynamic_symbol_loader.py

@@ -402,15 +402,17 @@ class DynamicSymbolLoader:
         footprint: str = "",
         x: float = 0,
         y: float = 0,
+        unit: int = 1,
     ) -> bool:
         """
         Add a component instance to the schematic.
         This creates the (symbol ...) block with lib_id reference.
+        For multi-unit symbols, set unit to 1–N to place a specific unit.
         """
         full_lib_id = f"{library_name}:{symbol_name}"
         new_uuid = str(uuid.uuid4())
 
-        instance_block = f"""  (symbol (lib_id "{full_lib_id}") (at {x} {y} 0) (unit 1)
+        instance_block = f"""  (symbol (lib_id "{full_lib_id}") (at {x} {y} 0) (unit {unit})
     (in_bom yes) (on_board yes) (dnp no)
     (uuid "{new_uuid}")
     (property "Reference" "{reference}" (at {x} {y - 2.54} 0)
@@ -429,7 +431,7 @@ class DynamicSymbolLoader:
       (project "project"
         (path "/"
           (reference "{reference}")
-          (unit 1)
+          (unit {unit})
         )
       )
     )
@@ -493,6 +495,7 @@ class DynamicSymbolLoader:
         footprint: str = "",
         x: float = 0,
         y: float = 0,
+        unit: int = 1,
         project_path: Optional[Path] = None,
     ) -> bool:
         """
@@ -500,6 +503,7 @@ class DynamicSymbolLoader:
         This is the main entry point for adding components.
 
         Args:
+            unit: For multi-unit symbols, which unit to place (1=A, 2=B, …). Default 1.
             project_path: Optional project directory. When set, project-specific
                           sym-lib-table is also searched for the library file.
         """
@@ -518,6 +522,7 @@ class DynamicSymbolLoader:
             footprint=footprint,
             x=x,
             y=y,
+            unit=unit,
         )
 
 

python/kicad_interface.py

@@ -717,6 +717,7 @@ class KiCADInterface:
             footprint = component.get("footprint", "")
             x = component.get("x", 0)
             y = component.get("y", 0)
+            unit = component.get("unit", 1)
 
             # Derive project path from schematic path for project-local library resolution
             schematic_file = Path(schematic_path)
@@ -732,6 +733,7 @@ class KiCADInterface:
                 footprint=footprint,
                 x=x,
                 y=y,
+                unit=unit,
                 project_path=derived_project_path,
             )
 

src/tools/schematic.ts

@@ -49,6 +49,12 @@ export function registerSchematicTools(server: McpServer, callKicadScript: Funct
         })
         .optional()
         .describe("Position on schematic"),
+      unit: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Unit number for multi-unit symbols (1=A, 2=B, 3=C, …). Defaults to 1."),
     },
     async (args: {
       schematicPath: string;
@@ -57,6 +63,7 @@ export function registerSchematicTools(server: McpServer, callKicadScript: Funct
       value?: string;
       footprint?: string;
       position?: { x: number; y: number };
+      unit?: number;
     }) => {
       // Transform to what Python backend expects
       const [library, symbolName] = args.symbol.includes(":")
@@ -74,6 +81,7 @@ export function registerSchematicTools(server: McpServer, callKicadScript: Funct
           // Python expects flat x, y not nested position
           x: args.position?.x ?? 0,
           y: args.position?.y ?? 0,
+          unit: args.unit ?? 1,
         },
       };