kicad-sch-api 0.3.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

mcp_server/models.py

@@ -0,0 +1,252 @@
+"""
+Pydantic models for MCP server API responses.
+
+Provides type-safe data models for MCP tools that interact with the schematic API,
+ensuring consistent serialization and validation across all endpoints.
+"""
+
+from typing import List, Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PointModel(BaseModel):
+    """2D point coordinates."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {"x": 100.0, "y": 100.0},
+            "description": "Position in KiCAD schematic coordinates",
+        }
+    )
+
+    x: float = Field(..., description="X coordinate in mm")
+    y: float = Field(..., description="Y coordinate in mm")
+
+
+class PinInfoOutput(BaseModel):
+    """
+    Complete pin information for MCP clients.
+
+    Provides comprehensive pin metadata including position, electrical type,
+    graphical representation, and unique identification.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "number": "1",
+                "name": "~",
+                "position": {"x": 100.33, "y": 104.14},
+                "electrical_type": "passive",
+                "shape": "line",
+                "length": 2.54,
+                "orientation": 0.0,
+                "uuid": "1f8ab1be-1ad8-469d-8ba9-667910bdee9e:1",
+            }
+        }
+    )
+
+    number: str = Field(
+        ...,
+        description="Pin number or designator (e.g., '1', '2', 'A1')",
+        examples=["1", "2", "A1", "CLK"],
+    )
+    name: str = Field(
+        ...,
+        description="Pin name or signal designation (e.g., 'VCC', 'GND', 'CLK')",
+        examples=["VCC", "GND", "CLK", "D0"],
+    )
+    position: PointModel = Field(
+        ...,
+        description="Absolute position in schematic coordinates (mm), "
+        "accounting for component rotation and mirroring",
+    )
+    electrical_type: str = Field(
+        ...,
+        description="Pin electrical type (input, output, passive, power_in, power_out, bidirectional, etc.)",
+        examples=["passive", "input", "output", "power_in", "power_out"],
+    )
+    shape: str = Field(
+        ...,
+        description="Pin graphical shape (line, inverted, clock, inverted_clock, input_low, etc.)",
+        examples=["line", "inverted", "clock"],
+    )
+    length: float = Field(
+        ...,
+        description="Pin length in mm (typically 2.54 for standard pins)",
+        examples=[2.54],
+    )
+    orientation: float = Field(
+        ...,
+        description="Pin orientation in degrees (0, 90, 180, or 270)",
+        examples=[0.0, 90.0, 180.0, 270.0],
+    )
+    uuid: str = Field(
+        ...,
+        description="Unique identifier for this pin instance (composite: component_uuid:pin_number)",
+        examples=["1f8ab1be-1ad8-469d-8ba9-667910bdee9e:1"],
+    )
+
+
+class ComponentPinsOutput(BaseModel):
+    """
+    Output model for get_component_pins MCP tool.
+
+    Returns all pins for a specified component with complete metadata.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "reference": "R1",
+                "lib_id": "Device:R",
+                "pins": [
+                    {
+                        "number": "1",
+                        "name": "~",
+                        "position": {"x": 100.33, "y": 104.14},
+                        "electrical_type": "passive",
+                        "shape": "line",
+                        "length": 2.54,
+                        "orientation": 0.0,
+                        "uuid": "1f8ab1be-1ad8-469d-8ba9-667910bdee9e:1",
+                    },
+                    {
+                        "number": "2",
+                        "name": "~",
+                        "position": {"x": 100.33, "y": 95.86},
+                        "electrical_type": "passive",
+                        "shape": "line",
+                        "length": 2.54,
+                        "orientation": 0.0,
+                        "uuid": "1f8ab1be-1ad8-469d-8ba9-667910bdee9e:2",
+                    },
+                ],
+                "pin_count": 2,
+                "success": True,
+            }
+        }
+    )
+
+    reference: str = Field(
+        ...,
+        description="Component reference designator (e.g., 'R1', 'U2', 'C1')",
+        examples=["R1", "U2", "C1"],
+    )
+    lib_id: str = Field(
+        ...,
+        description="Library identifier (e.g., 'Device:R', 'Amplifier_Operational:TL072')",
+        examples=["Device:R", "Amplifier_Operational:TL072", "LED:LED"],
+    )
+    pins: List[PinInfoOutput] = Field(
+        ...,
+        description="List of all pins for this component with complete metadata",
+    )
+    pin_count: int = Field(
+        ...,
+        description="Total number of pins",
+        examples=[2, 8, 14, 48],
+    )
+    success: bool = Field(
+        default=True,
+        description="Whether the operation was successful",
+    )
+    message: Optional[str] = Field(
+        default=None,
+        description="Optional message or error description",
+    )
+
+
+class ComponentInfoOutput(BaseModel):
+    """
+    Component information output model.
+
+    Provides comprehensive component metadata including position, properties,
+    and unique identification.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "reference": "R1",
+                "lib_id": "Device:R",
+                "value": "10k",
+                "position": {"x": 100.0, "y": 100.0},
+                "rotation": 0.0,
+                "footprint": "Resistor_SMD:R_0603_1608Metric",
+                "uuid": "1f8ab1be-1ad8-469d-8ba9-667910bdee9e",
+                "success": True,
+            }
+        }
+    )
+
+    reference: str = Field(
+        ...,
+        description="Component reference designator (e.g., 'R1', 'U2', 'C1')",
+        examples=["R1", "U2", "C1"],
+    )
+    lib_id: str = Field(
+        ...,
+        description="Library identifier (e.g., 'Device:R', 'Amplifier_Operational:TL072')",
+        examples=["Device:R", "Amplifier_Operational:TL072", "LED:LED"],
+    )
+    value: str = Field(
+        ...,
+        description="Component value or part description",
+        examples=["10k", "100nF", "TL072"],
+    )
+    position: PointModel = Field(
+        ...,
+        description="Component position in schematic coordinates (mm)",
+    )
+    rotation: float = Field(
+        ...,
+        description="Component rotation in degrees (0, 90, 180, or 270)",
+        examples=[0.0, 90.0, 180.0, 270.0],
+    )
+    footprint: Optional[str] = Field(
+        default=None,
+        description="PCB footprint identifier",
+        examples=["Resistor_SMD:R_0603_1608Metric", "Package_SO:SOIC-8_3.9x4.9mm_P1.27mm"],
+    )
+    uuid: str = Field(
+        ...,
+        description="Unique identifier for this component instance",
+        examples=["1f8ab1be-1ad8-469d-8ba9-667910bdee9e"],
+    )
+    success: bool = Field(
+        default=True,
+        description="Whether the operation was successful",
+    )
+    message: Optional[str] = Field(
+        default=None,
+        description="Optional message or error description",
+    )
+
+
+class ErrorOutput(BaseModel):
+    """Standard error response model."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "success": False,
+                "error": "COMPONENT_NOT_FOUND",
+                "message": "Component 'R999' not found in schematic",
+            }
+        }
+    )
+
+    success: bool = Field(
+        default=False,
+        description="Operation success status",
+    )
+    error: str = Field(
+        ...,
+        description="Error type or code",
+        examples=["COMPONENT_NOT_FOUND", "LIBRARY_ERROR"],
+    )
+    message: str = Field(
+        ...,
+        description="Detailed error message",
+    )

mcp_server/server.py

@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+"""
+MCP server main entry point for kicad-sch-api.
+
+Provides schematic management and pin discovery tools via the Model Context Protocol.
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+from fastmcp import FastMCP
+
+import kicad_sch_api as ksa
+from mcp_server.models import ErrorOutput
+from mcp_server.tools.pin_discovery import (
+    find_pins_by_name,
+    find_pins_by_type,
+    get_component_pins,
+    get_current_schematic,
+    set_current_schematic,
+)
+from mcp_server.tools.component_tools import (
+    add_component,
+    list_components,
+    update_component,
+    remove_component,
+    filter_components,
+)
+from mcp_server.tools.connectivity_tools import (
+    add_wire,
+    add_label,
+    add_junction,
+    connect_components,
+)
+from mcp_server.tools.consolidated_tools import (
+    manage_schematic,
+    manage_components,
+    manage_wires,
+    manage_labels,
+    manage_text_boxes,
+    manage_power,
+    manage_sheets,
+    manage_global_labels,
+)
+
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger(__name__)
+
+
+# Initialize FastMCP server
+mcp = FastMCP("kicad-sch-api")
+
+
+# ========== Schematic Management Tools ==========
+
+
+@mcp.tool()
+async def create_schematic(name: str) -> dict:
+    """
+    Create a new blank KiCAD schematic.
+
+    Args:
+        name: Project name for the schematic
+
+    Returns:
+        Dictionary with success status and schematic information
+
+    Examples:
+        >>> result = await create_schematic("MyProject")
+        >>> print(result['message'])
+        Created new schematic: MyProject
+    """
+    logger.info(f"[MCP] create_schematic called with name: {name}")
+
+    try:
+        # Create new schematic
+        schematic = ksa.create_schematic(name)
+
+        # Set as current working schematic
+        set_current_schematic(schematic)
+
+        logger.info(f"[MCP] Created and set schematic: {name}")
+        return {
+            "success": True,
+            "message": f"Created new schematic: {name}",
+            "project_name": name,
+            "uuid": str(schematic.uuid),
+        }
+
+    except Exception as e:
+        logger.error(f"[MCP] Error creating schematic: {e}", exc_info=True)
+        return {
+            "success": False,
+            "error": "CREATION_ERROR",
+            "message": f"Failed to create schematic: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def load_schematic(file_path: str) -> dict:
+    """
+    Load an existing KiCAD schematic file.
+
+    Args:
+        file_path: Absolute path to .kicad_sch file
+
+    Returns:
+        Dictionary with success status and schematic information
+
+    Examples:
+        >>> result = await load_schematic("/path/to/project.kicad_sch")
+        >>> print(f"Loaded: {result['project_name']}")
+    """
+    logger.info(f"[MCP] load_schematic called with path: {file_path}")
+
+    try:
+        # Validate path
+        path = Path(file_path)
+        if not path.exists():
+            logger.error(f"[MCP] File not found: {file_path}")
+            return {
+                "success": False,
+                "error": "FILE_NOT_FOUND",
+                "message": f"Schematic file not found: {file_path}",
+            }
+
+        if not path.suffix == ".kicad_sch":
+            logger.error(f"[MCP] Invalid file extension: {file_path}")
+            return {
+                "success": False,
+                "error": "INVALID_FILE",
+                "message": "File must have .kicad_sch extension",
+            }
+
+        # Load schematic
+        schematic = ksa.Schematic.load(str(path))
+
+        # Set as current working schematic
+        set_current_schematic(schematic)
+
+        # Count components
+        component_count = len(list(schematic.components.all()))
+
+        logger.info(
+            f"[MCP] Loaded schematic: {schematic.title_block.title} "
+            f"({component_count} components)"
+        )
+        return {
+            "success": True,
+            "message": f"Loaded schematic: {path.name}",
+            "file_path": str(path),
+            "project_name": schematic.title_block.title,
+            "uuid": str(schematic.uuid),
+            "component_count": component_count,
+        }
+
+    except Exception as e:
+        logger.error(f"[MCP] Error loading schematic: {e}", exc_info=True)
+        return {
+            "success": False,
+            "error": "LOAD_ERROR",
+            "message": f"Failed to load schematic: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def save_schematic(file_path: Optional[str] = None) -> dict:
+    """
+    Save the current schematic to disk.
+
+    Args:
+        file_path: Optional path to save to. If not provided, saves to original location.
+
+    Returns:
+        Dictionary with success status
+
+    Examples:
+        >>> # Save to original location
+        >>> result = await save_schematic()
+
+        >>> # Save to new location
+        >>> result = await save_schematic("/path/to/new_location.kicad_sch")
+    """
+    logger.info(f"[MCP] save_schematic called with path: {file_path}")
+
+    # Check if schematic is loaded
+    schematic = get_current_schematic()
+    if schematic is None:
+        logger.error("[MCP] No schematic loaded")
+        return {
+            "success": False,
+            "error": "NO_SCHEMATIC_LOADED",
+            "message": "No schematic is currently loaded. Please load or create a schematic first.",
+        }
+
+    try:
+        if file_path:
+            # Save to specified path
+            path = Path(file_path)
+            if not path.suffix == ".kicad_sch":
+                logger.error(f"[MCP] Invalid file extension: {file_path}")
+                return {
+                    "success": False,
+                    "error": "INVALID_FILE",
+                    "message": "File must have .kicad_sch extension",
+                }
+            schematic.save(str(path))
+            logger.info(f"[MCP] Saved schematic to: {path}")
+            return {
+                "success": True,
+                "message": f"Saved schematic to: {path.name}",
+                "file_path": str(path),
+            }
+        else:
+            # Save to original location
+            schematic.save()
+            logger.info("[MCP] Saved schematic to original location")
+            return {
+                "success": True,
+                "message": "Saved schematic to original location",
+            }
+
+    except Exception as e:
+        logger.error(f"[MCP] Error saving schematic: {e}", exc_info=True)
+        return {
+            "success": False,
+            "error": "SAVE_ERROR",
+            "message": f"Failed to save schematic: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def get_schematic_info() -> dict:
+    """
+    Get information about the currently loaded schematic.
+
+    Returns:
+        Dictionary with schematic metadata
+
+    Examples:
+        >>> result = await get_schematic_info()
+        >>> print(f"Components: {result['component_count']}")
+    """
+    logger.info("[MCP] get_schematic_info called")
+
+    # Check if schematic is loaded
+    schematic = get_current_schematic()
+    if schematic is None:
+        logger.error("[MCP] No schematic loaded")
+        return {
+            "success": False,
+            "error": "NO_SCHEMATIC_LOADED",
+            "message": "No schematic is currently loaded",
+        }
+
+    try:
+        # Collect schematic information
+        components = list(schematic.components.all())
+        component_refs = [c.reference for c in components]
+
+        info = {
+            "success": True,
+            "project_name": schematic.title_block.title,
+            "uuid": str(schematic.uuid),
+            "component_count": len(components),
+            "component_references": component_refs,
+            "lib_symbols_count": len(schematic.lib_symbols),
+        }
+
+        logger.info(
+            f"[MCP] Schematic info: {info['project_name']} ({info['component_count']} components)"
+        )
+        return info
+
+    except Exception as e:
+        logger.error(f"[MCP] Error getting schematic info: {e}", exc_info=True)
+        return {
+            "success": False,
+            "error": "INTERNAL_ERROR",
+            "message": f"Failed to get schematic info: {str(e)}",
+        }
+
+
+# ========== Register Pin Discovery Tools ==========
+
+# Register the pin discovery tools from pin_discovery.py
+mcp.tool()(get_component_pins)
+mcp.tool()(find_pins_by_name)
+mcp.tool()(find_pins_by_type)
+
+
+# ========== Register Component Management Tools ==========
+
+# Register the component management tools from component_tools.py
+mcp.tool()(add_component)
+mcp.tool()(list_components)
+mcp.tool()(update_component)
+mcp.tool()(remove_component)
+mcp.tool()(filter_components)
+
+
+# ========== Register Connectivity Tools ==========
+
+# Register the connectivity tools from connectivity_tools.py
+mcp.tool()(add_wire)
+mcp.tool()(add_label)
+mcp.tool()(add_junction)
+mcp.tool()(connect_components)
+
+
+# ========== Register Consolidated Tools ==========
+
+# Register the 8 consolidated CRUD tools for schematic management
+# These tools consolidate all operations by entity type with action parameters
+mcp.tool()(manage_schematic)      # Schematic: create, read, save, load
+mcp.tool()(manage_components)     # Components: add, list, get_pins, update, remove
+mcp.tool()(manage_wires)          # Wires: add, remove
+mcp.tool()(manage_labels)         # Labels: add, remove
+mcp.tool()(manage_text_boxes)     # TextBoxes: add, update, remove
+mcp.tool()(manage_power)          # Power: add, list, remove
+mcp.tool()(manage_sheets)         # Sheets: add, set_context, list, remove
+mcp.tool()(manage_global_labels)  # GlobalLabels: add, remove
+
+
+# ========== Server Entry Point ==========
+
+
+def main() -> None:
+    """
+    Main entry point for the MCP server.
+
+    Starts the FastMCP server with STDIO transport for Claude Desktop integration.
+    """
+    logger.info("Starting kicad-sch-api MCP server...")
+    logger.info(f"kicad-sch-api version: {ksa.__version__}")
+
+    try:
+        # Run the MCP server with STDIO transport
+        mcp.run(transport="stdio")
+    except KeyboardInterrupt:
+        logger.info("Server shutdown requested")
+        sys.exit(0)
+    except Exception as e:
+        logger.error(f"Server error: {e}", exc_info=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

mcp_server/tools/__init__.py

@@ -0,0 +1,32 @@
+"""
+MCP tools for kicad-sch-api.
+
+Provides tool implementations for pin discovery, component manipulation,
+and connectivity operations.
+"""
+
+from mcp_server.tools.connectivity_tools import (
+    add_junction,
+    add_label,
+    add_wire,
+    connect_components,
+)
+from mcp_server.tools.pin_discovery import (
+    find_pins_by_name,
+    find_pins_by_type,
+    get_component_pins,
+    get_current_schematic,
+    set_current_schematic,
+)
+
+__all__ = [
+    "get_component_pins",
+    "find_pins_by_name",
+    "find_pins_by_type",
+    "get_current_schematic",
+    "set_current_schematic",
+    "add_wire",
+    "add_label",
+    "add_junction",
+    "connect_components",
+]