KiCAD-MCP-Server

# KiCAD Footprint Library Integration **Status:** ✅ COMPLETE (Week 2 - Component Library Integration) **Date:** 2025-11-01 **Version:** 2.1.0-alpha ## Overview The KiCAD MCP Server now includes full footprint library integration, enabling: - ✅ Automatic discovery of all installed KiCAD footprint libraries - ✅ Search and browse footprints across all libraries - ✅ Component placement using library footprints - ✅ Support for both `Library:Footprint` and `Footprint` formats ## How It Works ### Library Discovery The `LibraryManager` class automatically discovers footprint libraries by: 1. **Parsing fp-lib-table files:** - Global: `~/.config/kicad/9.0/fp-lib-table` - Project-specific: `project-dir/fp-lib-table` 2. **Resolving environment variables:** - `${KICAD9_FOOTPRINT_DIR}` → `/usr/share/kicad/footprints` - `${K IPRJMOD}` → project directory - Supports custom paths 3. **Indexing footprints:** - Scans `.kicad_mod` files in each library - Caches results for performance - Provides fast search capabilities ### Supported Formats **Library:Footprint format (recommended):** ```json { "componentId": "Resistor_SMD:R_0603_1608Metric" } ``` **Footprint-only format (searches all libraries):** ```json { "componentId": "R_0603_1608Metric" } ``` ## New MCP Tools ### 1. `list_libraries` List all available footprint libraries. **Parameters:** None **Returns:** ```json { "success": true, "libraries": ["Resistor_SMD", "Capacitor_SMD", "LED_SMD", ...], "count": 153 } ``` ### 2. `search_footprints` Search for footprints matching a pattern. **Parameters:** ```json { "pattern": "*0603*", // Supports wildcards "limit": 20 // Optional, default: 20 } ``` **Returns:** ```json { "success": true, "footprints": [ { "library": "Resistor_SMD", "footprint": "R_0603_1608Metric", "full_name": "Resistor_SMD:R_0603_1608Metric" }, ... ] } ``` ### 3. `list_library_footprints` List all footprints in a specific library. **Parameters:** ```json { "library": "Resistor_SMD" } ``` **Returns:** ```json { "success": true, "library": "Resistor_SMD", "footprints": ["R_0402_1005Metric", "R_0603_1608Metric", ...], "count": 120 } ``` ### 4. `get_footprint_info` Get detailed information about a specific footprint. **Parameters:** ```json { "footprint": "Resistor_SMD:R_0603_1608Metric" } ``` **Returns:** ```json { "success": true, "footprint_info": { "library": "Resistor_SMD", "footprint": "R_0603_1608Metric", "full_name": "Resistor_SMD:R_0603_1608Metric", "library_path": "/usr/share/kicad/footprints/Resistor_SMD.pretty" } } ``` ## Updated Component Placement The `place_component` tool now uses the library system: ```json { "componentId": "Resistor_SMD:R_0603_1608Metric", // Library:Footprint format "position": {"x": 50, "y": 40, "unit": "mm"}, "reference": "R1", "value": "10k", "rotation": 0, "layer": "F.Cu" } ``` **Features:** - ✅ Automatic footprint discovery across all libraries - ✅ Helpful error messages with suggestions - ✅ Supports KiCAD 9.0 API (EDA_ANGLE, GetFPIDAsString) ## Example Usage (Claude Code) **Search for a resistor footprint:** ``` User: "Find me a 0603 resistor footprint" Claude: [uses search_footprints tool with pattern "*R_0603*"] Found: Resistor_SMD:R_0603_1608Metric ``` **Place a component:** ``` User: "Place a 10k 0603 resistor at 50,40mm" Claude: [uses place_component with "Resistor_SMD:R_0603_1608Metric"] ✅ Placed R1: 10k at (50, 40) mm ``` **List available capacitors:** ``` User: "What capacitor footprints are available?" Claude: [uses list_library_footprints with "Capacitor_SMD"] Found 103 capacitor footprints including: - C_0402_1005Metric - C_0603_1608Metric - C_0805_2012Metric ... ``` ## Configuration ### Custom Library Paths The system automatically detects KiCAD installations, but you can add custom libraries: 1. **Via KiCAD Preferences:** - Open KiCAD → Preferences → Manage Footprint Libraries - Add your custom library paths - The MCP server will automatically discover them 2. **Via Project fp-lib-table:** - Create `fp-lib-table` in your project directory - Follow the KiCAD S-expression format ### Supported Platforms - ✅ **Linux:** `/usr/share/kicad/footprints`, `~/.config/kicad/9.0/` - ✅ **Windows:** `C:/Program Files/KiCAD/*/share/kicad/footprints` - ✅ **macOS:** `/Applications/KiCad/KiCad.app/Contents/SharedSupport/footprints` ## KiCAD 9.0 API Compatibility The library integration includes full KiCAD 9.0 API support: ### Fixed API Changes: 1. ✅ `SetOrientation()` → now uses `EDA_ANGLE(degrees, DEGREES_T)` 2. ✅ `GetOrientation()` → returns `EDA_ANGLE`, call `.AsDegrees()` 3. ✅ `GetFootprintName()` → now `GetFPIDAsString()` ### Example Fixes: **Old (KiCAD 8.0):** ```python module.SetOrientation(90 * 10) # Decidegrees rotation = module.GetOrientation() / 10 ``` **New (KiCAD 9.0):** ```python angle = pcbnew.EDA_ANGLE(90, pcbnew.DEGREES_T) module.SetOrientation(angle) rotation = module.GetOrientation().AsDegrees() ``` ## Implementation Details ### LibraryManager Class **Location:** `python/commands/library.py` **Key Methods:** - `_load_libraries()` - Parse fp-lib-table files - `_parse_fp_lib_table()` - S-expression parser - `_resolve_uri()` - Handle environment variables - `find_footprint()` - Locate footprint in libraries - `search_footprints()` - Pattern-based search - `list_footprints()` - List library contents **Performance:** - Libraries loaded once at startup - Footprint lists cached on first access - Fast search using Python regex - Minimal memory footprint ### Integration Points 1. **KiCADInterface (`kicad_interface.py`):** - Creates `FootprintLibraryManager` on init - Passes to `ComponentCommands` - Routes library commands 2. **ComponentCommands (`component.py`):** - Uses `LibraryManager.find_footprint()` - Provides suggestions on errors - Supports both lookup formats 3. **MCP Tools (`src/tools/index.ts`):** - Exposes 4 new library tools - Fully typed TypeScript interfaces - Documented parameters ## Testing **Test Coverage:** - ✅ Library path discovery (Linux/Windows/macOS) - ✅ fp-lib-table parsing - ✅ Environment variable resolution - ✅ Footprint search and lookup - ✅ Component placement integration - ✅ Error handling and suggestions **Verified With:** - KiCAD 9.0.5 on Ubuntu 24.04 - 153 standard libraries (8,000+ footprints) - pcbnew Python API ## Known Limitations 1. **Library Updates:** Changes to fp-lib-table require server restart 2. **Custom Libraries:** Must be added via KiCAD preferences first 3. **Network Libraries:** GitHub-based libraries not yet supported 4. **Search Performance:** Linear search across all libraries (fast for <200 libs) ## Future Enhancements - [ ] Watch fp-lib-table for changes (auto-reload) - [ ] Support for GitHub library URLs - [ ] Fuzzy search for typo tolerance - [ ] Library metadata (descriptions, categories) - [ ] Footprint previews (SVG/PNG generation) - [ ] Most-used footprints caching ## Troubleshooting ### "No footprint libraries found" **Cause:** fp-lib-table not found or empty **Solution:** 1. Verify KiCAD is installed 2. Open KiCAD and ensure libraries are configured 3. Check `~/.config/kicad/9.0/fp-lib-table` exists ### "Footprint not found" **Cause:** Footprint doesn't exist or library not loaded **Solution:** 1. Use `search_footprints` to find similar footprints 2. Check library name is correct 3. Verify library is in fp-lib-table ### "Failed to load footprint" **Cause:** Corrupt .kicad_mod file or permissions issue **Solution:** 1. Check file permissions on library directories 2. Reinstall KiCAD libraries if corrupt 3. Check logs for detailed error ## Related Documentation - [ROADMAP.md](./ROADMAP.md) - Week 2 planning - [STATUS_SUMMARY.md](./STATUS_SUMMARY.md) - Current implementation status - [API.md](./API.md) - Full MCP API reference - [KiCAD Documentation](https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html) - Official KiCAD docs ## Changelog **2025-11-01 - v2.1.0-alpha** - ✅ Implemented LibraryManager class - ✅ Added 4 new MCP library tools - ✅ Updated component placement to use libraries - ✅ Fixed all KiCAD 9.0 API compatibility issues - ✅ Tested end-to-end with real components - ✅ Created comprehensive documentation --- **Status: PRODUCTION READY** 🎉 The library integration is complete and fully functional. Component placement now works seamlessly with KiCAD's footprint libraries, enabling AI-driven PCB design with real, validated components.