KiCAD-MCP-Server

# KiCAD IPC API Migration Plan **Status:** 📋 Planning **Target Completion:** Week 2-3 (November 1-8, 2025) **Priority:** 🔴 **CRITICAL** - Current SWIG API deprecated --- ## Executive Summary The current KiCAD MCP Server uses SWIG-based Python bindings (`import pcbnew`) which are **deprecated as of KiCAD 9.0** and will be **removed in KiCAD 10.0**. We must migrate to the official **KiCAD IPC API** to future-proof the project. ### Why Migrate? | SWIG API (Current) | IPC API (Future) | |-------------------|------------------| | ❌ Deprecated | ✅ Official & Supported | | ❌ Will be removed in KiCAD 10.0 | ✅ Long-term stability | | ❌ Python-only | ✅ Multi-language (Python, JS, etc.) | | ❌ Direct linking | ✅ Inter-process communication | | ⚠️ Synchronous only | ✅ Async support | | ⚠️ No versioning | ✅ Protocol Buffers versioning | **Decision: Migrate immediately to avoid technical debt** --- ## IPC API Overview ### Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ TypeScript MCP Server (Node.js) │ └──────────────────────┬──────────────────────────────────────┘ │ JSON over stdin/stdout ┌──────────────────────▼──────────────────────────────────────┐ │ Python Interface Layer │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ KiCAD API Abstraction (NEW) │ │ │ └────────────────────────────────────────────────────────┘ │ └──────────────────────┬──────────────────────────────────────┘ │ kicad-python library ┌──────────────────────▼──────────────────────────────────────┐ │ KiCAD IPC Server (Protocol Buffers) │ │ Running inside KiCAD Process │ └──────────────────────┬──────────────────────────────────────┘ │ UNIX Sockets / Named Pipes ┌──────────────────────▼──────────────────────────────────────┐ │ KiCAD 9.0+ Application │ └─────────────────────────────────────────────────────────────┘ ``` ### Key Differences 1. **KiCAD Must Be Running** - SWIG: Can run headless, no KiCAD GUI needed - IPC: Requires KiCAD running with IPC server enabled 2. **Communication Method** - SWIG: Direct Python module import - IPC: Socket-based RPC (Remote Procedure Call) 3. **API Structure** - SWIG: `board.SetSize(width, height)` - IPC: `kicad.get_board().set_size(width, height)` --- ## Migration Strategy ### Phase 1: Research & Preparation (Days 1-2) **Goals:** - Understand kicad-python library - Test IPC connection - Document API differences **Tasks:** ```bash # Install kicad-python pip install kicad-python>=0.5.0 # Test basic connection python3 << EOF from kicad import KiCad kicad = KiCad() print(f"Connected to KiCAD: {kicad.check_version()}") EOF # Read official documentation # https://docs.kicad.org/kicad-python-main ``` **Deliverables:** - [ ] kicad-python installed and tested - [ ] Connection test script - [ ] API comparison document (SWIG vs IPC) --- ### Phase 2: Abstraction Layer (Days 3-4) **Goal:** Create an abstraction layer to support both APIs during transition **File Structure:** ``` python/kicad_api/ ├── __init__.py ├── base.py # Abstract base class ├── ipc_backend.py # NEW: IPC API implementation ├── swig_backend.py # Legacy SWIG implementation └── factory.py # Backend selector ``` **Abstract Interface:** ```python # python/kicad_api/base.py from abc import ABC, abstractmethod from typing import Optional from pathlib import Path class KiCADBackend(ABC): """Abstract base class for KiCAD API backends""" @abstractmethod def connect(self) -> bool: """Connect to KiCAD""" pass @abstractmethod def disconnect(self) -> None: """Disconnect from KiCAD""" pass @abstractmethod def is_connected(self) -> bool: """Check if connected""" pass @abstractmethod def create_project(self, path: Path, name: str) -> dict: """Create a new KiCAD project""" pass @abstractmethod def open_project(self, path: Path) -> dict: """Open existing project""" pass @abstractmethod def get_board(self) -> 'BoardAPI': """Get board API""" pass # ... more abstract methods ``` **IPC Implementation:** ```python # python/kicad_api/ipc_backend.py from kicad import KiCad from kicad_api.base import KiCADBackend class IPCBackend(KiCADBackend): """KiCAD IPC API backend""" def __init__(self): self.kicad = None def connect(self) -> bool: """Connect to running KiCAD instance""" try: self.kicad = KiCad() # Verify connection version = self.kicad.check_version() logger.info(f"Connected to KiCAD via IPC: {version}") return True except Exception as e: logger.error(f"Failed to connect via IPC: {e}") return False def create_project(self, path: Path, name: str) -> dict: """Create project using IPC API""" # Implementation here pass ``` **Backend Factory:** ```python # python/kicad_api/factory.py from typing import Optional from kicad_api.base import KiCADBackend from kicad_api.ipc_backend import IPCBackend from kicad_api.swig_backend import SWIGBackend def create_backend(backend_type: Optional[str] = None) -> KiCADBackend: """ Create appropriate KiCAD backend Args: backend_type: 'ipc', 'swig', or None for auto-detect Returns: KiCADBackend instance """ if backend_type == 'ipc': return IPCBackend() elif backend_type == 'swig': return SWIGBackend() else: # Auto-detect: Try IPC first, fall back to SWIG try: backend = IPCBackend() if backend.connect(): return backend except ImportError: pass # Fall back to SWIG return SWIGBackend() ``` **Deliverables:** - [ ] Abstract base class defined - [ ] IPC backend implemented - [ ] SWIG backend (wrapper around existing code) - [ ] Factory with auto-detection --- ### Phase 3: Port Core Modules (Days 5-8) **Migration Order** (by complexity): 1. **project.py** (Simple - good starting point) - Create, open, save projects - Estimated: 2 hours 2. **board.py** (Medium - board properties) - Set size, layers, outline - Estimated: 4 hours 3. **component.py** (Complex - many operations) - Place, move, rotate, delete - Component arrays and alignment - Estimated: 8 hours 4. **routing.py** (Complex - trace routing) - Nets, traces, vias - Copper pours, differential pairs - Estimated: 8 hours 5. **design_rules.py** (Medium - DRC) - Set rules, run DRC - Estimated: 4 hours 6. **export.py** (Medium - file exports) - Gerber, PDF, SVG, 3D - Estimated: 4 hours **Total Estimated Time: 30 hours (~4 days)** **Migration Template:** ```python # OLD (SWIG) import pcbnew board = pcbnew.LoadBoard(filename) board.SetBoardSize(width, height) # NEW (IPC via abstraction) from kicad_api import create_backend backend = create_backend('ipc') backend.connect() board_api = backend.get_board() board_api.set_size(width, height) ``` **Deliverables:** - [ ] project.py migrated - [ ] board.py migrated - [ ] component.py migrated - [ ] routing.py migrated - [ ] design_rules.py migrated - [ ] export.py migrated --- ### Phase 4: Testing & Validation (Days 9-10) **Testing Strategy:** 1. **Unit Tests** ```python @pytest.mark.parametrize("backend_type", ["ipc", "swig"]) def test_create_project(backend_type): backend = create_backend(backend_type) result = backend.create_project(Path("/tmp/test"), "TestProject") assert result["success"] is True ``` 2. **Integration Tests** - Run side-by-side: IPC vs SWIG - Compare outputs for identical operations - Verify file compatibility 3. **Performance Benchmarks** ```python # Measure: operations/second for each backend # Expected: IPC slightly slower due to IPC overhead ``` **Deliverables:** - [ ] 50+ unit tests passing for IPC backend - [ ] Side-by-side comparison tests - [ ] Performance benchmarks documented --- ## API Comparison Reference ### Project Operations | Operation | SWIG | IPC | |-----------|------|-----| | Create project | Custom file creation | `kicad.create_project()` | | Open project | `pcbnew.LoadBoard()` | `kicad.open_project()` | | Save project | `board.Save()` | `board.save()` | ### Board Operations | Operation | SWIG | IPC | |-----------|------|-----| | Get board | `pcbnew.LoadBoard()` | `kicad.get_board()` | | Set size | `board.SetBoardSize()` | `board.set_size()` | | Add layer | `board.GetLayerCount()` | `board.layers.add()` | ### Component Operations | Operation | SWIG | IPC | |-----------|------|-----| | Place component | `pcbnew.FOOTPRINT()` | `board.add_footprint()` | | Move component | `fp.SetPosition()` | `footprint.set_position()` | | Rotate component | `fp.SetOrientation()` | `footprint.set_rotation()` | ### Routing Operations | Operation | SWIG | IPC | |-----------|------|-----| | Add net | `board.GetNetCount()` | `board.nets.add()` | | Route trace | `pcbnew.PCB_TRACK()` | `board.add_track()` | | Add via | `pcbnew.PCB_VIA()` | `board.add_via()` | --- ## Configuration Changes ### Update requirements.txt ```diff + # KiCAD IPC API (official Python bindings) + kicad-python>=0.5.0 # Legacy SWIG support (for backward compatibility) kicad-skip>=0.1.0 ``` ### Environment Variables ```bash # Enable IPC API in KiCAD preferences # Preferences > Plugins > Enable IPC API Server # Set backend preference (optional) export KICAD_BACKEND=ipc # or 'swig' or 'auto' ``` ### User Migration Guide Create `docs/MIGRATING_TO_IPC.md`: - How to enable IPC in KiCAD - What changes for users - Troubleshooting IPC connection issues --- ## Rollback Plan If IPC migration fails: 1. **Keep SWIG backend** - Already abstracted 2. **Default to SWIG** - Change factory auto-detection 3. **Document limitations** - Note that SWIG will be removed eventually 4. **Plan retry** - Schedule IPC migration for later --- ## Success Criteria - [ ] ✅ All existing functionality works with IPC backend - [ ] ✅ Tests pass with both IPC and SWIG backends - [ ] ✅ Performance acceptable (< 20% slowdown vs SWIG) - [ ] ✅ Documentation updated - [ ] ✅ Migration guide created - [ ] ✅ User-facing tools work without changes --- ## Timeline | Week | Days | Tasks | |------|------|-------| | **Week 2** | Mon-Tue | Research, install kicad-python, test connection | | | Wed-Thu | Build abstraction layer | | | Fri | Port project.py and board.py | | **Week 3** | Mon-Tue | Port component.py and routing.py | | | Wed | Port design_rules.py and export.py | | | Thu-Fri | Testing, validation, documentation | --- ## Resources - **Official Docs:** https://docs.kicad.org/kicad-python-main - **kicad-python PyPI:** https://pypi.org/project/kicad-python/ - **IPC API Spec:** https://dev-docs.kicad.org/en/apis-and-binding/ipc-api/ - **Protocol Buffers:** Used by IPC for message format --- ## Open Questions 1. **How to handle KiCAD not running?** - Option A: Auto-launch KiCAD in background - Option B: Require user to launch KiCAD first - Option C: Fall back to SWIG if IPC unavailable - **Decision: Option C for now, A later** 2. **Connection management** - Should we keep connection open or connect per-operation? - **Decision: Keep alive with reconnect logic** 3. **Performance vs reliability** - IPC has overhead but more stable - **Decision: Reliability > performance** --- ## Next Steps (This Week) 1. **Install kicad-python** ```bash pip install kicad-python ``` 2. **Test IPC connection** ```bash # Launch KiCAD # Enable IPC in preferences python3 -c "from kicad import KiCad; k=KiCad(); print(k.check_version())" ``` 3. **Create abstraction layer structure** ```bash mkdir -p python/kicad_api touch python/kicad_api/{__init__,base,ipc_backend,swig_backend,factory}.py ``` 4. **Begin project.py migration** - Start with simplest module - Establish patterns for others --- **Prepared by:** Claude Code **Last Updated:** October 25, 2025 **Status:** 📋 Ready to execute