This is page 4 of 4. Use http://codebase.md/mixelpixx/kicad-mcp-server?page={x} to view the full context.
# Directory Structure
```
├── .github
│ └── workflows
│ └── ci.yml
├── .gitignore
├── .pre-commit-config.yaml
├── CHANGELOG_2025-10-26.md
├── CHANGELOG_2025-11-01.md
├── CHANGELOG_2025-11-05.md
├── CHANGELOG_2025-11-30.md
├── config
│ ├── claude-desktop-config.json
│ ├── default-config.json
│ ├── linux-config.example.json
│ ├── macos-config.example.json
│ └── windows-config.example.json
├── CONTRIBUTING.md
├── docs
│ ├── BUILD_AND_TEST_SESSION.md
│ ├── CLIENT_CONFIGURATION.md
│ ├── IPC_API_MIGRATION_PLAN.md
│ ├── IPC_BACKEND_STATUS.md
│ ├── JLCPCB_INTEGRATION_PLAN.md
│ ├── KNOWN_ISSUES.md
│ ├── LIBRARY_INTEGRATION.md
│ ├── LINUX_COMPATIBILITY_AUDIT.md
│ ├── PLATFORM_GUIDE.md
│ ├── REALTIME_WORKFLOW.md
│ ├── ROADMAP.md
│ ├── STATUS_SUMMARY.md
│ ├── UI_AUTO_LAUNCH.md
│ ├── VISUAL_FEEDBACK.md
│ ├── WEEK1_SESSION1_SUMMARY.md
│ ├── WEEK1_SESSION2_SUMMARY.md
│ └── WINDOWS_TROUBLESHOOTING.md
├── LICENSE
├── package-json.json
├── package-lock.json
├── package.json
├── pytest.ini
├── python
│ ├── commands
│ │ ├── __init__.py
│ │ ├── board
│ │ │ ├── __init__.py
│ │ │ ├── layers.py
│ │ │ ├── outline.py
│ │ │ ├── size.py
│ │ │ └── view.py
│ │ ├── board.py
│ │ ├── component_schematic.py
│ │ ├── component.py
│ │ ├── connection_schematic.py
│ │ ├── design_rules.py
│ │ ├── export.py
│ │ ├── library_schematic.py
│ │ ├── library.py
│ │ ├── project.py
│ │ ├── routing.py
│ │ └── schematic.py
│ ├── kicad_api
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── factory.py
│ │ ├── ipc_backend.py
│ │ └── swig_backend.py
│ ├── kicad_interface.py
│ ├── requirements.txt
│ ├── resources
│ │ ├── __init__.py
│ │ └── resource_definitions.py
│ ├── schemas
│ │ ├── __init__.py
│ │ └── tool_schemas.py
│ ├── test_ipc_backend.py
│ └── utils
│ ├── __init__.py
│ ├── kicad_process.py
│ └── platform_helper.py
├── README.md
├── requirements-dev.txt
├── requirements.txt
├── scripts
│ ├── auto_refresh_kicad.sh
│ └── install-linux.sh
├── setup-windows.ps1
├── src
│ ├── config.ts
│ ├── index.ts
│ ├── kicad-server.ts
│ ├── logger.ts
│ ├── prompts
│ │ ├── component.ts
│ │ ├── design.ts
│ │ ├── index.ts
│ │ └── routing.ts
│ ├── resources
│ │ ├── board.ts
│ │ ├── component.ts
│ │ ├── index.ts
│ │ ├── library.ts
│ │ └── project.ts
│ ├── server.ts
│ ├── tools
│ │ ├── board.ts
│ │ ├── component.ts
│ │ ├── component.txt
│ │ ├── design-rules.ts
│ │ ├── export.ts
│ │ ├── index.ts
│ │ ├── library.ts
│ │ ├── project.ts
│ │ ├── routing.ts
│ │ ├── schematic.ts
│ │ └── ui.ts
│ └── utils
│ └── resource-helpers.ts
├── tests
│ ├── __init__.py
│ └── test_platform_helper.py
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/python/commands/component.py:
--------------------------------------------------------------------------------
```python
"""
Component-related command implementations for KiCAD interface
"""
import os
import pcbnew
import logging
import math
from typing import Dict, Any, Optional, List, Tuple
import base64
from commands.library import LibraryManager
logger = logging.getLogger('kicad_interface')
class ComponentCommands:
"""Handles component-related KiCAD operations"""
def __init__(self, board: Optional[pcbnew.BOARD] = None, library_manager: Optional[LibraryManager] = None):
"""Initialize with optional board instance and library manager"""
self.board = board
self.library_manager = library_manager or LibraryManager()
def place_component(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Place a component on the PCB"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
# Get parameters
component_id = params.get("componentId")
position = params.get("position")
reference = params.get("reference")
value = params.get("value")
footprint = params.get("footprint")
rotation = params.get("rotation", 0)
layer = params.get("layer", "F.Cu")
if not component_id or not position:
return {
"success": False,
"message": "Missing parameters",
"errorDetails": "componentId and position are required"
}
# Find footprint using library manager
# component_id can be "Library:Footprint" or just "Footprint"
footprint_result = self.library_manager.find_footprint(component_id)
if not footprint_result:
# Try to suggest similar footprints
suggestions = self.library_manager.search_footprints(f"*{component_id}*", limit=5)
suggestion_text = ""
if suggestions:
suggestion_text = "\n\nDid you mean one of these?\n" + \
"\n".join([f" - {s['full_name']}" for s in suggestions])
return {
"success": False,
"message": "Footprint not found",
"errorDetails": f"Could not find footprint: {component_id}{suggestion_text}"
}
library_path, footprint_name = footprint_result
# Load footprint from library
# Extract library nickname from path
library_nickname = None
for nick, path in self.library_manager.libraries.items():
if path == library_path:
library_nickname = nick
break
if not library_nickname:
return {
"success": False,
"message": "Internal error",
"errorDetails": "Could not determine library nickname"
}
# Load the footprint
module = pcbnew.FootprintLoad(library_path, footprint_name)
if not module:
return {
"success": False,
"message": "Failed to load footprint",
"errorDetails": f"Could not load footprint from {library_path}/{footprint_name}"
}
# Set position
scale = 1000000 if position["unit"] == "mm" else 25400000 # mm or inch to nm
x_nm = int(position["x"] * scale)
y_nm = int(position["y"] * scale)
module.SetPosition(pcbnew.VECTOR2I(x_nm, y_nm))
# Set reference if provided
if reference:
module.SetReference(reference)
# Set value if provided
if value:
module.SetValue(value)
# Set footprint if provided
if footprint:
module.SetFootprintName(footprint)
# Set rotation (KiCAD 9.0 uses EDA_ANGLE)
angle = pcbnew.EDA_ANGLE(rotation, pcbnew.DEGREES_T)
module.SetOrientation(angle)
# Set layer
layer_id = self.board.GetLayerID(layer)
if layer_id >= 0:
module.SetLayer(layer_id)
# Add to board
self.board.Add(module)
return {
"success": True,
"message": f"Placed component: {component_id}",
"component": {
"reference": module.GetReference(),
"value": module.GetValue(),
"position": {
"x": position["x"],
"y": position["y"],
"unit": position["unit"]
},
"rotation": rotation,
"layer": layer
}
}
except Exception as e:
logger.error(f"Error placing component: {str(e)}")
return {
"success": False,
"message": "Failed to place component",
"errorDetails": str(e)
}
def move_component(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Move an existing component to a new position"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
reference = params.get("reference")
position = params.get("position")
rotation = params.get("rotation")
if not reference or not position:
return {
"success": False,
"message": "Missing parameters",
"errorDetails": "reference and position are required"
}
# Find the component
module = self.board.FindFootprintByReference(reference)
if not module:
return {
"success": False,
"message": "Component not found",
"errorDetails": f"Could not find component: {reference}"
}
# Set new position
scale = 1000000 if position["unit"] == "mm" else 25400000 # mm or inch to nm
x_nm = int(position["x"] * scale)
y_nm = int(position["y"] * scale)
module.SetPosition(pcbnew.VECTOR2I(x_nm, y_nm))
# Set new rotation if provided
if rotation is not None:
angle = pcbnew.EDA_ANGLE(rotation, pcbnew.DEGREES_T)
module.SetOrientation(angle)
return {
"success": True,
"message": f"Moved component: {reference}",
"component": {
"reference": reference,
"position": {
"x": position["x"],
"y": position["y"],
"unit": position["unit"]
},
"rotation": rotation if rotation is not None else module.GetOrientation().AsDegrees()
}
}
except Exception as e:
logger.error(f"Error moving component: {str(e)}")
return {
"success": False,
"message": "Failed to move component",
"errorDetails": str(e)
}
def rotate_component(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Rotate an existing component"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
reference = params.get("reference")
angle = params.get("angle")
if not reference or angle is None:
return {
"success": False,
"message": "Missing parameters",
"errorDetails": "reference and angle are required"
}
# Find the component
module = self.board.FindFootprintByReference(reference)
if not module:
return {
"success": False,
"message": "Component not found",
"errorDetails": f"Could not find component: {reference}"
}
# Set rotation
rotation_angle = pcbnew.EDA_ANGLE(angle, pcbnew.DEGREES_T)
module.SetOrientation(rotation_angle)
return {
"success": True,
"message": f"Rotated component: {reference}",
"component": {
"reference": reference,
"rotation": angle
}
}
except Exception as e:
logger.error(f"Error rotating component: {str(e)}")
return {
"success": False,
"message": "Failed to rotate component",
"errorDetails": str(e)
}
def delete_component(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Delete a component from the PCB"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
reference = params.get("reference")
if not reference:
return {
"success": False,
"message": "Missing reference",
"errorDetails": "reference parameter is required"
}
# Find the component
module = self.board.FindFootprintByReference(reference)
if not module:
return {
"success": False,
"message": "Component not found",
"errorDetails": f"Could not find component: {reference}"
}
# Remove from board
self.board.Remove(module)
return {
"success": True,
"message": f"Deleted component: {reference}"
}
except Exception as e:
logger.error(f"Error deleting component: {str(e)}")
return {
"success": False,
"message": "Failed to delete component",
"errorDetails": str(e)
}
def edit_component(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Edit the properties of an existing component"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
reference = params.get("reference")
new_reference = params.get("newReference")
value = params.get("value")
footprint = params.get("footprint")
if not reference:
return {
"success": False,
"message": "Missing reference",
"errorDetails": "reference parameter is required"
}
# Find the component
module = self.board.FindFootprintByReference(reference)
if not module:
return {
"success": False,
"message": "Component not found",
"errorDetails": f"Could not find component: {reference}"
}
# Update properties
if new_reference:
module.SetReference(new_reference)
if value:
module.SetValue(value)
if footprint:
module.SetFootprintName(footprint)
return {
"success": True,
"message": f"Updated component: {reference}",
"component": {
"reference": new_reference or reference,
"value": value or module.GetValue(),
"footprint": footprint or module.GetFPIDAsString()
}
}
except Exception as e:
logger.error(f"Error editing component: {str(e)}")
return {
"success": False,
"message": "Failed to edit component",
"errorDetails": str(e)
}
def get_component_properties(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Get detailed properties of a component"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
reference = params.get("reference")
if not reference:
return {
"success": False,
"message": "Missing reference",
"errorDetails": "reference parameter is required"
}
# Find the component
module = self.board.FindFootprintByReference(reference)
if not module:
return {
"success": False,
"message": "Component not found",
"errorDetails": f"Could not find component: {reference}"
}
# Get position in mm
pos = module.GetPosition()
x_mm = pos.x / 1000000
y_mm = pos.y / 1000000
return {
"success": True,
"component": {
"reference": module.GetReference(),
"value": module.GetValue(),
"footprint": module.GetFPIDAsString(),
"position": {
"x": x_mm,
"y": y_mm,
"unit": "mm"
},
"rotation": module.GetOrientation().AsDegrees(),
"layer": self.board.GetLayerName(module.GetLayer()),
"attributes": {
"smd": module.GetAttributes() & pcbnew.FP_SMD,
"through_hole": module.GetAttributes() & pcbnew.FP_THROUGH_HOLE,
"board_only": module.GetAttributes() & pcbnew.FP_BOARD_ONLY
}
}
}
except Exception as e:
logger.error(f"Error getting component properties: {str(e)}")
return {
"success": False,
"message": "Failed to get component properties",
"errorDetails": str(e)
}
def get_component_list(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Get a list of all components on the board"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
components = []
for module in self.board.GetFootprints():
pos = module.GetPosition()
x_mm = pos.x / 1000000
y_mm = pos.y / 1000000
components.append({
"reference": module.GetReference(),
"value": module.GetValue(),
"footprint": module.GetFPIDAsString(),
"position": {
"x": x_mm,
"y": y_mm,
"unit": "mm"
},
"rotation": module.GetOrientation().AsDegrees(),
"layer": self.board.GetLayerName(module.GetLayer())
})
return {
"success": True,
"components": components
}
except Exception as e:
logger.error(f"Error getting component list: {str(e)}")
return {
"success": False,
"message": "Failed to get component list",
"errorDetails": str(e)
}
def place_component_array(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Place an array of components in a grid or circular pattern"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
component_id = params.get("componentId")
pattern = params.get("pattern", "grid") # grid or circular
count = params.get("count")
reference_prefix = params.get("referencePrefix", "U")
value = params.get("value")
if not component_id or not count:
return {
"success": False,
"message": "Missing parameters",
"errorDetails": "componentId and count are required"
}
if pattern == "grid":
start_position = params.get("startPosition")
rows = params.get("rows")
columns = params.get("columns")
spacing_x = params.get("spacingX")
spacing_y = params.get("spacingY")
rotation = params.get("rotation", 0)
layer = params.get("layer", "F.Cu")
if not start_position or not rows or not columns or not spacing_x or not spacing_y:
return {
"success": False,
"message": "Missing grid parameters",
"errorDetails": "For grid pattern, startPosition, rows, columns, spacingX, and spacingY are required"
}
if rows * columns != count:
return {
"success": False,
"message": "Invalid grid parameters",
"errorDetails": "rows * columns must equal count"
}
placed_components = self._place_grid_array(
component_id,
start_position,
rows,
columns,
spacing_x,
spacing_y,
reference_prefix,
value,
rotation,
layer
)
elif pattern == "circular":
center = params.get("center")
radius = params.get("radius")
angle_start = params.get("angleStart", 0)
angle_step = params.get("angleStep")
rotation_offset = params.get("rotationOffset", 0)
layer = params.get("layer", "F.Cu")
if not center or not radius or not angle_step:
return {
"success": False,
"message": "Missing circular parameters",
"errorDetails": "For circular pattern, center, radius, and angleStep are required"
}
placed_components = self._place_circular_array(
component_id,
center,
radius,
count,
angle_start,
angle_step,
reference_prefix,
value,
rotation_offset,
layer
)
else:
return {
"success": False,
"message": "Invalid pattern",
"errorDetails": "Pattern must be 'grid' or 'circular'"
}
return {
"success": True,
"message": f"Placed {count} components in {pattern} pattern",
"components": placed_components
}
except Exception as e:
logger.error(f"Error placing component array: {str(e)}")
return {
"success": False,
"message": "Failed to place component array",
"errorDetails": str(e)
}
def align_components(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Align multiple components along a line or distribute them evenly"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
references = params.get("references", [])
alignment = params.get("alignment", "horizontal") # horizontal, vertical, or edge
distribution = params.get("distribution", "none") # none, equal, or spacing
spacing = params.get("spacing")
if not references or len(references) < 2:
return {
"success": False,
"message": "Missing references",
"errorDetails": "At least two component references are required"
}
# Find all referenced components
components = []
for ref in references:
module = self.board.FindFootprintByReference(ref)
if not module:
return {
"success": False,
"message": "Component not found",
"errorDetails": f"Could not find component: {ref}"
}
components.append(module)
# Perform alignment based on selected option
if alignment == "horizontal":
self._align_components_horizontally(components, distribution, spacing)
elif alignment == "vertical":
self._align_components_vertically(components, distribution, spacing)
elif alignment == "edge":
edge = params.get("edge")
if not edge:
return {
"success": False,
"message": "Missing edge parameter",
"errorDetails": "Edge parameter is required for edge alignment"
}
self._align_components_to_edge(components, edge)
else:
return {
"success": False,
"message": "Invalid alignment option",
"errorDetails": "Alignment must be 'horizontal', 'vertical', or 'edge'"
}
# Prepare result data
aligned_components = []
for module in components:
pos = module.GetPosition()
aligned_components.append({
"reference": module.GetReference(),
"position": {
"x": pos.x / 1000000,
"y": pos.y / 1000000,
"unit": "mm"
},
"rotation": module.GetOrientation().AsDegrees()
})
return {
"success": True,
"message": f"Aligned {len(components)} components",
"alignment": alignment,
"distribution": distribution,
"components": aligned_components
}
except Exception as e:
logger.error(f"Error aligning components: {str(e)}")
return {
"success": False,
"message": "Failed to align components",
"errorDetails": str(e)
}
def duplicate_component(self, params: Dict[str, Any]) -> Dict[str, Any]:
"""Duplicate an existing component"""
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
reference = params.get("reference")
new_reference = params.get("newReference")
position = params.get("position")
rotation = params.get("rotation")
if not reference or not new_reference:
return {
"success": False,
"message": "Missing parameters",
"errorDetails": "reference and newReference are required"
}
# Find the source component
source = self.board.FindFootprintByReference(reference)
if not source:
return {
"success": False,
"message": "Component not found",
"errorDetails": f"Could not find component: {reference}"
}
# Check if new reference already exists
if self.board.FindFootprintByReference(new_reference):
return {
"success": False,
"message": "Reference already exists",
"errorDetails": f"A component with reference {new_reference} already exists"
}
# Create new footprint with the same properties
new_module = pcbnew.FOOTPRINT(self.board)
new_module.SetFootprintName(source.GetFPIDAsString())
new_module.SetValue(source.GetValue())
new_module.SetReference(new_reference)
new_module.SetLayer(source.GetLayer())
# Copy pads and other items
for pad in source.Pads():
new_pad = pcbnew.PAD(new_module)
new_pad.Copy(pad)
new_module.Add(new_pad)
# Set position if provided, otherwise use offset from original
if position:
scale = 1000000 if position.get("unit", "mm") == "mm" else 25400000
x_nm = int(position["x"] * scale)
y_nm = int(position["y"] * scale)
new_module.SetPosition(pcbnew.VECTOR2I(x_nm, y_nm))
else:
# Offset by 5mm
source_pos = source.GetPosition()
new_module.SetPosition(pcbnew.VECTOR2I(source_pos.x + 5000000, source_pos.y))
# Set rotation if provided, otherwise use same as original
if rotation is not None:
rotation_angle = pcbnew.EDA_ANGLE(rotation, pcbnew.DEGREES_T)
new_module.SetOrientation(rotation_angle)
else:
new_module.SetOrientation(source.GetOrientation())
# Add to board
self.board.Add(new_module)
# Get final position in mm
pos = new_module.GetPosition()
return {
"success": True,
"message": f"Duplicated component {reference} to {new_reference}",
"component": {
"reference": new_reference,
"value": new_module.GetValue(),
"footprint": new_module.GetFPIDAsString(),
"position": {
"x": pos.x / 1000000,
"y": pos.y / 1000000,
"unit": "mm"
},
"rotation": new_module.GetOrientation().AsDegrees(),
"layer": self.board.GetLayerName(new_module.GetLayer())
}
}
except Exception as e:
logger.error(f"Error duplicating component: {str(e)}")
return {
"success": False,
"message": "Failed to duplicate component",
"errorDetails": str(e)
}
def _place_grid_array(self, component_id: str, start_position: Dict[str, Any],
rows: int, columns: int, spacing_x: float, spacing_y: float,
reference_prefix: str, value: str, rotation: float, layer: str) -> List[Dict[str, Any]]:
"""Place components in a grid pattern and return the list of placed components"""
placed = []
# Convert spacing to nm
unit = start_position.get("unit", "mm")
scale = 1000000 if unit == "mm" else 25400000 # mm or inch to nm
spacing_x_nm = int(spacing_x * scale)
spacing_y_nm = int(spacing_y * scale)
# Get layer ID
layer_id = self.board.GetLayerID(layer)
for row in range(rows):
for col in range(columns):
# Calculate position
x = start_position["x"] + (col * spacing_x)
y = start_position["y"] + (row * spacing_y)
# Generate reference
index = row * columns + col + 1
component_reference = f"{reference_prefix}{index}"
# Place component
result = self.place_component({
"componentId": component_id,
"position": {"x": x, "y": y, "unit": unit},
"reference": component_reference,
"value": value,
"rotation": rotation,
"layer": layer
})
if result["success"]:
placed.append(result["component"])
return placed
def _place_circular_array(self, component_id: str, center: Dict[str, Any],
radius: float, count: int, angle_start: float,
angle_step: float, reference_prefix: str,
value: str, rotation_offset: float, layer: str) -> List[Dict[str, Any]]:
"""Place components in a circular pattern and return the list of placed components"""
placed = []
# Get unit
unit = center.get("unit", "mm")
for i in range(count):
# Calculate angle for this component
angle = angle_start + (i * angle_step)
angle_rad = math.radians(angle)
# Calculate position
x = center["x"] + (radius * math.cos(angle_rad))
y = center["y"] + (radius * math.sin(angle_rad))
# Generate reference
component_reference = f"{reference_prefix}{i+1}"
# Calculate rotation (pointing outward from center)
component_rotation = angle + rotation_offset
# Place component
result = self.place_component({
"componentId": component_id,
"position": {"x": x, "y": y, "unit": unit},
"reference": component_reference,
"value": value,
"rotation": component_rotation,
"layer": layer
})
if result["success"]:
placed.append(result["component"])
return placed
def _align_components_horizontally(self, components: List[pcbnew.FOOTPRINT],
distribution: str, spacing: Optional[float]) -> None:
"""Align components horizontally and optionally distribute them"""
if not components:
return
# Find the average Y coordinate
y_sum = sum(module.GetPosition().y for module in components)
y_avg = y_sum // len(components)
# Sort components by X position
components.sort(key=lambda m: m.GetPosition().x)
# Set Y coordinate for all components
for module in components:
pos = module.GetPosition()
module.SetPosition(pcbnew.VECTOR2I(pos.x, y_avg))
# Handle distribution if requested
if distribution == "equal" and len(components) > 1:
# Get leftmost and rightmost X coordinates
x_min = components[0].GetPosition().x
x_max = components[-1].GetPosition().x
# Calculate equal spacing
total_space = x_max - x_min
spacing_nm = total_space // (len(components) - 1)
# Set X positions with equal spacing
for i in range(1, len(components) - 1):
pos = components[i].GetPosition()
new_x = x_min + (i * spacing_nm)
components[i].SetPosition(pcbnew.VECTOR2I(new_x, pos.y))
elif distribution == "spacing" and spacing is not None:
# Convert spacing to nanometers
spacing_nm = int(spacing * 1000000) # assuming mm
# Set X positions with the specified spacing
x_current = components[0].GetPosition().x
for i in range(1, len(components)):
pos = components[i].GetPosition()
x_current += spacing_nm
components[i].SetPosition(pcbnew.VECTOR2I(x_current, pos.y))
def _align_components_vertically(self, components: List[pcbnew.FOOTPRINT],
distribution: str, spacing: Optional[float]) -> None:
"""Align components vertically and optionally distribute them"""
if not components:
return
# Find the average X coordinate
x_sum = sum(module.GetPosition().x for module in components)
x_avg = x_sum // len(components)
# Sort components by Y position
components.sort(key=lambda m: m.GetPosition().y)
# Set X coordinate for all components
for module in components:
pos = module.GetPosition()
module.SetPosition(pcbnew.VECTOR2I(x_avg, pos.y))
# Handle distribution if requested
if distribution == "equal" and len(components) > 1:
# Get topmost and bottommost Y coordinates
y_min = components[0].GetPosition().y
y_max = components[-1].GetPosition().y
# Calculate equal spacing
total_space = y_max - y_min
spacing_nm = total_space // (len(components) - 1)
# Set Y positions with equal spacing
for i in range(1, len(components) - 1):
pos = components[i].GetPosition()
new_y = y_min + (i * spacing_nm)
components[i].SetPosition(pcbnew.VECTOR2I(pos.x, new_y))
elif distribution == "spacing" and spacing is not None:
# Convert spacing to nanometers
spacing_nm = int(spacing * 1000000) # assuming mm
# Set Y positions with the specified spacing
y_current = components[0].GetPosition().y
for i in range(1, len(components)):
pos = components[i].GetPosition()
y_current += spacing_nm
components[i].SetPosition(pcbnew.VECTOR2I(pos.x, y_current))
def _align_components_to_edge(self, components: List[pcbnew.FOOTPRINT], edge: str) -> None:
"""Align components to the specified edge of the board"""
if not components:
return
# Get board bounds
board_box = self.board.GetBoardEdgesBoundingBox()
left = board_box.GetLeft()
right = board_box.GetRight()
top = board_box.GetTop()
bottom = board_box.GetBottom()
# Align based on specified edge
if edge == "left":
for module in components:
pos = module.GetPosition()
module.SetPosition(pcbnew.VECTOR2I(left + 2000000, pos.y)) # 2mm offset from edge
elif edge == "right":
for module in components:
pos = module.GetPosition()
module.SetPosition(pcbnew.VECTOR2I(right - 2000000, pos.y)) # 2mm offset from edge
elif edge == "top":
for module in components:
pos = module.GetPosition()
module.SetPosition(pcbnew.VECTOR2I(pos.x, top + 2000000)) # 2mm offset from edge
elif edge == "bottom":
for module in components:
pos = module.GetPosition()
module.SetPosition(pcbnew.VECTOR2I(pos.x, bottom - 2000000)) # 2mm offset from edge
else:
logger.warning(f"Unknown edge alignment: {edge}")
```
--------------------------------------------------------------------------------
/python/kicad_api/ipc_backend.py:
--------------------------------------------------------------------------------
```python
"""
IPC API Backend (KiCAD 9.0+)
Uses the official kicad-python library for inter-process communication
with a running KiCAD instance. This enables REAL-TIME UI synchronization.
Note: Requires KiCAD to be running with IPC server enabled:
Preferences > Plugins > Enable IPC API Server
Key Benefits over SWIG:
- Changes appear instantly in KiCAD UI (no reload needed)
- Transaction support for undo/redo
- Stable API that won't break between versions
- Multi-language support
"""
import logging
import os
from pathlib import Path
from typing import Optional, Dict, Any, List, Callable
from kicad_api.base import (
KiCADBackend,
BoardAPI,
ConnectionError,
APINotAvailableError
)
logger = logging.getLogger(__name__)
# Unit conversion constant: KiCAD IPC uses nanometers internally
MM_TO_NM = 1_000_000
INCH_TO_NM = 25_400_000
class IPCBackend(KiCADBackend):
"""
KiCAD IPC API backend for real-time UI synchronization.
Communicates with KiCAD via Protocol Buffers over UNIX sockets.
Requires KiCAD 9.0+ to be running with IPC enabled.
Changes made through this backend appear immediately in the KiCAD UI
without requiring manual reload.
"""
def __init__(self):
self._kicad = None
self._connected = False
self._version = None
self._on_change_callbacks: List[Callable] = []
def connect(self, socket_path: Optional[str] = None) -> bool:
"""
Connect to running KiCAD instance via IPC.
Args:
socket_path: Optional socket path. If not provided, will try common locations.
Use format: ipc:///tmp/kicad/api.sock
Returns:
True if connection successful
Raises:
ConnectionError: If connection fails
"""
try:
# Import here to allow module to load even without kicad-python
from kipy import KiCad
logger.info("Connecting to KiCAD via IPC...")
# Try to connect with provided path or auto-detect
socket_paths_to_try = []
if socket_path:
socket_paths_to_try.append(socket_path)
else:
# Common socket locations
socket_paths_to_try = [
'ipc:///tmp/kicad/api.sock', # Linux default
f'ipc:///run/user/{os.getuid()}/kicad/api.sock', # XDG runtime
None # Let kipy auto-detect
]
last_error = None
for path in socket_paths_to_try:
try:
if path:
logger.debug(f"Trying socket path: {path}")
self._kicad = KiCad(socket_path=path)
else:
logger.debug("Trying auto-detection")
self._kicad = KiCad()
# Verify connection with ping (ping returns None on success)
self._kicad.ping()
logger.info(f"Connected via socket: {path or 'auto-detected'}")
break
except Exception as e:
last_error = e
logger.debug(f"Failed to connect via {path}: {e}")
continue
else:
# None of the paths worked
raise ConnectionError(f"Could not connect to KiCAD IPC: {last_error}")
# Get version info
self._version = self._get_kicad_version()
logger.info(f"Connected to KiCAD {self._version} via IPC")
self._connected = True
return True
except ImportError as e:
logger.error("kicad-python library not found")
raise APINotAvailableError(
"IPC backend requires kicad-python. "
"Install with: pip install kicad-python"
) from e
except Exception as e:
logger.error(f"Failed to connect via IPC: {e}")
logger.info(
"Ensure KiCAD is running with IPC enabled: "
"Preferences > Plugins > Enable IPC API Server"
)
raise ConnectionError(f"IPC connection failed: {e}") from e
def _get_kicad_version(self) -> str:
"""Get KiCAD version string."""
try:
if self._kicad.check_version():
return self._kicad.get_api_version()
return "9.0+ (version mismatch)"
except Exception:
return "unknown"
def disconnect(self) -> None:
"""Disconnect from KiCAD."""
if self._kicad:
self._kicad = None
self._connected = False
logger.info("Disconnected from KiCAD IPC")
def is_connected(self) -> bool:
"""Check if connected to KiCAD."""
if not self._connected or not self._kicad:
return False
try:
# ping() returns None on success, raises on failure
self._kicad.ping()
return True
except Exception:
self._connected = False
return False
def get_version(self) -> str:
"""Get KiCAD version."""
return self._version or "unknown"
def register_change_callback(self, callback: Callable) -> None:
"""Register a callback to be called when changes are made."""
self._on_change_callbacks.append(callback)
def _notify_change(self, change_type: str, details: Dict[str, Any]) -> None:
"""Notify registered callbacks of a change."""
for callback in self._on_change_callbacks:
try:
callback(change_type, details)
except Exception as e:
logger.warning(f"Change callback error: {e}")
# Project Operations
def create_project(self, path: Path, name: str) -> Dict[str, Any]:
"""
Create a new KiCAD project.
Note: The IPC API doesn't directly create projects.
Projects must be created through the UI or file system.
"""
if not self.is_connected():
raise ConnectionError("Not connected to KiCAD")
# IPC API doesn't have project creation - use file-based approach
logger.warning("Project creation via IPC not fully supported - using hybrid approach")
# For now, we'll return info about what needs to happen
return {
"success": False,
"message": "Direct project creation not supported via IPC",
"suggestion": "Open KiCAD and create a new project, or use SWIG backend"
}
def open_project(self, path: Path) -> Dict[str, Any]:
"""Open existing project via IPC."""
if not self.is_connected():
raise ConnectionError("Not connected to KiCAD")
try:
# Check for open documents
documents = self._kicad.get_open_documents()
# Look for matching project
path_str = str(path)
for doc in documents:
if path_str in str(doc):
return {
"success": True,
"message": f"Project already open: {path}",
"path": str(path)
}
return {
"success": False,
"message": "Project not currently open in KiCAD",
"suggestion": "Open the project in KiCAD first, then connect via IPC"
}
except Exception as e:
logger.error(f"Failed to check project: {e}")
return {
"success": False,
"message": "Failed to check project",
"errorDetails": str(e)
}
def save_project(self, path: Optional[Path] = None) -> Dict[str, Any]:
"""Save current project via IPC."""
if not self.is_connected():
raise ConnectionError("Not connected to KiCAD")
try:
board = self._kicad.get_board()
if path:
board.save_as(str(path))
else:
board.save()
self._notify_change("save", {"path": str(path) if path else "current"})
return {
"success": True,
"message": "Project saved successfully"
}
except Exception as e:
logger.error(f"Failed to save project: {e}")
return {
"success": False,
"message": "Failed to save project",
"errorDetails": str(e)
}
def close_project(self) -> None:
"""Close current project (not supported via IPC)."""
logger.warning("Closing projects via IPC is not supported")
# Board Operations
def get_board(self) -> BoardAPI:
"""Get board API for real-time manipulation."""
if not self.is_connected():
raise ConnectionError("Not connected to KiCAD")
return IPCBoardAPI(self._kicad, self._notify_change)
class IPCBoardAPI(BoardAPI):
"""
Board API implementation for IPC backend.
All changes made through this API appear immediately in the KiCAD UI.
Uses transactions for proper undo/redo support.
"""
def __init__(self, kicad_instance, notify_callback: Callable):
self._kicad = kicad_instance
self._board = None
self._notify = notify_callback
self._current_commit = None
def _get_board(self):
"""Get board instance, connecting if needed."""
if self._board is None:
try:
self._board = self._kicad.get_board()
except Exception as e:
logger.error(f"Failed to get board: {e}")
raise ConnectionError(f"No board open in KiCAD: {e}")
return self._board
def begin_transaction(self, description: str = "MCP Operation") -> None:
"""Begin a transaction for grouping operations into a single undo step."""
board = self._get_board()
self._current_commit = board.begin_commit()
logger.debug(f"Started transaction: {description}")
def commit_transaction(self, description: str = "MCP Operation") -> None:
"""Commit the current transaction."""
if self._current_commit:
board = self._get_board()
board.push_commit(self._current_commit, description)
self._current_commit = None
logger.debug(f"Committed transaction: {description}")
def rollback_transaction(self) -> None:
"""Roll back the current transaction."""
if self._current_commit:
board = self._get_board()
board.drop_commit(self._current_commit)
self._current_commit = None
logger.debug("Rolled back transaction")
def save(self) -> bool:
"""Save the board immediately."""
try:
board = self._get_board()
board.save()
self._notify("save", {})
return True
except Exception as e:
logger.error(f"Failed to save board: {e}")
return False
def set_size(self, width: float, height: float, unit: str = "mm") -> bool:
"""
Set board size.
Note: Board size in KiCAD is typically defined by the board outline,
not a direct size property. This method may need to create/modify
the board outline.
"""
try:
from kipy.board_types import BoardRectangle
from kipy.geometry import Vector2
from kipy.util.units import from_mm
from kipy.proto.board.board_types_pb2 import BoardLayer
board = self._get_board()
# Convert to nm
if unit == "mm":
w = from_mm(width)
h = from_mm(height)
else:
w = int(width * INCH_TO_NM)
h = int(height * INCH_TO_NM)
# Create board outline rectangle on Edge.Cuts layer
rect = BoardRectangle()
rect.start = Vector2.from_xy(0, 0)
rect.end = Vector2.from_xy(w, h)
rect.layer = BoardLayer.BL_Edge_Cuts
rect.width = from_mm(0.1) # Standard edge cut width
# Begin transaction for undo support
commit = board.begin_commit()
board.create_items(rect)
board.push_commit(commit, f"Set board size to {width}x{height} {unit}")
self._notify("board_size", {"width": width, "height": height, "unit": unit})
return True
except Exception as e:
logger.error(f"Failed to set board size: {e}")
return False
def get_size(self) -> Dict[str, float]:
"""Get current board size from bounding box."""
try:
board = self._get_board()
# Get shapes on Edge.Cuts layer to determine board size
shapes = board.get_shapes()
if not shapes:
return {"width": 0, "height": 0, "unit": "mm"}
# Find bounding box of edge cuts
from kipy.util.units import to_mm
min_x = min_y = float('inf')
max_x = max_y = float('-inf')
for shape in shapes:
# Check if on Edge.Cuts layer
bbox = board.get_item_bounding_box(shape)
if bbox:
min_x = min(min_x, bbox.min.x)
min_y = min(min_y, bbox.min.y)
max_x = max(max_x, bbox.max.x)
max_y = max(max_y, bbox.max.y)
if min_x == float('inf'):
return {"width": 0, "height": 0, "unit": "mm"}
return {
"width": to_mm(max_x - min_x),
"height": to_mm(max_y - min_y),
"unit": "mm"
}
except Exception as e:
logger.error(f"Failed to get board size: {e}")
return {"width": 0, "height": 0, "unit": "mm", "error": str(e)}
def add_layer(self, layer_name: str, layer_type: str) -> bool:
"""Add layer to the board (layers are typically predefined in KiCAD)."""
logger.warning("Layer management via IPC is limited - layers are predefined")
return False
def get_enabled_layers(self) -> List[str]:
"""Get list of enabled layers."""
try:
board = self._get_board()
layers = board.get_enabled_layers()
return [str(layer) for layer in layers]
except Exception as e:
logger.error(f"Failed to get enabled layers: {e}")
return []
def list_components(self) -> List[Dict[str, Any]]:
"""List all components (footprints) on the board."""
try:
from kipy.util.units import to_mm
board = self._get_board()
footprints = board.get_footprints()
components = []
for fp in footprints:
try:
pos = fp.position
components.append({
"reference": fp.reference_field.text.value if fp.reference_field else "",
"value": fp.value_field.text.value if fp.value_field else "",
"footprint": str(fp.definition.library_link) if fp.definition else "",
"position": {
"x": to_mm(pos.x) if pos else 0,
"y": to_mm(pos.y) if pos else 0,
"unit": "mm"
},
"rotation": fp.orientation.degrees if fp.orientation else 0,
"layer": str(fp.layer) if hasattr(fp, 'layer') else "F.Cu",
"id": str(fp.id) if hasattr(fp, 'id') else ""
})
except Exception as e:
logger.warning(f"Error processing footprint: {e}")
continue
return components
except Exception as e:
logger.error(f"Failed to list components: {e}")
return []
def place_component(
self,
reference: str,
footprint: str,
x: float,
y: float,
rotation: float = 0,
layer: str = "F.Cu",
value: str = ""
) -> bool:
"""
Place a component on the board.
The component appears immediately in the KiCAD UI.
This method uses a hybrid approach:
1. Load the footprint definition from the library using pcbnew (SWIG)
2. Place it on the board via IPC for real-time UI updates
Args:
reference: Component reference designator (e.g., "R1", "U1")
footprint: Footprint path in format "Library:FootprintName" or just "FootprintName"
x: X position in mm
y: Y position in mm
rotation: Rotation angle in degrees
layer: Layer name ("F.Cu" for top, "B.Cu" for bottom)
value: Component value (optional)
"""
try:
# First, try to load the footprint from library using pcbnew SWIG
loaded_fp = self._load_footprint_from_library(footprint)
if loaded_fp:
# We have the footprint from the library - place it via SWIG
# then sync to IPC for UI update
return self._place_loaded_footprint(
loaded_fp, reference, x, y, rotation, layer, value
)
else:
# Fallback: Create a basic placeholder footprint via IPC
logger.warning(f"Could not load footprint '{footprint}' from library, creating placeholder")
return self._place_placeholder_footprint(
reference, footprint, x, y, rotation, layer, value
)
except Exception as e:
logger.error(f"Failed to place component: {e}")
return False
def _load_footprint_from_library(self, footprint_path: str):
"""
Load a footprint from the library using pcbnew SWIG API.
Args:
footprint_path: Either "Library:FootprintName" or just "FootprintName"
Returns:
pcbnew.FOOTPRINT object or None if not found
"""
try:
import pcbnew
# Parse library and footprint name
if ':' in footprint_path:
lib_name, fp_name = footprint_path.split(':', 1)
else:
# Try to find the footprint in all libraries
lib_name = None
fp_name = footprint_path
# Get the footprint library table
fp_lib_table = pcbnew.GetGlobalFootprintLib()
if lib_name:
# Load from specific library
try:
loaded_fp = pcbnew.FootprintLoad(fp_lib_table, lib_name, fp_name)
if loaded_fp:
logger.info(f"Loaded footprint '{fp_name}' from library '{lib_name}'")
return loaded_fp
except Exception as e:
logger.warning(f"Could not load from {lib_name}: {e}")
else:
# Search all libraries for the footprint
lib_names = fp_lib_table.GetLogicalLibs()
for lib in lib_names:
try:
loaded_fp = pcbnew.FootprintLoad(fp_lib_table, lib, fp_name)
if loaded_fp:
logger.info(f"Found footprint '{fp_name}' in library '{lib}'")
return loaded_fp
except:
continue
logger.warning(f"Footprint '{footprint_path}' not found in any library")
return None
except ImportError:
logger.warning("pcbnew not available - cannot load footprints from library")
return None
except Exception as e:
logger.error(f"Error loading footprint from library: {e}")
return None
def _place_loaded_footprint(
self,
loaded_fp,
reference: str,
x: float,
y: float,
rotation: float,
layer: str,
value: str
) -> bool:
"""
Place a loaded pcbnew footprint onto the board.
Uses SWIG to add the footprint, then notifies for IPC sync.
"""
try:
import pcbnew
# Get the board file path from IPC to load via pcbnew
board = self._get_board()
# Get the pcbnew board instance
# We need to get the actual board file path
project = board.get_project()
board_path = None
# Try to get the board path from kipy
try:
docs = self._kicad.get_open_documents()
for doc in docs:
if hasattr(doc, 'path') and str(doc.path).endswith('.kicad_pcb'):
board_path = str(doc.path)
break
except Exception as e:
logger.debug(f"Could not get board path from IPC: {e}")
if board_path and os.path.exists(board_path):
# Load board via pcbnew
pcb_board = pcbnew.LoadBoard(board_path)
else:
# Try to get from pcbnew directly
pcb_board = pcbnew.GetBoard()
if not pcb_board:
logger.error("Could not get pcbnew board instance")
return self._place_placeholder_footprint(
reference, "", x, y, rotation, layer, value
)
# Set footprint position and properties
scale = MM_TO_NM
loaded_fp.SetPosition(pcbnew.VECTOR2I(int(x * scale), int(y * scale)))
loaded_fp.SetOrientationDegrees(rotation)
# Set reference
loaded_fp.SetReference(reference)
# Set value if provided
if value:
loaded_fp.SetValue(value)
# Set layer (flip if bottom)
if layer == "B.Cu":
if not loaded_fp.IsFlipped():
loaded_fp.Flip(loaded_fp.GetPosition(), False)
# Add to board
pcb_board.Add(loaded_fp)
# Save the board so IPC can see the changes
pcbnew.SaveBoard(board_path, pcb_board)
# Refresh IPC view
try:
board.revert() # Reload from disk to sync IPC
except Exception as e:
logger.debug(f"Could not refresh IPC board: {e}")
self._notify("component_placed", {
"reference": reference,
"footprint": loaded_fp.GetFPIDAsString(),
"position": {"x": x, "y": y},
"rotation": rotation,
"layer": layer,
"loaded_from_library": True
})
logger.info(f"Placed component {reference} ({loaded_fp.GetFPIDAsString()}) at ({x}, {y}) mm")
return True
except Exception as e:
logger.error(f"Error placing loaded footprint: {e}")
# Fall back to placeholder
return self._place_placeholder_footprint(
reference, "", x, y, rotation, layer, value
)
def _place_placeholder_footprint(
self,
reference: str,
footprint: str,
x: float,
y: float,
rotation: float,
layer: str,
value: str
) -> bool:
"""
Place a placeholder footprint when library loading fails.
Creates a basic footprint via IPC with just reference/value fields.
"""
try:
from kipy.board_types import Footprint
from kipy.geometry import Vector2, Angle
from kipy.util.units import from_mm
from kipy.proto.board.board_types_pb2 import BoardLayer
board = self._get_board()
# Create footprint
fp = Footprint()
fp.position = Vector2.from_xy(from_mm(x), from_mm(y))
fp.orientation = Angle.from_degrees(rotation)
# Set layer
if layer == "B.Cu":
fp.layer = BoardLayer.BL_B_Cu
else:
fp.layer = BoardLayer.BL_F_Cu
# Set reference and value
if fp.reference_field:
fp.reference_field.text.value = reference
if fp.value_field:
fp.value_field.text.value = value if value else footprint
# Begin transaction
commit = board.begin_commit()
board.create_items(fp)
board.push_commit(commit, f"Placed component {reference}")
self._notify("component_placed", {
"reference": reference,
"footprint": footprint,
"position": {"x": x, "y": y},
"rotation": rotation,
"layer": layer,
"loaded_from_library": False,
"is_placeholder": True
})
logger.info(f"Placed placeholder component {reference} at ({x}, {y}) mm")
return True
except Exception as e:
logger.error(f"Failed to place placeholder component: {e}")
return False
def move_component(self, reference: str, x: float, y: float, rotation: Optional[float] = None) -> bool:
"""Move a component to a new position (updates UI immediately)."""
try:
from kipy.geometry import Vector2, Angle
from kipy.util.units import from_mm
board = self._get_board()
footprints = board.get_footprints()
# Find the footprint by reference
target_fp = None
for fp in footprints:
if fp.reference_field and fp.reference_field.text.value == reference:
target_fp = fp
break
if not target_fp:
logger.error(f"Component not found: {reference}")
return False
# Update position
target_fp.position = Vector2.from_xy(from_mm(x), from_mm(y))
if rotation is not None:
target_fp.orientation = Angle.from_degrees(rotation)
# Apply changes
commit = board.begin_commit()
board.update_items([target_fp])
board.push_commit(commit, f"Moved component {reference}")
self._notify("component_moved", {
"reference": reference,
"position": {"x": x, "y": y},
"rotation": rotation
})
return True
except Exception as e:
logger.error(f"Failed to move component: {e}")
return False
def delete_component(self, reference: str) -> bool:
"""Delete a component from the board."""
try:
board = self._get_board()
footprints = board.get_footprints()
# Find the footprint by reference
target_fp = None
for fp in footprints:
if fp.reference_field and fp.reference_field.text.value == reference:
target_fp = fp
break
if not target_fp:
logger.error(f"Component not found: {reference}")
return False
# Remove component
commit = board.begin_commit()
board.remove_items([target_fp])
board.push_commit(commit, f"Deleted component {reference}")
self._notify("component_deleted", {"reference": reference})
return True
except Exception as e:
logger.error(f"Failed to delete component: {e}")
return False
def add_track(
self,
start_x: float,
start_y: float,
end_x: float,
end_y: float,
width: float = 0.25,
layer: str = "F.Cu",
net_name: Optional[str] = None
) -> bool:
"""
Add a track (trace) to the board.
The track appears immediately in the KiCAD UI.
"""
try:
from kipy.board_types import Track
from kipy.geometry import Vector2
from kipy.util.units import from_mm
from kipy.proto.board.board_types_pb2 import BoardLayer
board = self._get_board()
# Create track
track = Track()
track.start = Vector2.from_xy(from_mm(start_x), from_mm(start_y))
track.end = Vector2.from_xy(from_mm(end_x), from_mm(end_y))
track.width = from_mm(width)
# Set layer
layer_map = {
"F.Cu": BoardLayer.BL_F_Cu,
"B.Cu": BoardLayer.BL_B_Cu,
"In1.Cu": BoardLayer.BL_In1_Cu,
"In2.Cu": BoardLayer.BL_In2_Cu,
}
track.layer = layer_map.get(layer, BoardLayer.BL_F_Cu)
# Set net if specified
if net_name:
nets = board.get_nets()
for net in nets:
if net.name == net_name:
track.net = net
break
# Add track with transaction
commit = board.begin_commit()
board.create_items(track)
board.push_commit(commit, "Added track")
self._notify("track_added", {
"start": {"x": start_x, "y": start_y},
"end": {"x": end_x, "y": end_y},
"width": width,
"layer": layer,
"net": net_name
})
logger.info(f"Added track from ({start_x}, {start_y}) to ({end_x}, {end_y}) mm")
return True
except Exception as e:
logger.error(f"Failed to add track: {e}")
return False
def add_via(
self,
x: float,
y: float,
diameter: float = 0.8,
drill: float = 0.4,
net_name: Optional[str] = None,
via_type: str = "through"
) -> bool:
"""
Add a via to the board.
The via appears immediately in the KiCAD UI.
"""
try:
from kipy.board_types import Via
from kipy.geometry import Vector2
from kipy.util.units import from_mm
from kipy.proto.board.board_types_pb2 import ViaType
board = self._get_board()
# Create via
via = Via()
via.position = Vector2.from_xy(from_mm(x), from_mm(y))
via.diameter = from_mm(diameter)
via.drill_diameter = from_mm(drill)
# Set via type (enum values: VT_THROUGH=1, VT_BLIND_BURIED=2, VT_MICRO=3)
type_map = {
"through": ViaType.VT_THROUGH,
"blind": ViaType.VT_BLIND_BURIED,
"micro": ViaType.VT_MICRO,
}
via.type = type_map.get(via_type, ViaType.VT_THROUGH)
# Set net if specified
if net_name:
nets = board.get_nets()
for net in nets:
if net.name == net_name:
via.net = net
break
# Add via with transaction
commit = board.begin_commit()
board.create_items(via)
board.push_commit(commit, "Added via")
self._notify("via_added", {
"position": {"x": x, "y": y},
"diameter": diameter,
"drill": drill,
"net": net_name,
"type": via_type
})
logger.info(f"Added via at ({x}, {y}) mm")
return True
except Exception as e:
logger.error(f"Failed to add via: {e}")
return False
def add_text(
self,
text: str,
x: float,
y: float,
layer: str = "F.SilkS",
size: float = 1.0,
rotation: float = 0
) -> bool:
"""Add text to the board."""
try:
from kipy.board_types import BoardText
from kipy.geometry import Vector2, Angle
from kipy.util.units import from_mm
from kipy.proto.board.board_types_pb2 import BoardLayer
board = self._get_board()
# Create text
board_text = BoardText()
board_text.value = text
board_text.position = Vector2.from_xy(from_mm(x), from_mm(y))
board_text.angle = Angle.from_degrees(rotation)
# Set layer
layer_map = {
"F.SilkS": BoardLayer.BL_F_SilkS,
"B.SilkS": BoardLayer.BL_B_SilkS,
"F.Cu": BoardLayer.BL_F_Cu,
"B.Cu": BoardLayer.BL_B_Cu,
}
board_text.layer = layer_map.get(layer, BoardLayer.BL_F_SilkS)
# Add text with transaction
commit = board.begin_commit()
board.create_items(board_text)
board.push_commit(commit, f"Added text: {text}")
self._notify("text_added", {
"text": text,
"position": {"x": x, "y": y},
"layer": layer
})
return True
except Exception as e:
logger.error(f"Failed to add text: {e}")
return False
def get_tracks(self) -> List[Dict[str, Any]]:
"""Get all tracks on the board."""
try:
from kipy.util.units import to_mm
board = self._get_board()
tracks = board.get_tracks()
result = []
for track in tracks:
try:
result.append({
"start": {
"x": to_mm(track.start.x),
"y": to_mm(track.start.y)
},
"end": {
"x": to_mm(track.end.x),
"y": to_mm(track.end.y)
},
"width": to_mm(track.width),
"layer": str(track.layer),
"net": track.net.name if track.net else "",
"id": str(track.id) if hasattr(track, 'id') else ""
})
except Exception as e:
logger.warning(f"Error processing track: {e}")
continue
return result
except Exception as e:
logger.error(f"Failed to get tracks: {e}")
return []
def get_vias(self) -> List[Dict[str, Any]]:
"""Get all vias on the board."""
try:
from kipy.util.units import to_mm
board = self._get_board()
vias = board.get_vias()
result = []
for via in vias:
try:
result.append({
"position": {
"x": to_mm(via.position.x),
"y": to_mm(via.position.y)
},
"diameter": to_mm(via.diameter),
"drill": to_mm(via.drill_diameter),
"net": via.net.name if via.net else "",
"type": str(via.type),
"id": str(via.id) if hasattr(via, 'id') else ""
})
except Exception as e:
logger.warning(f"Error processing via: {e}")
continue
return result
except Exception as e:
logger.error(f"Failed to get vias: {e}")
return []
def get_nets(self) -> List[Dict[str, Any]]:
"""Get all nets on the board."""
try:
board = self._get_board()
nets = board.get_nets()
result = []
for net in nets:
try:
result.append({
"name": net.name,
"code": net.code if hasattr(net, 'code') else 0
})
except Exception as e:
logger.warning(f"Error processing net: {e}")
continue
return result
except Exception as e:
logger.error(f"Failed to get nets: {e}")
return []
def add_zone(
self,
points: List[Dict[str, float]],
layer: str = "F.Cu",
net_name: Optional[str] = None,
clearance: float = 0.5,
min_thickness: float = 0.25,
priority: int = 0,
fill_mode: str = "solid",
name: str = ""
) -> bool:
"""
Add a copper pour zone to the board.
The zone appears immediately in the KiCAD UI.
Args:
points: List of points defining the zone outline, e.g. [{"x": 0, "y": 0}, ...]
layer: Layer name (F.Cu, B.Cu, etc.)
net_name: Net to connect the zone to (e.g., "GND")
clearance: Clearance from other copper in mm
min_thickness: Minimum copper thickness in mm
priority: Zone priority (higher = fills first)
fill_mode: "solid" or "hatched"
name: Optional zone name
"""
try:
from kipy.board_types import Zone, ZoneFillMode, ZoneType
from kipy.geometry import PolyLine, PolyLineNode, Vector2
from kipy.util.units import from_mm
from kipy.proto.board.board_types_pb2 import BoardLayer
board = self._get_board()
if len(points) < 3:
logger.error("Zone requires at least 3 points")
return False
# Create zone
zone = Zone()
zone.type = ZoneType.ZT_COPPER
# Set layer
layer_map = {
"F.Cu": BoardLayer.BL_F_Cu,
"B.Cu": BoardLayer.BL_B_Cu,
"In1.Cu": BoardLayer.BL_In1_Cu,
"In2.Cu": BoardLayer.BL_In2_Cu,
"In3.Cu": BoardLayer.BL_In3_Cu,
"In4.Cu": BoardLayer.BL_In4_Cu,
}
zone.layers = [layer_map.get(layer, BoardLayer.BL_F_Cu)]
# Set net if specified
if net_name:
nets = board.get_nets()
for net in nets:
if net.name == net_name:
zone.net = net
break
# Set zone properties
zone.clearance = from_mm(clearance)
zone.min_thickness = from_mm(min_thickness)
zone.priority = priority
if name:
zone.name = name
# Set fill mode
if fill_mode == "hatched":
zone.fill_mode = ZoneFillMode.ZFM_HATCHED
else:
zone.fill_mode = ZoneFillMode.ZFM_SOLID
# Create outline polyline
outline = PolyLine()
outline.closed = True
for point in points:
x = point.get("x", 0)
y = point.get("y", 0)
node = PolyLineNode.from_xy(from_mm(x), from_mm(y))
outline.append(node)
# Set the outline on the zone
# Note: Zone outline is set via the proto directly since kipy
# doesn't expose a direct setter for creating new zones
zone._proto.outline.polygons.add()
zone._proto.outline.polygons[0].outline.CopyFrom(outline._proto)
# Add zone with transaction
commit = board.begin_commit()
board.create_items(zone)
board.push_commit(commit, f"Added copper zone on {layer}")
self._notify("zone_added", {
"layer": layer,
"net": net_name,
"points": len(points),
"priority": priority
})
logger.info(f"Added zone on {layer} with {len(points)} points")
return True
except Exception as e:
logger.error(f"Failed to add zone: {e}")
return False
def get_zones(self) -> List[Dict[str, Any]]:
"""Get all zones on the board."""
try:
from kipy.util.units import to_mm
board = self._get_board()
zones = board.get_zones()
result = []
for zone in zones:
try:
result.append({
"name": zone.name if hasattr(zone, 'name') else "",
"net": zone.net.name if zone.net else "",
"priority": zone.priority if hasattr(zone, 'priority') else 0,
"layers": [str(l) for l in zone.layers] if hasattr(zone, 'layers') else [],
"filled": zone.filled if hasattr(zone, 'filled') else False,
"id": str(zone.id) if hasattr(zone, 'id') else ""
})
except Exception as e:
logger.warning(f"Error processing zone: {e}")
continue
return result
except Exception as e:
logger.error(f"Failed to get zones: {e}")
return []
def refill_zones(self) -> bool:
"""Refill all copper pour zones."""
try:
board = self._get_board()
board.refill_zones()
self._notify("zones_refilled", {})
return True
except Exception as e:
logger.error(f"Failed to refill zones: {e}")
return False
def get_selection(self) -> List[Dict[str, Any]]:
"""Get currently selected items in the KiCAD UI."""
try:
board = self._get_board()
selection = board.get_selection()
result = []
for item in selection:
result.append({
"type": type(item).__name__,
"id": str(item.id) if hasattr(item, 'id') else ""
})
return result
except Exception as e:
logger.error(f"Failed to get selection: {e}")
return []
def clear_selection(self) -> bool:
"""Clear the current selection in KiCAD UI."""
try:
board = self._get_board()
board.clear_selection()
return True
except Exception as e:
logger.error(f"Failed to clear selection: {e}")
return False
# Export for factory
__all__ = ['IPCBackend', 'IPCBoardAPI']
```
--------------------------------------------------------------------------------
/python/schemas/tool_schemas.py:
--------------------------------------------------------------------------------
```python
"""
Comprehensive tool schema definitions for all KiCAD MCP commands
Following MCP 2025-06-18 specification for tool definitions.
Each tool includes:
- name: Unique identifier
- title: Human-readable display name
- description: Detailed explanation of what the tool does
- inputSchema: JSON Schema for parameters
- outputSchema: Optional JSON Schema for return values (structured content)
"""
from typing import Dict, Any
# =============================================================================
# PROJECT TOOLS
# =============================================================================
PROJECT_TOOLS = [
{
"name": "create_project",
"title": "Create New KiCAD Project",
"description": "Creates a new KiCAD project with PCB board file and optional project configuration. Automatically creates project directory and initializes board with default settings.",
"inputSchema": {
"type": "object",
"properties": {
"projectName": {
"type": "string",
"description": "Name of the project (used for file naming)",
"minLength": 1
},
"path": {
"type": "string",
"description": "Directory path where project will be created (defaults to current working directory)"
},
"template": {
"type": "string",
"description": "Optional path to template board file to copy settings from"
}
},
"required": ["projectName"]
}
},
{
"name": "open_project",
"title": "Open Existing KiCAD Project",
"description": "Opens an existing KiCAD project file (.kicad_pro or .kicad_pcb) and loads the board into memory for manipulation.",
"inputSchema": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Path to .kicad_pro or .kicad_pcb file"
}
},
"required": ["filename"]
}
},
{
"name": "save_project",
"title": "Save Current Project",
"description": "Saves the current board to disk. Can optionally save to a new location.",
"inputSchema": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Optional new path to save the board (if not provided, saves to current location)"
}
}
}
},
{
"name": "get_project_info",
"title": "Get Project Information",
"description": "Retrieves metadata and properties of the currently open project including name, paths, and board status.",
"inputSchema": {
"type": "object",
"properties": {}
}
}
]
# =============================================================================
# BOARD TOOLS
# =============================================================================
BOARD_TOOLS = [
{
"name": "set_board_size",
"title": "Set Board Dimensions",
"description": "Sets the PCB board dimensions. The board outline must be added separately using add_board_outline.",
"inputSchema": {
"type": "object",
"properties": {
"width": {
"type": "number",
"description": "Board width in millimeters",
"minimum": 1
},
"height": {
"type": "number",
"description": "Board height in millimeters",
"minimum": 1
}
},
"required": ["width", "height"]
}
},
{
"name": "add_board_outline",
"title": "Add Board Outline",
"description": "Adds a board outline shape (rectangle, rounded rectangle, circle, or polygon) on the Edge.Cuts layer.",
"inputSchema": {
"type": "object",
"properties": {
"shape": {
"type": "string",
"enum": ["rectangle", "rounded_rectangle", "circle", "polygon"],
"description": "Shape type for the board outline"
},
"width": {
"type": "number",
"description": "Width in mm (for rectangle/rounded_rectangle)",
"minimum": 1
},
"height": {
"type": "number",
"description": "Height in mm (for rectangle/rounded_rectangle)",
"minimum": 1
},
"radius": {
"type": "number",
"description": "Radius in mm (for circle) or corner radius (for rounded_rectangle)",
"minimum": 0
},
"points": {
"type": "array",
"description": "Array of [x, y] coordinates in mm (for polygon)",
"items": {
"type": "array",
"items": {"type": "number"},
"minItems": 2,
"maxItems": 2
},
"minItems": 3
}
},
"required": ["shape"]
}
},
{
"name": "add_layer",
"title": "Add Custom Layer",
"description": "Adds a new custom layer to the board stack (e.g., User.1, User.Comments).",
"inputSchema": {
"type": "object",
"properties": {
"layerName": {
"type": "string",
"description": "Name of the layer to add"
},
"layerType": {
"type": "string",
"enum": ["signal", "power", "mixed", "jumper"],
"description": "Type of layer (for copper layers)"
}
},
"required": ["layerName"]
}
},
{
"name": "set_active_layer",
"title": "Set Active Layer",
"description": "Sets the currently active layer for drawing operations.",
"inputSchema": {
"type": "object",
"properties": {
"layerName": {
"type": "string",
"description": "Name of the layer to make active (e.g., F.Cu, B.Cu, Edge.Cuts)"
}
},
"required": ["layerName"]
}
},
{
"name": "get_layer_list",
"title": "List Board Layers",
"description": "Returns a list of all layers in the board with their properties.",
"inputSchema": {
"type": "object",
"properties": {}
}
},
{
"name": "get_board_info",
"title": "Get Board Information",
"description": "Retrieves comprehensive board information including dimensions, layer count, component count, and design rules.",
"inputSchema": {
"type": "object",
"properties": {}
}
},
{
"name": "get_board_2d_view",
"title": "Render Board Preview",
"description": "Generates a 2D visual representation of the current board state as a PNG image.",
"inputSchema": {
"type": "object",
"properties": {
"width": {
"type": "number",
"description": "Image width in pixels (default: 800)",
"minimum": 100,
"default": 800
},
"height": {
"type": "number",
"description": "Image height in pixels (default: 600)",
"minimum": 100,
"default": 600
}
}
}
},
{
"name": "add_mounting_hole",
"title": "Add Mounting Hole",
"description": "Adds a mounting hole (non-plated through hole) at the specified position with given diameter.",
"inputSchema": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate in millimeters"
},
"y": {
"type": "number",
"description": "Y coordinate in millimeters"
},
"diameter": {
"type": "number",
"description": "Hole diameter in millimeters",
"minimum": 0.1
}
},
"required": ["x", "y", "diameter"]
}
},
{
"name": "add_board_text",
"title": "Add Text to Board",
"description": "Adds text annotation to the board on a specified layer (e.g., F.SilkS for top silkscreen).",
"inputSchema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Text content to add",
"minLength": 1
},
"x": {
"type": "number",
"description": "X coordinate in millimeters"
},
"y": {
"type": "number",
"description": "Y coordinate in millimeters"
},
"layer": {
"type": "string",
"description": "Layer name (e.g., F.SilkS, B.SilkS, F.Cu)",
"default": "F.SilkS"
},
"size": {
"type": "number",
"description": "Text size in millimeters",
"minimum": 0.1,
"default": 1.0
},
"thickness": {
"type": "number",
"description": "Text thickness in millimeters",
"minimum": 0.01,
"default": 0.15
}
},
"required": ["text", "x", "y"]
}
}
]
# =============================================================================
# COMPONENT TOOLS
# =============================================================================
COMPONENT_TOOLS = [
{
"name": "place_component",
"title": "Place Component",
"description": "Places a component with specified footprint at given coordinates on the board.",
"inputSchema": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "Component reference designator (e.g., R1, C2, U3)"
},
"footprint": {
"type": "string",
"description": "Footprint library:name (e.g., Resistor_SMD:R_0805_2012Metric)"
},
"x": {
"type": "number",
"description": "X coordinate in millimeters"
},
"y": {
"type": "number",
"description": "Y coordinate in millimeters"
},
"rotation": {
"type": "number",
"description": "Rotation angle in degrees (0-360)",
"minimum": 0,
"maximum": 360,
"default": 0
},
"layer": {
"type": "string",
"enum": ["F.Cu", "B.Cu"],
"description": "Board layer (top or bottom)",
"default": "F.Cu"
}
},
"required": ["reference", "footprint", "x", "y"]
}
},
{
"name": "move_component",
"title": "Move Component",
"description": "Moves an existing component to a new position on the board.",
"inputSchema": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "Component reference designator"
},
"x": {
"type": "number",
"description": "New X coordinate in millimeters"
},
"y": {
"type": "number",
"description": "New Y coordinate in millimeters"
}
},
"required": ["reference", "x", "y"]
}
},
{
"name": "rotate_component",
"title": "Rotate Component",
"description": "Rotates a component by specified angle. Rotation is cumulative with existing rotation.",
"inputSchema": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "Component reference designator"
},
"angle": {
"type": "number",
"description": "Rotation angle in degrees (positive = counterclockwise)"
}
},
"required": ["reference", "angle"]
}
},
{
"name": "delete_component",
"title": "Delete Component",
"description": "Removes a component from the board.",
"inputSchema": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "Component reference designator"
}
},
"required": ["reference"]
}
},
{
"name": "edit_component",
"title": "Edit Component Properties",
"description": "Modifies properties of an existing component (value, footprint, etc.).",
"inputSchema": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "Component reference designator"
},
"value": {
"type": "string",
"description": "New component value"
},
"footprint": {
"type": "string",
"description": "New footprint library:name"
}
},
"required": ["reference"]
}
},
{
"name": "get_component_properties",
"title": "Get Component Properties",
"description": "Retrieves detailed properties of a specific component.",
"inputSchema": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "Component reference designator"
}
},
"required": ["reference"]
}
},
{
"name": "get_component_list",
"title": "List All Components",
"description": "Returns a list of all components on the board with their properties.",
"inputSchema": {
"type": "object",
"properties": {}
}
},
{
"name": "place_component_array",
"title": "Place Component Array",
"description": "Places multiple copies of a component in a grid or circular pattern.",
"inputSchema": {
"type": "object",
"properties": {
"referencePrefix": {
"type": "string",
"description": "Reference prefix (e.g., 'R' for R1, R2, R3...)"
},
"startNumber": {
"type": "integer",
"description": "Starting number for references",
"minimum": 1,
"default": 1
},
"footprint": {
"type": "string",
"description": "Footprint library:name"
},
"pattern": {
"type": "string",
"enum": ["grid", "circular"],
"description": "Array pattern type"
},
"count": {
"type": "integer",
"description": "Total number of components to place",
"minimum": 1
},
"startX": {
"type": "number",
"description": "Starting X coordinate in millimeters"
},
"startY": {
"type": "number",
"description": "Starting Y coordinate in millimeters"
},
"spacingX": {
"type": "number",
"description": "Horizontal spacing in mm (for grid pattern)"
},
"spacingY": {
"type": "number",
"description": "Vertical spacing in mm (for grid pattern)"
},
"radius": {
"type": "number",
"description": "Circle radius in mm (for circular pattern)"
},
"rows": {
"type": "integer",
"description": "Number of rows (for grid pattern)",
"minimum": 1
},
"columns": {
"type": "integer",
"description": "Number of columns (for grid pattern)",
"minimum": 1
}
},
"required": ["referencePrefix", "footprint", "pattern", "count", "startX", "startY"]
}
},
{
"name": "align_components",
"title": "Align Components",
"description": "Aligns multiple components horizontally or vertically.",
"inputSchema": {
"type": "object",
"properties": {
"references": {
"type": "array",
"description": "Array of component reference designators to align",
"items": {"type": "string"},
"minItems": 2
},
"direction": {
"type": "string",
"enum": ["horizontal", "vertical"],
"description": "Alignment direction"
},
"spacing": {
"type": "number",
"description": "Spacing between components in mm (optional, for even distribution)"
}
},
"required": ["references", "direction"]
}
},
{
"name": "duplicate_component",
"title": "Duplicate Component",
"description": "Creates a copy of an existing component with new reference designator.",
"inputSchema": {
"type": "object",
"properties": {
"sourceReference": {
"type": "string",
"description": "Reference of component to duplicate"
},
"newReference": {
"type": "string",
"description": "Reference designator for the new component"
},
"offsetX": {
"type": "number",
"description": "X offset from original position in mm",
"default": 0
},
"offsetY": {
"type": "number",
"description": "Y offset from original position in mm",
"default": 0
}
},
"required": ["sourceReference", "newReference"]
}
}
]
# =============================================================================
# ROUTING TOOLS
# =============================================================================
ROUTING_TOOLS = [
{
"name": "add_net",
"title": "Create Electrical Net",
"description": "Creates a new electrical net for signal routing.",
"inputSchema": {
"type": "object",
"properties": {
"netName": {
"type": "string",
"description": "Name of the net (e.g., VCC, GND, SDA)",
"minLength": 1
},
"netClass": {
"type": "string",
"description": "Optional net class to assign (must exist first)"
}
},
"required": ["netName"]
}
},
{
"name": "route_trace",
"title": "Route PCB Trace",
"description": "Routes a copper trace between two points or pads on a specified layer.",
"inputSchema": {
"type": "object",
"properties": {
"netName": {
"type": "string",
"description": "Net name for this trace"
},
"layer": {
"type": "string",
"description": "Layer to route on (e.g., F.Cu, B.Cu)",
"default": "F.Cu"
},
"width": {
"type": "number",
"description": "Trace width in millimeters",
"minimum": 0.1
},
"points": {
"type": "array",
"description": "Array of [x, y] waypoints in millimeters",
"items": {
"type": "array",
"items": {"type": "number"},
"minItems": 2,
"maxItems": 2
},
"minItems": 2
}
},
"required": ["points", "width"]
}
},
{
"name": "add_via",
"title": "Add Via",
"description": "Adds a via (plated through-hole) to connect traces between layers.",
"inputSchema": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate in millimeters"
},
"y": {
"type": "number",
"description": "Y coordinate in millimeters"
},
"diameter": {
"type": "number",
"description": "Via diameter in millimeters",
"minimum": 0.1
},
"drill": {
"type": "number",
"description": "Drill diameter in millimeters",
"minimum": 0.1
},
"netName": {
"type": "string",
"description": "Net name to assign to this via"
}
},
"required": ["x", "y", "diameter", "drill"]
}
},
{
"name": "delete_trace",
"title": "Delete Trace",
"description": "Removes a trace or segment from the board.",
"inputSchema": {
"type": "object",
"properties": {
"traceId": {
"type": "string",
"description": "Identifier of the trace to delete"
}
},
"required": ["traceId"]
}
},
{
"name": "get_nets_list",
"title": "List All Nets",
"description": "Returns a list of all electrical nets defined on the board.",
"inputSchema": {
"type": "object",
"properties": {}
}
},
{
"name": "create_netclass",
"title": "Create Net Class",
"description": "Defines a net class with specific routing rules (trace width, clearance, etc.).",
"inputSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Net class name",
"minLength": 1
},
"traceWidth": {
"type": "number",
"description": "Default trace width in millimeters",
"minimum": 0.1
},
"clearance": {
"type": "number",
"description": "Clearance in millimeters",
"minimum": 0.1
},
"viaDiameter": {
"type": "number",
"description": "Via diameter in millimeters"
},
"viaDrill": {
"type": "number",
"description": "Via drill diameter in millimeters"
}
},
"required": ["name", "traceWidth", "clearance"]
}
},
{
"name": "add_copper_pour",
"title": "Add Copper Pour",
"description": "Creates a copper pour/zone (typically for ground or power planes).",
"inputSchema": {
"type": "object",
"properties": {
"netName": {
"type": "string",
"description": "Net to connect this copper pour to (e.g., GND, VCC)"
},
"layer": {
"type": "string",
"description": "Layer for the copper pour (e.g., F.Cu, B.Cu)"
},
"priority": {
"type": "integer",
"description": "Pour priority (higher priorities fill first)",
"minimum": 0,
"default": 0
},
"clearance": {
"type": "number",
"description": "Clearance from other objects in millimeters",
"minimum": 0.1
},
"outline": {
"type": "array",
"description": "Array of [x, y] points defining the pour boundary",
"items": {
"type": "array",
"items": {"type": "number"},
"minItems": 2,
"maxItems": 2
},
"minItems": 3
}
},
"required": ["netName", "layer", "outline"]
}
},
{
"name": "route_differential_pair",
"title": "Route Differential Pair",
"description": "Routes a differential signal pair with matched lengths and spacing.",
"inputSchema": {
"type": "object",
"properties": {
"positiveName": {
"type": "string",
"description": "Positive signal net name"
},
"negativeName": {
"type": "string",
"description": "Negative signal net name"
},
"layer": {
"type": "string",
"description": "Layer to route on"
},
"width": {
"type": "number",
"description": "Trace width in millimeters"
},
"gap": {
"type": "number",
"description": "Gap between traces in millimeters"
},
"points": {
"type": "array",
"description": "Waypoints for the pair routing",
"items": {
"type": "array",
"items": {"type": "number"},
"minItems": 2,
"maxItems": 2
},
"minItems": 2
}
},
"required": ["positiveName", "negativeName", "width", "gap", "points"]
}
}
]
# =============================================================================
# LIBRARY TOOLS
# =============================================================================
LIBRARY_TOOLS = [
{
"name": "list_libraries",
"title": "List Footprint Libraries",
"description": "Lists all available footprint libraries accessible to KiCAD.",
"inputSchema": {
"type": "object",
"properties": {}
}
},
{
"name": "search_footprints",
"title": "Search Footprints",
"description": "Searches for footprints matching a query string across all libraries.",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query (e.g., '0805', 'SOIC', 'QFP')",
"minLength": 1
},
"library": {
"type": "string",
"description": "Optional library to restrict search to"
}
},
"required": ["query"]
}
},
{
"name": "list_library_footprints",
"title": "List Footprints in Library",
"description": "Lists all footprints available in a specific library.",
"inputSchema": {
"type": "object",
"properties": {
"library": {
"type": "string",
"description": "Library name (e.g., Resistor_SMD, Connector_PinHeader)",
"minLength": 1
}
},
"required": ["library"]
}
},
{
"name": "get_footprint_info",
"title": "Get Footprint Details",
"description": "Retrieves detailed information about a specific footprint including pad layout, dimensions, and description.",
"inputSchema": {
"type": "object",
"properties": {
"library": {
"type": "string",
"description": "Library name"
},
"footprint": {
"type": "string",
"description": "Footprint name"
}
},
"required": ["library", "footprint"]
}
}
]
# =============================================================================
# DESIGN RULE TOOLS
# =============================================================================
DESIGN_RULE_TOOLS = [
{
"name": "set_design_rules",
"title": "Set Design Rules",
"description": "Configures board design rules including clearances, trace widths, and via sizes.",
"inputSchema": {
"type": "object",
"properties": {
"clearance": {
"type": "number",
"description": "Minimum clearance between copper in millimeters",
"minimum": 0.1
},
"trackWidth": {
"type": "number",
"description": "Minimum track width in millimeters",
"minimum": 0.1
},
"viaDiameter": {
"type": "number",
"description": "Minimum via diameter in millimeters"
},
"viaDrill": {
"type": "number",
"description": "Minimum via drill diameter in millimeters"
},
"microViaD iameter": {
"type": "number",
"description": "Minimum micro-via diameter in millimeters"
}
}
}
},
{
"name": "get_design_rules",
"title": "Get Current Design Rules",
"description": "Retrieves the currently configured design rules from the board.",
"inputSchema": {
"type": "object",
"properties": {}
}
},
{
"name": "run_drc",
"title": "Run Design Rule Check",
"description": "Executes a design rule check (DRC) on the current board and reports violations.",
"inputSchema": {
"type": "object",
"properties": {
"includeWarnings": {
"type": "boolean",
"description": "Include warnings in addition to errors",
"default": True
}
}
}
},
{
"name": "get_drc_violations",
"title": "Get DRC Violations",
"description": "Returns a list of design rule violations from the most recent DRC run.",
"inputSchema": {
"type": "object",
"properties": {}
}
}
]
# =============================================================================
# EXPORT TOOLS
# =============================================================================
EXPORT_TOOLS = [
{
"name": "export_gerber",
"title": "Export Gerber Files",
"description": "Generates Gerber files for PCB fabrication (industry standard format).",
"inputSchema": {
"type": "object",
"properties": {
"outputPath": {
"type": "string",
"description": "Directory path for output files"
},
"layers": {
"type": "array",
"description": "List of layers to export (if not provided, exports all copper and mask layers)",
"items": {"type": "string"}
},
"includeDrillFiles": {
"type": "boolean",
"description": "Include drill files (Excellon format)",
"default": True
}
},
"required": ["outputPath"]
}
},
{
"name": "export_pdf",
"title": "Export PDF",
"description": "Exports the board layout as a PDF document for documentation or review.",
"inputSchema": {
"type": "object",
"properties": {
"outputPath": {
"type": "string",
"description": "Path for output PDF file"
},
"layers": {
"type": "array",
"description": "Layers to include in PDF",
"items": {"type": "string"}
},
"colorMode": {
"type": "string",
"enum": ["color", "black_white"],
"description": "Color mode for output",
"default": "color"
}
},
"required": ["outputPath"]
}
},
{
"name": "export_svg",
"title": "Export SVG",
"description": "Exports the board as Scalable Vector Graphics for documentation or web display.",
"inputSchema": {
"type": "object",
"properties": {
"outputPath": {
"type": "string",
"description": "Path for output SVG file"
},
"layers": {
"type": "array",
"description": "Layers to include in SVG",
"items": {"type": "string"}
}
},
"required": ["outputPath"]
}
},
{
"name": "export_3d",
"title": "Export 3D Model",
"description": "Exports a 3D model of the board in STEP or VRML format for mechanical CAD integration.",
"inputSchema": {
"type": "object",
"properties": {
"outputPath": {
"type": "string",
"description": "Path for output 3D file"
},
"format": {
"type": "string",
"enum": ["step", "vrml"],
"description": "3D model format",
"default": "step"
},
"includeComponents": {
"type": "boolean",
"description": "Include 3D component models",
"default": True
}
},
"required": ["outputPath"]
}
},
{
"name": "export_bom",
"title": "Export Bill of Materials",
"description": "Generates a bill of materials (BOM) listing all components with references, values, and footprints.",
"inputSchema": {
"type": "object",
"properties": {
"outputPath": {
"type": "string",
"description": "Path for output BOM file"
},
"format": {
"type": "string",
"enum": ["csv", "xml", "html"],
"description": "BOM output format",
"default": "csv"
},
"groupByValue": {
"type": "boolean",
"description": "Group components with same value together",
"default": True
}
},
"required": ["outputPath"]
}
}
]
# =============================================================================
# SCHEMATIC TOOLS
# =============================================================================
SCHEMATIC_TOOLS = [
{
"name": "create_schematic",
"title": "Create New Schematic",
"description": "Creates a new KiCAD schematic file for circuit design.",
"inputSchema": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Path for the new schematic file (.kicad_sch)"
},
"title": {
"type": "string",
"description": "Schematic title"
}
},
"required": ["filename"]
}
},
{
"name": "load_schematic",
"title": "Load Existing Schematic",
"description": "Opens an existing KiCAD schematic file for editing.",
"inputSchema": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Path to schematic file (.kicad_sch)"
}
},
"required": ["filename"]
}
},
{
"name": "add_schematic_component",
"title": "Add Component to Schematic",
"description": "Places a symbol (resistor, capacitor, IC, etc.) on the schematic.",
"inputSchema": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "Reference designator (e.g., R1, C2, U3)"
},
"symbol": {
"type": "string",
"description": "Symbol library:name (e.g., Device:R, Device:C)"
},
"value": {
"type": "string",
"description": "Component value (e.g., 10k, 0.1uF)"
},
"x": {
"type": "number",
"description": "X coordinate on schematic"
},
"y": {
"type": "number",
"description": "Y coordinate on schematic"
}
},
"required": ["reference", "symbol", "x", "y"]
}
},
{
"name": "add_schematic_wire",
"title": "Connect Components",
"description": "Draws a wire connection between component pins on the schematic.",
"inputSchema": {
"type": "object",
"properties": {
"points": {
"type": "array",
"description": "Array of [x, y] waypoints for the wire",
"items": {
"type": "array",
"items": {"type": "number"},
"minItems": 2,
"maxItems": 2
},
"minItems": 2
}
},
"required": ["points"]
}
},
{
"name": "list_schematic_libraries",
"title": "List Symbol Libraries",
"description": "Lists all available symbol libraries for schematic design.",
"inputSchema": {
"type": "object",
"properties": {
"searchPaths": {
"type": "array",
"description": "Optional additional paths to search for libraries",
"items": {"type": "string"}
}
}
}
},
{
"name": "export_schematic_pdf",
"title": "Export Schematic to PDF",
"description": "Exports the schematic as a PDF document for printing or documentation.",
"inputSchema": {
"type": "object",
"properties": {
"schematicPath": {
"type": "string",
"description": "Path to schematic file"
},
"outputPath": {
"type": "string",
"description": "Path for output PDF"
}
},
"required": ["schematicPath", "outputPath"]
}
}
]
# =============================================================================
# UI/PROCESS TOOLS
# =============================================================================
UI_TOOLS = [
{
"name": "check_kicad_ui",
"title": "Check KiCAD UI Status",
"description": "Checks if KiCAD user interface is currently running and returns process information.",
"inputSchema": {
"type": "object",
"properties": {}
}
},
{
"name": "launch_kicad_ui",
"title": "Launch KiCAD Application",
"description": "Opens the KiCAD graphical user interface, optionally with a specific project loaded.",
"inputSchema": {
"type": "object",
"properties": {
"projectPath": {
"type": "string",
"description": "Optional path to project file to open in UI"
},
"autoLaunch": {
"type": "boolean",
"description": "Whether to automatically launch if not running",
"default": True
}
}
}
}
]
# =============================================================================
# COMBINED TOOL SCHEMAS
# =============================================================================
TOOL_SCHEMAS: Dict[str, Any] = {}
# Combine all tool categories
for tool in (PROJECT_TOOLS + BOARD_TOOLS + COMPONENT_TOOLS + ROUTING_TOOLS +
LIBRARY_TOOLS + DESIGN_RULE_TOOLS + EXPORT_TOOLS +
SCHEMATIC_TOOLS + UI_TOOLS):
TOOL_SCHEMAS[tool["name"]] = tool
# Total: 46 tools with comprehensive schemas
```
--------------------------------------------------------------------------------
/python/kicad_interface.py:
--------------------------------------------------------------------------------
```python
#!/usr/bin/env python3
"""
KiCAD Python Interface Script for Model Context Protocol
This script handles communication between the MCP TypeScript server
and KiCAD's Python API (pcbnew). It receives commands via stdin as
JSON and returns responses via stdout also as JSON.
"""
import sys
import json
import traceback
import logging
import os
from typing import Dict, Any, Optional
# Import tool schemas and resource definitions
from schemas.tool_schemas import TOOL_SCHEMAS
from resources.resource_definitions import RESOURCE_DEFINITIONS, handle_resource_read
# Configure logging
log_dir = os.path.join(os.path.expanduser('~'), '.kicad-mcp', 'logs')
os.makedirs(log_dir, exist_ok=True)
log_file = os.path.join(log_dir, 'kicad_interface.log')
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s [%(levelname)s] %(message)s',
handlers=[
logging.FileHandler(log_file),
logging.StreamHandler(sys.stderr)
]
)
logger = logging.getLogger('kicad_interface')
# Log Python environment details
logger.info(f"Python version: {sys.version}")
logger.info(f"Python executable: {sys.executable}")
logger.info(f"Platform: {sys.platform}")
logger.info(f"Working directory: {os.getcwd()}")
# Windows-specific diagnostics
if sys.platform == 'win32':
logger.info("=== Windows Environment Diagnostics ===")
logger.info(f"PYTHONPATH: {os.environ.get('PYTHONPATH', 'NOT SET')}")
logger.info(f"PATH: {os.environ.get('PATH', 'NOT SET')[:200]}...") # Truncate PATH
# Check for common KiCAD installations
common_kicad_paths = [
r"C:\Program Files\KiCad",
r"C:\Program Files (x86)\KiCad"
]
found_kicad = False
for base_path in common_kicad_paths:
if os.path.exists(base_path):
logger.info(f"Found KiCAD installation at: {base_path}")
# List versions
try:
versions = [d for d in os.listdir(base_path) if os.path.isdir(os.path.join(base_path, d))]
logger.info(f" Versions found: {', '.join(versions)}")
for version in versions:
python_path = os.path.join(base_path, version, 'lib', 'python3', 'dist-packages')
if os.path.exists(python_path):
logger.info(f" ✓ Python path exists: {python_path}")
found_kicad = True
else:
logger.warning(f" ✗ Python path missing: {python_path}")
except Exception as e:
logger.warning(f" Could not list versions: {e}")
if not found_kicad:
logger.warning("No KiCAD installations found in standard locations!")
logger.warning("Please ensure KiCAD 9.0+ is installed from https://www.kicad.org/download/windows/")
logger.info("========================================")
# Add utils directory to path for imports
utils_dir = os.path.join(os.path.dirname(__file__))
if utils_dir not in sys.path:
sys.path.insert(0, utils_dir)
# Import platform helper and add KiCAD paths
from utils.platform_helper import PlatformHelper
from utils.kicad_process import check_and_launch_kicad, KiCADProcessManager
logger.info(f"Detecting KiCAD Python paths for {PlatformHelper.get_platform_name()}...")
paths_added = PlatformHelper.add_kicad_to_python_path()
if paths_added:
logger.info("Successfully added KiCAD Python paths to sys.path")
else:
logger.warning("No KiCAD Python paths found - attempting to import pcbnew from system path")
logger.info(f"Current Python path: {sys.path}")
# Check if auto-launch is enabled
AUTO_LAUNCH_KICAD = os.environ.get("KICAD_AUTO_LAUNCH", "false").lower() == "true"
if AUTO_LAUNCH_KICAD:
logger.info("KiCAD auto-launch enabled")
# Check which backend to use
# KICAD_BACKEND can be: 'auto', 'ipc', or 'swig'
KICAD_BACKEND = os.environ.get("KICAD_BACKEND", "auto").lower()
logger.info(f"KiCAD backend preference: {KICAD_BACKEND}")
# Try to use IPC backend first if available and preferred
USE_IPC_BACKEND = False
ipc_backend = None
if KICAD_BACKEND in ('auto', 'ipc'):
try:
logger.info("Checking IPC backend availability...")
from kicad_api.ipc_backend import IPCBackend
# Try to connect to running KiCAD
ipc_backend = IPCBackend()
if ipc_backend.connect():
USE_IPC_BACKEND = True
logger.info(f"✓ Using IPC backend - real-time UI sync enabled!")
logger.info(f" KiCAD version: {ipc_backend.get_version()}")
else:
logger.info("IPC backend available but KiCAD not running with IPC enabled")
ipc_backend = None
except ImportError:
logger.info("IPC backend not available (kicad-python not installed)")
except Exception as e:
logger.info(f"IPC backend connection failed: {e}")
ipc_backend = None
# Fall back to SWIG backend if IPC not available
if not USE_IPC_BACKEND and KICAD_BACKEND != 'ipc':
# Import KiCAD's Python API (SWIG)
try:
logger.info("Attempting to import pcbnew module (SWIG backend)...")
import pcbnew # type: ignore
logger.info(f"Successfully imported pcbnew module from: {pcbnew.__file__}")
logger.info(f"pcbnew version: {pcbnew.GetBuildVersion()}")
logger.warning("Using SWIG backend - changes require manual reload in KiCAD UI")
except ImportError as e:
logger.error(f"Failed to import pcbnew module: {e}")
logger.error(f"Current sys.path: {sys.path}")
# Platform-specific help message
help_message = ""
if sys.platform == 'win32':
help_message = """
Windows Troubleshooting:
1. Verify KiCAD is installed: C:\\Program Files\\KiCad\\9.0
2. Check PYTHONPATH environment variable points to:
C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages
3. Test with: "C:\\Program Files\\KiCad\\9.0\\bin\\python.exe" -c "import pcbnew"
4. Log file location: %USERPROFILE%\\.kicad-mcp\\logs\\kicad_interface.log
5. Run setup-windows.ps1 for automatic configuration
"""
elif sys.platform == 'darwin':
help_message = """
macOS Troubleshooting:
1. Verify KiCAD is installed: /Applications/KiCad/KiCad.app
2. Check PYTHONPATH points to KiCAD's Python packages
3. Run: python3 -c "import pcbnew" to test
"""
else: # Linux
help_message = """
Linux Troubleshooting:
1. Verify KiCAD is installed: apt list --installed | grep kicad
2. Check: /usr/lib/kicad/lib/python3/dist-packages exists
3. Test: python3 -c "import pcbnew"
"""
logger.error(help_message)
error_response = {
"success": False,
"message": "Failed to import pcbnew module - KiCAD Python API not found",
"errorDetails": f"Error: {str(e)}\n\n{help_message}\n\nPython sys.path:\n{chr(10).join(sys.path)}"
}
print(json.dumps(error_response))
sys.exit(1)
except Exception as e:
logger.error(f"Unexpected error importing pcbnew: {e}")
logger.error(traceback.format_exc())
error_response = {
"success": False,
"message": "Error importing pcbnew module",
"errorDetails": str(e)
}
print(json.dumps(error_response))
sys.exit(1)
# If IPC-only mode requested but not available, exit with error
elif KICAD_BACKEND == 'ipc' and not USE_IPC_BACKEND:
error_response = {
"success": False,
"message": "IPC backend requested but not available",
"errorDetails": "KiCAD must be running with IPC API enabled. Enable at: Preferences > Plugins > Enable IPC API Server"
}
print(json.dumps(error_response))
sys.exit(1)
# Import command handlers
try:
logger.info("Importing command handlers...")
from commands.project import ProjectCommands
from commands.board import BoardCommands
from commands.component import ComponentCommands
from commands.routing import RoutingCommands
from commands.design_rules import DesignRuleCommands
from commands.export import ExportCommands
from commands.schematic import SchematicManager
from commands.component_schematic import ComponentManager
from commands.connection_schematic import ConnectionManager
from commands.library_schematic import LibraryManager as SchematicLibraryManager
from commands.library import LibraryManager as FootprintLibraryManager, LibraryCommands
logger.info("Successfully imported all command handlers")
except ImportError as e:
logger.error(f"Failed to import command handlers: {e}")
error_response = {
"success": False,
"message": "Failed to import command handlers",
"errorDetails": str(e)
}
print(json.dumps(error_response))
sys.exit(1)
class KiCADInterface:
"""Main interface class to handle KiCAD operations"""
def __init__(self):
"""Initialize the interface and command handlers"""
self.board = None
self.project_filename = None
self.use_ipc = USE_IPC_BACKEND
self.ipc_backend = ipc_backend
self.ipc_board_api = None
if self.use_ipc:
logger.info("Initializing with IPC backend (real-time UI sync enabled)")
try:
self.ipc_board_api = self.ipc_backend.get_board()
logger.info("✓ Got IPC board API")
except Exception as e:
logger.warning(f"Could not get IPC board API: {e}")
else:
logger.info("Initializing with SWIG backend")
logger.info("Initializing command handlers...")
# Initialize footprint library manager
self.footprint_library = FootprintLibraryManager()
# Initialize command handlers
self.project_commands = ProjectCommands(self.board)
self.board_commands = BoardCommands(self.board)
self.component_commands = ComponentCommands(self.board, self.footprint_library)
self.routing_commands = RoutingCommands(self.board)
self.design_rule_commands = DesignRuleCommands(self.board)
self.export_commands = ExportCommands(self.board)
self.library_commands = LibraryCommands(self.footprint_library)
# Schematic-related classes don't need board reference
# as they operate directly on schematic files
# Command routing dictionary
self.command_routes = {
# Project commands
"create_project": self.project_commands.create_project,
"open_project": self.project_commands.open_project,
"save_project": self.project_commands.save_project,
"get_project_info": self.project_commands.get_project_info,
# Board commands
"set_board_size": self.board_commands.set_board_size,
"add_layer": self.board_commands.add_layer,
"set_active_layer": self.board_commands.set_active_layer,
"get_board_info": self.board_commands.get_board_info,
"get_layer_list": self.board_commands.get_layer_list,
"get_board_2d_view": self.board_commands.get_board_2d_view,
"add_board_outline": self.board_commands.add_board_outline,
"add_mounting_hole": self.board_commands.add_mounting_hole,
"add_text": self.board_commands.add_text,
"add_board_text": self.board_commands.add_text, # Alias for TypeScript tool
# Component commands
"place_component": self.component_commands.place_component,
"move_component": self.component_commands.move_component,
"rotate_component": self.component_commands.rotate_component,
"delete_component": self.component_commands.delete_component,
"edit_component": self.component_commands.edit_component,
"get_component_properties": self.component_commands.get_component_properties,
"get_component_list": self.component_commands.get_component_list,
"place_component_array": self.component_commands.place_component_array,
"align_components": self.component_commands.align_components,
"duplicate_component": self.component_commands.duplicate_component,
# Routing commands
"add_net": self.routing_commands.add_net,
"route_trace": self.routing_commands.route_trace,
"add_via": self.routing_commands.add_via,
"delete_trace": self.routing_commands.delete_trace,
"get_nets_list": self.routing_commands.get_nets_list,
"create_netclass": self.routing_commands.create_netclass,
"add_copper_pour": self.routing_commands.add_copper_pour,
"route_differential_pair": self.routing_commands.route_differential_pair,
"refill_zones": self._handle_refill_zones,
# Design rule commands
"set_design_rules": self.design_rule_commands.set_design_rules,
"get_design_rules": self.design_rule_commands.get_design_rules,
"run_drc": self.design_rule_commands.run_drc,
"get_drc_violations": self.design_rule_commands.get_drc_violations,
# Export commands
"export_gerber": self.export_commands.export_gerber,
"export_pdf": self.export_commands.export_pdf,
"export_svg": self.export_commands.export_svg,
"export_3d": self.export_commands.export_3d,
"export_bom": self.export_commands.export_bom,
# Library commands (footprint management)
"list_libraries": self.library_commands.list_libraries,
"search_footprints": self.library_commands.search_footprints,
"list_library_footprints": self.library_commands.list_library_footprints,
"get_footprint_info": self.library_commands.get_footprint_info,
# Schematic commands
"create_schematic": self._handle_create_schematic,
"load_schematic": self._handle_load_schematic,
"add_schematic_component": self._handle_add_schematic_component,
"add_schematic_wire": self._handle_add_schematic_wire,
"add_schematic_connection": self._handle_add_schematic_connection,
"add_schematic_net_label": self._handle_add_schematic_net_label,
"connect_to_net": self._handle_connect_to_net,
"get_net_connections": self._handle_get_net_connections,
"generate_netlist": self._handle_generate_netlist,
"list_schematic_libraries": self._handle_list_schematic_libraries,
"export_schematic_pdf": self._handle_export_schematic_pdf,
# UI/Process management commands
"check_kicad_ui": self._handle_check_kicad_ui,
"launch_kicad_ui": self._handle_launch_kicad_ui,
# IPC-specific commands (real-time operations)
"get_backend_info": self._handle_get_backend_info,
"ipc_add_track": self._handle_ipc_add_track,
"ipc_add_via": self._handle_ipc_add_via,
"ipc_add_text": self._handle_ipc_add_text,
"ipc_list_components": self._handle_ipc_list_components,
"ipc_get_tracks": self._handle_ipc_get_tracks,
"ipc_get_vias": self._handle_ipc_get_vias,
"ipc_save_board": self._handle_ipc_save_board
}
logger.info(f"KiCAD interface initialized (backend: {'IPC' if self.use_ipc else 'SWIG'})")
# Commands that can be handled via IPC for real-time updates
IPC_CAPABLE_COMMANDS = {
# Routing commands
"route_trace": "_ipc_route_trace",
"add_via": "_ipc_add_via",
"add_net": "_ipc_add_net",
"delete_trace": "_ipc_delete_trace",
"get_nets_list": "_ipc_get_nets_list",
# Zone commands
"add_copper_pour": "_ipc_add_copper_pour",
"refill_zones": "_ipc_refill_zones",
# Board commands
"add_text": "_ipc_add_text",
"add_board_text": "_ipc_add_text",
"set_board_size": "_ipc_set_board_size",
"get_board_info": "_ipc_get_board_info",
"add_board_outline": "_ipc_add_board_outline",
"add_mounting_hole": "_ipc_add_mounting_hole",
"get_layer_list": "_ipc_get_layer_list",
# Component commands
"place_component": "_ipc_place_component",
"move_component": "_ipc_move_component",
"rotate_component": "_ipc_rotate_component",
"delete_component": "_ipc_delete_component",
"get_component_list": "_ipc_get_component_list",
"get_component_properties": "_ipc_get_component_properties",
# Save command
"save_project": "_ipc_save_project",
}
def handle_command(self, command: str, params: Dict[str, Any]) -> Dict[str, Any]:
"""Route command to appropriate handler, preferring IPC when available"""
logger.info(f"Handling command: {command}")
logger.debug(f"Command parameters: {params}")
try:
# Check if we can use IPC for this command (real-time UI sync)
if self.use_ipc and self.ipc_board_api and command in self.IPC_CAPABLE_COMMANDS:
ipc_handler_name = self.IPC_CAPABLE_COMMANDS[command]
ipc_handler = getattr(self, ipc_handler_name, None)
if ipc_handler:
logger.info(f"Using IPC backend for {command} (real-time sync)")
result = ipc_handler(params)
# Add indicator that IPC was used
if isinstance(result, dict):
result["_backend"] = "ipc"
result["_realtime"] = True
logger.debug(f"IPC command result: {result}")
return result
# Fall back to SWIG-based handler
if self.use_ipc and command in self.IPC_CAPABLE_COMMANDS:
logger.warning(f"IPC handler not available for {command}, falling back to SWIG (deprecated)")
# Get the handler for the command
handler = self.command_routes.get(command)
if handler:
# Execute the command
result = handler(params)
logger.debug(f"Command result: {result}")
# Add backend indicator
if isinstance(result, dict):
result["_backend"] = "swig"
result["_realtime"] = False
# Update board reference if command was successful
if result.get("success", False):
if command == "create_project" or command == "open_project":
logger.info("Updating board reference...")
# Get board from the project commands handler
self.board = self.project_commands.board
self._update_command_handlers()
return result
else:
logger.error(f"Unknown command: {command}")
return {
"success": False,
"message": f"Unknown command: {command}",
"errorDetails": "The specified command is not supported"
}
except Exception as e:
# Get the full traceback
traceback_str = traceback.format_exc()
logger.error(f"Error handling command {command}: {str(e)}\n{traceback_str}")
return {
"success": False,
"message": f"Error handling command: {command}",
"errorDetails": f"{str(e)}\n{traceback_str}"
}
def _update_command_handlers(self):
"""Update board reference in all command handlers"""
logger.debug("Updating board reference in command handlers")
self.project_commands.board = self.board
self.board_commands.board = self.board
self.component_commands.board = self.board
self.routing_commands.board = self.board
self.design_rule_commands.board = self.board
self.export_commands.board = self.board
# Schematic command handlers
def _handle_create_schematic(self, params):
"""Create a new schematic"""
logger.info("Creating schematic")
try:
# Support multiple parameter naming conventions for compatibility:
# - TypeScript tools use: name, path
# - Python schema uses: filename, title
# - Legacy uses: projectName, path, metadata
project_name = (
params.get("projectName") or
params.get("name") or
params.get("title")
)
# Handle filename parameter - it may contain full path
filename = params.get("filename")
if filename:
# If filename provided, extract name and path from it
if filename.endswith('.kicad_sch'):
filename = filename[:-10] # Remove .kicad_sch extension
path = os.path.dirname(filename) or "."
project_name = project_name or os.path.basename(filename)
else:
path = params.get("path", ".")
metadata = params.get("metadata", {})
if not project_name:
return {
"success": False,
"message": "Schematic name is required. Provide 'name', 'projectName', or 'filename' parameter."
}
schematic = SchematicManager.create_schematic(project_name, metadata)
file_path = f"{path}/{project_name}.kicad_sch"
success = SchematicManager.save_schematic(schematic, file_path)
return {"success": success, "file_path": file_path}
except Exception as e:
logger.error(f"Error creating schematic: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_load_schematic(self, params):
"""Load an existing schematic"""
logger.info("Loading schematic")
try:
filename = params.get("filename")
if not filename:
return {"success": False, "message": "Filename is required"}
schematic = SchematicManager.load_schematic(filename)
success = schematic is not None
if success:
metadata = SchematicManager.get_schematic_metadata(schematic)
return {"success": success, "metadata": metadata}
else:
return {"success": False, "message": "Failed to load schematic"}
except Exception as e:
logger.error(f"Error loading schematic: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_add_schematic_component(self, params):
"""Add a component to a schematic"""
logger.info("Adding component to schematic")
try:
schematic_path = params.get("schematicPath")
component = params.get("component", {})
if not schematic_path:
return {"success": False, "message": "Schematic path is required"}
if not component:
return {"success": False, "message": "Component definition is required"}
schematic = SchematicManager.load_schematic(schematic_path)
if not schematic:
return {"success": False, "message": "Failed to load schematic"}
component_obj = ComponentManager.add_component(schematic, component)
success = component_obj is not None
if success:
SchematicManager.save_schematic(schematic, schematic_path)
return {"success": True}
else:
return {"success": False, "message": "Failed to add component"}
except Exception as e:
logger.error(f"Error adding component to schematic: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_add_schematic_wire(self, params):
"""Add a wire to a schematic"""
logger.info("Adding wire to schematic")
try:
schematic_path = params.get("schematicPath")
start_point = params.get("startPoint")
end_point = params.get("endPoint")
if not schematic_path:
return {"success": False, "message": "Schematic path is required"}
if not start_point or not end_point:
return {"success": False, "message": "Start and end points are required"}
schematic = SchematicManager.load_schematic(schematic_path)
if not schematic:
return {"success": False, "message": "Failed to load schematic"}
wire = ConnectionManager.add_wire(schematic, start_point, end_point)
success = wire is not None
if success:
SchematicManager.save_schematic(schematic, schematic_path)
return {"success": True}
else:
return {"success": False, "message": "Failed to add wire"}
except Exception as e:
logger.error(f"Error adding wire to schematic: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_list_schematic_libraries(self, params):
"""List available symbol libraries"""
logger.info("Listing schematic libraries")
try:
search_paths = params.get("searchPaths")
libraries = LibraryManager.list_available_libraries(search_paths)
return {"success": True, "libraries": libraries}
except Exception as e:
logger.error(f"Error listing schematic libraries: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_export_schematic_pdf(self, params):
"""Export schematic to PDF"""
logger.info("Exporting schematic to PDF")
try:
schematic_path = params.get("schematicPath")
output_path = params.get("outputPath")
if not schematic_path:
return {"success": False, "message": "Schematic path is required"}
if not output_path:
return {"success": False, "message": "Output path is required"}
import subprocess
result = subprocess.run(
["kicad-cli", "sch", "export", "pdf", "--output", output_path, schematic_path],
capture_output=True,
text=True
)
success = result.returncode == 0
message = result.stderr if not success else ""
return {"success": success, "message": message}
except Exception as e:
logger.error(f"Error exporting schematic to PDF: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_add_schematic_connection(self, params):
"""Add a pin-to-pin connection in schematic"""
logger.info("Adding pin-to-pin connection in schematic")
try:
schematic_path = params.get("schematicPath")
source_ref = params.get("sourceRef")
source_pin = params.get("sourcePin")
target_ref = params.get("targetRef")
target_pin = params.get("targetPin")
if not all([schematic_path, source_ref, source_pin, target_ref, target_pin]):
return {"success": False, "message": "Missing required parameters"}
schematic = SchematicManager.load_schematic(schematic_path)
if not schematic:
return {"success": False, "message": "Failed to load schematic"}
success = ConnectionManager.add_connection(schematic, source_ref, source_pin, target_ref, target_pin)
if success:
SchematicManager.save_schematic(schematic, schematic_path)
return {"success": True}
else:
return {"success": False, "message": "Failed to add connection"}
except Exception as e:
logger.error(f"Error adding schematic connection: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_add_schematic_net_label(self, params):
"""Add a net label to schematic"""
logger.info("Adding net label to schematic")
try:
schematic_path = params.get("schematicPath")
net_name = params.get("netName")
position = params.get("position")
if not all([schematic_path, net_name, position]):
return {"success": False, "message": "Missing required parameters"}
schematic = SchematicManager.load_schematic(schematic_path)
if not schematic:
return {"success": False, "message": "Failed to load schematic"}
label = ConnectionManager.add_net_label(schematic, net_name, position)
if label:
SchematicManager.save_schematic(schematic, schematic_path)
return {"success": True}
else:
return {"success": False, "message": "Failed to add net label"}
except Exception as e:
logger.error(f"Error adding net label: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_connect_to_net(self, params):
"""Connect a component pin to a named net"""
logger.info("Connecting component pin to net")
try:
schematic_path = params.get("schematicPath")
component_ref = params.get("componentRef")
pin_name = params.get("pinName")
net_name = params.get("netName")
if not all([schematic_path, component_ref, pin_name, net_name]):
return {"success": False, "message": "Missing required parameters"}
schematic = SchematicManager.load_schematic(schematic_path)
if not schematic:
return {"success": False, "message": "Failed to load schematic"}
success = ConnectionManager.connect_to_net(schematic, component_ref, pin_name, net_name)
if success:
SchematicManager.save_schematic(schematic, schematic_path)
return {"success": True}
else:
return {"success": False, "message": "Failed to connect to net"}
except Exception as e:
logger.error(f"Error connecting to net: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_get_net_connections(self, params):
"""Get all connections for a named net"""
logger.info("Getting net connections")
try:
schematic_path = params.get("schematicPath")
net_name = params.get("netName")
if not all([schematic_path, net_name]):
return {"success": False, "message": "Missing required parameters"}
schematic = SchematicManager.load_schematic(schematic_path)
if not schematic:
return {"success": False, "message": "Failed to load schematic"}
connections = ConnectionManager.get_net_connections(schematic, net_name)
return {"success": True, "connections": connections}
except Exception as e:
logger.error(f"Error getting net connections: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_generate_netlist(self, params):
"""Generate netlist from schematic"""
logger.info("Generating netlist from schematic")
try:
schematic_path = params.get("schematicPath")
if not schematic_path:
return {"success": False, "message": "Schematic path is required"}
schematic = SchematicManager.load_schematic(schematic_path)
if not schematic:
return {"success": False, "message": "Failed to load schematic"}
netlist = ConnectionManager.generate_netlist(schematic)
return {"success": True, "netlist": netlist}
except Exception as e:
logger.error(f"Error generating netlist: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_check_kicad_ui(self, params):
"""Check if KiCAD UI is running"""
logger.info("Checking if KiCAD UI is running")
try:
manager = KiCADProcessManager()
is_running = manager.is_running()
processes = manager.get_process_info() if is_running else []
return {
"success": True,
"running": is_running,
"processes": processes,
"message": "KiCAD is running" if is_running else "KiCAD is not running"
}
except Exception as e:
logger.error(f"Error checking KiCAD UI status: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_launch_kicad_ui(self, params):
"""Launch KiCAD UI"""
logger.info("Launching KiCAD UI")
try:
project_path = params.get("projectPath")
auto_launch = params.get("autoLaunch", AUTO_LAUNCH_KICAD)
# Convert project path to Path object if provided
from pathlib import Path
path_obj = Path(project_path) if project_path else None
result = check_and_launch_kicad(path_obj, auto_launch)
return {
"success": True,
**result
}
except Exception as e:
logger.error(f"Error launching KiCAD UI: {str(e)}")
return {"success": False, "message": str(e)}
def _handle_refill_zones(self, params):
"""Refill all copper pour zones on the board"""
logger.info("Refilling zones")
try:
if not self.board:
return {
"success": False,
"message": "No board is loaded",
"errorDetails": "Load or create a board first"
}
# Use pcbnew's zone filler for SWIG backend
filler = pcbnew.ZONE_FILLER(self.board)
zones = self.board.Zones()
filler.Fill(zones)
return {
"success": True,
"message": "Zones refilled successfully",
"zoneCount": zones.size() if hasattr(zones, 'size') else len(list(zones))
}
except Exception as e:
logger.error(f"Error refilling zones: {str(e)}")
return {"success": False, "message": str(e)}
# =========================================================================
# IPC Backend handlers - these provide real-time UI synchronization
# These methods are called automatically when IPC is available
# =========================================================================
def _ipc_route_trace(self, params):
"""IPC handler for route_trace - adds track with real-time UI update"""
try:
# Extract parameters matching the existing route_trace interface
start = params.get("start", {})
end = params.get("end", {})
layer = params.get("layer", "F.Cu")
width = params.get("width", 0.25)
net = params.get("net")
# Handle both dict format and direct x/y
start_x = start.get("x", 0) if isinstance(start, dict) else params.get("startX", 0)
start_y = start.get("y", 0) if isinstance(start, dict) else params.get("startY", 0)
end_x = end.get("x", 0) if isinstance(end, dict) else params.get("endX", 0)
end_y = end.get("y", 0) if isinstance(end, dict) else params.get("endY", 0)
success = self.ipc_board_api.add_track(
start_x=start_x,
start_y=start_y,
end_x=end_x,
end_y=end_y,
width=width,
layer=layer,
net_name=net
)
return {
"success": success,
"message": "Added trace (visible in KiCAD UI)" if success else "Failed to add trace",
"trace": {
"start": {"x": start_x, "y": start_y, "unit": "mm"},
"end": {"x": end_x, "y": end_y, "unit": "mm"},
"layer": layer,
"width": width,
"net": net
}
}
except Exception as e:
logger.error(f"IPC route_trace error: {e}")
return {"success": False, "message": str(e)}
def _ipc_add_via(self, params):
"""IPC handler for add_via - adds via with real-time UI update"""
try:
position = params.get("position", {})
x = position.get("x", 0) if isinstance(position, dict) else params.get("x", 0)
y = position.get("y", 0) if isinstance(position, dict) else params.get("y", 0)
size = params.get("size", 0.8)
drill = params.get("drill", 0.4)
net = params.get("net")
from_layer = params.get("from_layer", "F.Cu")
to_layer = params.get("to_layer", "B.Cu")
success = self.ipc_board_api.add_via(
x=x,
y=y,
diameter=size,
drill=drill,
net_name=net,
via_type="through"
)
return {
"success": success,
"message": "Added via (visible in KiCAD UI)" if success else "Failed to add via",
"via": {
"position": {"x": x, "y": y, "unit": "mm"},
"size": size,
"drill": drill,
"from_layer": from_layer,
"to_layer": to_layer,
"net": net
}
}
except Exception as e:
logger.error(f"IPC add_via error: {e}")
return {"success": False, "message": str(e)}
def _ipc_add_net(self, params):
"""IPC handler for add_net"""
# Note: Net creation via IPC is limited - nets are typically created
# when components are placed. Return success for compatibility.
name = params.get("name")
logger.info(f"IPC add_net: {name} (nets auto-created with components)")
return {
"success": True,
"message": f"Net '{name}' will be created when components are connected",
"net": {"name": name}
}
def _ipc_add_copper_pour(self, params):
"""IPC handler for add_copper_pour - adds zone with real-time UI update"""
try:
layer = params.get("layer", "F.Cu")
net = params.get("net")
clearance = params.get("clearance", 0.5)
min_width = params.get("minWidth", 0.25)
points = params.get("points", [])
priority = params.get("priority", 0)
fill_type = params.get("fillType", "solid")
name = params.get("name", "")
if not points or len(points) < 3:
return {
"success": False,
"message": "At least 3 points are required for copper pour outline"
}
# Convert points format if needed (handle both {x, y} and {x, y, unit})
formatted_points = []
for point in points:
formatted_points.append({
"x": point.get("x", 0),
"y": point.get("y", 0)
})
success = self.ipc_board_api.add_zone(
points=formatted_points,
layer=layer,
net_name=net,
clearance=clearance,
min_thickness=min_width,
priority=priority,
fill_mode=fill_type,
name=name
)
return {
"success": success,
"message": "Added copper pour (visible in KiCAD UI)" if success else "Failed to add copper pour",
"pour": {
"layer": layer,
"net": net,
"clearance": clearance,
"minWidth": min_width,
"priority": priority,
"fillType": fill_type,
"pointCount": len(points)
}
}
except Exception as e:
logger.error(f"IPC add_copper_pour error: {e}")
return {"success": False, "message": str(e)}
def _ipc_refill_zones(self, params):
"""IPC handler for refill_zones - refills all zones with real-time UI update"""
try:
success = self.ipc_board_api.refill_zones()
return {
"success": success,
"message": "Zones refilled (visible in KiCAD UI)" if success else "Failed to refill zones"
}
except Exception as e:
logger.error(f"IPC refill_zones error: {e}")
return {"success": False, "message": str(e)}
def _ipc_add_text(self, params):
"""IPC handler for add_text/add_board_text - adds text with real-time UI update"""
try:
text = params.get("text", "")
position = params.get("position", {})
x = position.get("x", 0) if isinstance(position, dict) else params.get("x", 0)
y = position.get("y", 0) if isinstance(position, dict) else params.get("y", 0)
layer = params.get("layer", "F.SilkS")
size = params.get("size", 1.0)
rotation = params.get("rotation", 0)
success = self.ipc_board_api.add_text(
text=text,
x=x,
y=y,
layer=layer,
size=size,
rotation=rotation
)
return {
"success": success,
"message": f"Added text '{text}' (visible in KiCAD UI)" if success else "Failed to add text"
}
except Exception as e:
logger.error(f"IPC add_text error: {e}")
return {"success": False, "message": str(e)}
def _ipc_set_board_size(self, params):
"""IPC handler for set_board_size"""
try:
width = params.get("width", 100)
height = params.get("height", 100)
unit = params.get("unit", "mm")
success = self.ipc_board_api.set_size(width, height, unit)
return {
"success": success,
"message": f"Board size set to {width}x{height} {unit} (visible in KiCAD UI)" if success else "Failed to set board size",
"boardSize": {"width": width, "height": height, "unit": unit}
}
except Exception as e:
logger.error(f"IPC set_board_size error: {e}")
return {"success": False, "message": str(e)}
def _ipc_get_board_info(self, params):
"""IPC handler for get_board_info"""
try:
size = self.ipc_board_api.get_size()
components = self.ipc_board_api.list_components()
tracks = self.ipc_board_api.get_tracks()
vias = self.ipc_board_api.get_vias()
nets = self.ipc_board_api.get_nets()
return {
"success": True,
"boardInfo": {
"size": size,
"componentCount": len(components),
"trackCount": len(tracks),
"viaCount": len(vias),
"netCount": len(nets),
"backend": "ipc",
"realtime": True
}
}
except Exception as e:
logger.error(f"IPC get_board_info error: {e}")
return {"success": False, "message": str(e)}
def _ipc_place_component(self, params):
"""IPC handler for place_component - places component with real-time UI update"""
try:
reference = params.get("reference", params.get("componentId", ""))
footprint = params.get("footprint", "")
position = params.get("position", {})
x = position.get("x", 0) if isinstance(position, dict) else params.get("x", 0)
y = position.get("y", 0) if isinstance(position, dict) else params.get("y", 0)
rotation = params.get("rotation", 0)
layer = params.get("layer", "F.Cu")
value = params.get("value", "")
success = self.ipc_board_api.place_component(
reference=reference,
footprint=footprint,
x=x,
y=y,
rotation=rotation,
layer=layer,
value=value
)
return {
"success": success,
"message": f"Placed component {reference} (visible in KiCAD UI)" if success else "Failed to place component",
"component": {
"reference": reference,
"footprint": footprint,
"position": {"x": x, "y": y, "unit": "mm"},
"rotation": rotation,
"layer": layer
}
}
except Exception as e:
logger.error(f"IPC place_component error: {e}")
return {"success": False, "message": str(e)}
def _ipc_move_component(self, params):
"""IPC handler for move_component - moves component with real-time UI update"""
try:
reference = params.get("reference", params.get("componentId", ""))
position = params.get("position", {})
x = position.get("x", 0) if isinstance(position, dict) else params.get("x", 0)
y = position.get("y", 0) if isinstance(position, dict) else params.get("y", 0)
rotation = params.get("rotation")
success = self.ipc_board_api.move_component(
reference=reference,
x=x,
y=y,
rotation=rotation
)
return {
"success": success,
"message": f"Moved component {reference} (visible in KiCAD UI)" if success else "Failed to move component"
}
except Exception as e:
logger.error(f"IPC move_component error: {e}")
return {"success": False, "message": str(e)}
def _ipc_delete_component(self, params):
"""IPC handler for delete_component - deletes component with real-time UI update"""
try:
reference = params.get("reference", params.get("componentId", ""))
success = self.ipc_board_api.delete_component(reference=reference)
return {
"success": success,
"message": f"Deleted component {reference} (visible in KiCAD UI)" if success else "Failed to delete component"
}
except Exception as e:
logger.error(f"IPC delete_component error: {e}")
return {"success": False, "message": str(e)}
def _ipc_get_component_list(self, params):
"""IPC handler for get_component_list"""
try:
components = self.ipc_board_api.list_components()
return {
"success": True,
"components": components,
"count": len(components)
}
except Exception as e:
logger.error(f"IPC get_component_list error: {e}")
return {"success": False, "message": str(e)}
def _ipc_save_project(self, params):
"""IPC handler for save_project"""
try:
success = self.ipc_board_api.save()
return {
"success": success,
"message": "Project saved" if success else "Failed to save project"
}
except Exception as e:
logger.error(f"IPC save_project error: {e}")
return {"success": False, "message": str(e)}
def _ipc_delete_trace(self, params):
"""IPC handler for delete_trace - Note: IPC doesn't support direct trace deletion yet"""
# IPC API doesn't have a direct delete track method
# Fall back to SWIG for this operation
logger.info("delete_trace: Falling back to SWIG (IPC doesn't support trace deletion)")
return self.routing_commands.delete_trace(params)
def _ipc_get_nets_list(self, params):
"""IPC handler for get_nets_list - gets nets with real-time data"""
try:
nets = self.ipc_board_api.get_nets()
return {
"success": True,
"nets": nets,
"count": len(nets)
}
except Exception as e:
logger.error(f"IPC get_nets_list error: {e}")
return {"success": False, "message": str(e)}
def _ipc_add_board_outline(self, params):
"""IPC handler for add_board_outline - adds board edge with real-time UI update"""
try:
from kipy.board_types import BoardSegment
from kipy.geometry import Vector2
from kipy.util.units import from_mm
from kipy.proto.board.board_types_pb2 import BoardLayer
board = self.ipc_board_api._get_board()
points = params.get("points", [])
width = params.get("width", 0.1)
if len(points) < 2:
return {"success": False, "message": "At least 2 points required for board outline"}
commit = board.begin_commit()
lines_created = 0
# Create line segments connecting the points
for i in range(len(points)):
start = points[i]
end = points[(i + 1) % len(points)] # Wrap around to close the outline
segment = BoardSegment()
segment.start = Vector2.from_xy(from_mm(start.get("x", 0)), from_mm(start.get("y", 0)))
segment.end = Vector2.from_xy(from_mm(end.get("x", 0)), from_mm(end.get("y", 0)))
segment.layer = BoardLayer.BL_Edge_Cuts
segment.attributes.stroke.width = from_mm(width)
board.create_items(segment)
lines_created += 1
board.push_commit(commit, "Added board outline")
return {
"success": True,
"message": f"Added board outline with {lines_created} segments (visible in KiCAD UI)",
"segments": lines_created
}
except Exception as e:
logger.error(f"IPC add_board_outline error: {e}")
return {"success": False, "message": str(e)}
def _ipc_add_mounting_hole(self, params):
"""IPC handler for add_mounting_hole - adds mounting hole with real-time UI update"""
try:
from kipy.board_types import BoardCircle
from kipy.geometry import Vector2
from kipy.util.units import from_mm
from kipy.proto.board.board_types_pb2 import BoardLayer
board = self.ipc_board_api._get_board()
x = params.get("x", 0)
y = params.get("y", 0)
diameter = params.get("diameter", 3.2) # M3 hole default
commit = board.begin_commit()
# Create circle on Edge.Cuts layer for the hole
circle = BoardCircle()
circle.center = Vector2.from_xy(from_mm(x), from_mm(y))
circle.radius = from_mm(diameter / 2)
circle.layer = BoardLayer.BL_Edge_Cuts
circle.attributes.stroke.width = from_mm(0.1)
board.create_items(circle)
board.push_commit(commit, f"Added mounting hole at ({x}, {y})")
return {
"success": True,
"message": f"Added mounting hole at ({x}, {y}) mm (visible in KiCAD UI)",
"hole": {
"position": {"x": x, "y": y},
"diameter": diameter
}
}
except Exception as e:
logger.error(f"IPC add_mounting_hole error: {e}")
return {"success": False, "message": str(e)}
def _ipc_get_layer_list(self, params):
"""IPC handler for get_layer_list - gets enabled layers"""
try:
layers = self.ipc_board_api.get_enabled_layers()
return {
"success": True,
"layers": layers,
"count": len(layers)
}
except Exception as e:
logger.error(f"IPC get_layer_list error: {e}")
return {"success": False, "message": str(e)}
def _ipc_rotate_component(self, params):
"""IPC handler for rotate_component - rotates component with real-time UI update"""
try:
reference = params.get("reference", params.get("componentId", ""))
angle = params.get("angle", params.get("rotation", 90))
# Get current component to find its position
components = self.ipc_board_api.list_components()
target = None
for comp in components:
if comp.get("reference") == reference:
target = comp
break
if not target:
return {"success": False, "message": f"Component {reference} not found"}
# Calculate new rotation
current_rotation = target.get("rotation", 0)
new_rotation = (current_rotation + angle) % 360
# Use move_component with new rotation (position stays the same)
success = self.ipc_board_api.move_component(
reference=reference,
x=target.get("position", {}).get("x", 0),
y=target.get("position", {}).get("y", 0),
rotation=new_rotation
)
return {
"success": success,
"message": f"Rotated component {reference} by {angle}° (visible in KiCAD UI)" if success else "Failed to rotate component",
"newRotation": new_rotation
}
except Exception as e:
logger.error(f"IPC rotate_component error: {e}")
return {"success": False, "message": str(e)}
def _ipc_get_component_properties(self, params):
"""IPC handler for get_component_properties - gets detailed component info"""
try:
reference = params.get("reference", params.get("componentId", ""))
components = self.ipc_board_api.list_components()
target = None
for comp in components:
if comp.get("reference") == reference:
target = comp
break
if not target:
return {"success": False, "message": f"Component {reference} not found"}
return {
"success": True,
"component": target
}
except Exception as e:
logger.error(f"IPC get_component_properties error: {e}")
return {"success": False, "message": str(e)}
# =========================================================================
# Legacy IPC command handlers (explicit ipc_* commands)
# =========================================================================
def _handle_get_backend_info(self, params):
"""Get information about the current backend"""
return {
"success": True,
"backend": "ipc" if self.use_ipc else "swig",
"realtime_sync": self.use_ipc,
"ipc_connected": self.ipc_backend.is_connected() if self.ipc_backend else False,
"version": self.ipc_backend.get_version() if self.ipc_backend else "N/A",
"message": "Using IPC backend with real-time UI sync" if self.use_ipc else "Using SWIG backend (requires manual reload)"
}
def _handle_ipc_add_track(self, params):
"""Add a track using IPC backend (real-time)"""
if not self.use_ipc or not self.ipc_board_api:
return {"success": False, "message": "IPC backend not available"}
try:
success = self.ipc_board_api.add_track(
start_x=params.get("startX", 0),
start_y=params.get("startY", 0),
end_x=params.get("endX", 0),
end_y=params.get("endY", 0),
width=params.get("width", 0.25),
layer=params.get("layer", "F.Cu"),
net_name=params.get("net")
)
return {
"success": success,
"message": "Track added (visible in KiCAD UI)" if success else "Failed to add track",
"realtime": True
}
except Exception as e:
logger.error(f"Error adding track via IPC: {e}")
return {"success": False, "message": str(e)}
def _handle_ipc_add_via(self, params):
"""Add a via using IPC backend (real-time)"""
if not self.use_ipc or not self.ipc_board_api:
return {"success": False, "message": "IPC backend not available"}
try:
success = self.ipc_board_api.add_via(
x=params.get("x", 0),
y=params.get("y", 0),
diameter=params.get("diameter", 0.8),
drill=params.get("drill", 0.4),
net_name=params.get("net"),
via_type=params.get("type", "through")
)
return {
"success": success,
"message": "Via added (visible in KiCAD UI)" if success else "Failed to add via",
"realtime": True
}
except Exception as e:
logger.error(f"Error adding via via IPC: {e}")
return {"success": False, "message": str(e)}
def _handle_ipc_add_text(self, params):
"""Add text using IPC backend (real-time)"""
if not self.use_ipc or not self.ipc_board_api:
return {"success": False, "message": "IPC backend not available"}
try:
success = self.ipc_board_api.add_text(
text=params.get("text", ""),
x=params.get("x", 0),
y=params.get("y", 0),
layer=params.get("layer", "F.SilkS"),
size=params.get("size", 1.0),
rotation=params.get("rotation", 0)
)
return {
"success": success,
"message": "Text added (visible in KiCAD UI)" if success else "Failed to add text",
"realtime": True
}
except Exception as e:
logger.error(f"Error adding text via IPC: {e}")
return {"success": False, "message": str(e)}
def _handle_ipc_list_components(self, params):
"""List components using IPC backend"""
if not self.use_ipc or not self.ipc_board_api:
return {"success": False, "message": "IPC backend not available"}
try:
components = self.ipc_board_api.list_components()
return {
"success": True,
"components": components,
"count": len(components)
}
except Exception as e:
logger.error(f"Error listing components via IPC: {e}")
return {"success": False, "message": str(e)}
def _handle_ipc_get_tracks(self, params):
"""Get tracks using IPC backend"""
if not self.use_ipc or not self.ipc_board_api:
return {"success": False, "message": "IPC backend not available"}
try:
tracks = self.ipc_board_api.get_tracks()
return {
"success": True,
"tracks": tracks,
"count": len(tracks)
}
except Exception as e:
logger.error(f"Error getting tracks via IPC: {e}")
return {"success": False, "message": str(e)}
def _handle_ipc_get_vias(self, params):
"""Get vias using IPC backend"""
if not self.use_ipc or not self.ipc_board_api:
return {"success": False, "message": "IPC backend not available"}
try:
vias = self.ipc_board_api.get_vias()
return {
"success": True,
"vias": vias,
"count": len(vias)
}
except Exception as e:
logger.error(f"Error getting vias via IPC: {e}")
return {"success": False, "message": str(e)}
def _handle_ipc_save_board(self, params):
"""Save board using IPC backend"""
if not self.use_ipc or not self.ipc_board_api:
return {"success": False, "message": "IPC backend not available"}
try:
success = self.ipc_board_api.save()
return {
"success": success,
"message": "Board saved" if success else "Failed to save board"
}
except Exception as e:
logger.error(f"Error saving board via IPC: {e}")
return {"success": False, "message": str(e)}
def main():
"""Main entry point"""
logger.info("Starting KiCAD interface...")
interface = KiCADInterface()
try:
logger.info("Processing commands from stdin...")
# Process commands from stdin
for line in sys.stdin:
try:
# Parse command
logger.debug(f"Received input: {line.strip()}")
command_data = json.loads(line)
# Check if this is JSON-RPC 2.0 format
if 'jsonrpc' in command_data and command_data['jsonrpc'] == '2.0':
logger.info("Detected JSON-RPC 2.0 format message")
method = command_data.get('method')
params = command_data.get('params', {})
request_id = command_data.get('id')
# Handle MCP protocol methods
if method == 'initialize':
logger.info("Handling MCP initialize")
response = {
'jsonrpc': '2.0',
'id': request_id,
'result': {
'protocolVersion': '2025-06-18',
'capabilities': {
'tools': {
'listChanged': True
},
'resources': {
'subscribe': False,
'listChanged': True
}
},
'serverInfo': {
'name': 'kicad-mcp-server',
'title': 'KiCAD PCB Design Assistant',
'version': '2.1.0-alpha'
},
'instructions': 'AI-assisted PCB design with KiCAD. Use tools to create projects, design boards, place components, route traces, and export manufacturing files.'
}
}
elif method == 'tools/list':
logger.info("Handling MCP tools/list")
# Return list of available tools with proper schemas
tools = []
for cmd_name in interface.command_routes.keys():
# Get schema from TOOL_SCHEMAS if available
if cmd_name in TOOL_SCHEMAS:
tool_def = TOOL_SCHEMAS[cmd_name].copy()
tools.append(tool_def)
else:
# Fallback for tools without schemas
logger.warning(f"No schema defined for tool: {cmd_name}")
tools.append({
'name': cmd_name,
'description': f'KiCAD command: {cmd_name}',
'inputSchema': {
'type': 'object',
'properties': {}
}
})
logger.info(f"Returning {len(tools)} tools")
response = {
'jsonrpc': '2.0',
'id': request_id,
'result': {
'tools': tools
}
}
elif method == 'tools/call':
logger.info("Handling MCP tools/call")
tool_name = params.get('name')
tool_params = params.get('arguments', {})
# Execute the command
result = interface.handle_command(tool_name, tool_params)
response = {
'jsonrpc': '2.0',
'id': request_id,
'result': {
'content': [
{
'type': 'text',
'text': json.dumps(result)
}
]
}
}
elif method == 'resources/list':
logger.info("Handling MCP resources/list")
# Return list of available resources
response = {
'jsonrpc': '2.0',
'id': request_id,
'result': {
'resources': RESOURCE_DEFINITIONS
}
}
elif method == 'resources/read':
logger.info("Handling MCP resources/read")
resource_uri = params.get('uri')
if not resource_uri:
response = {
'jsonrpc': '2.0',
'id': request_id,
'error': {
'code': -32602,
'message': 'Missing required parameter: uri'
}
}
else:
# Read the resource
resource_data = handle_resource_read(resource_uri, interface)
response = {
'jsonrpc': '2.0',
'id': request_id,
'result': resource_data
}
else:
logger.error(f"Unknown JSON-RPC method: {method}")
response = {
'jsonrpc': '2.0',
'id': request_id,
'error': {
'code': -32601,
'message': f'Method not found: {method}'
}
}
else:
# Handle legacy custom format
logger.info("Detected custom format message")
command = command_data.get("command")
params = command_data.get("params", {})
if not command:
logger.error("Missing command field")
response = {
"success": False,
"message": "Missing command",
"errorDetails": "The command field is required"
}
else:
# Handle command
response = interface.handle_command(command, params)
# Send response
logger.debug(f"Sending response: {response}")
print(json.dumps(response))
sys.stdout.flush()
except json.JSONDecodeError as e:
logger.error(f"Invalid JSON input: {str(e)}")
response = {
"success": False,
"message": "Invalid JSON input",
"errorDetails": str(e)
}
print(json.dumps(response))
sys.stdout.flush()
except KeyboardInterrupt:
logger.info("KiCAD interface stopped")
sys.exit(0)
except Exception as e:
logger.error(f"Unexpected error: {str(e)}\n{traceback.format_exc()}")
sys.exit(1)
if __name__ == "__main__":
main()
```