kicad-mcp-server/docs/LIBRARY_INTEGRATION.md

# KiCAD Library Integration

**Status:** ✅ COMPLETE
**Date:** 2026-03-21
**Version:** 2.2.3+

## Overview

The KiCAD MCP Server includes full library integration for both footprints and symbols, enabling:
- ✅ Automatic discovery of all installed KiCAD footprint libraries
- ✅ Automatic discovery of KiCAD symbol libraries (including project-local)
- ✅ Search and browse footprints/symbols across all libraries
- ✅ Component placement using library footprints
- ✅ Symbol creation and editing with project-local library support (v2.2.2+)
- ✅ Support for both `Library:Footprint` and `Footprint` formats

## How It Works

### Library Discovery

The library system automatically discovers both footprint and symbol libraries:

**Footprint Libraries** - `LibraryManager` class:

1. **Parsing fp-lib-table files:**
   - Global: `~/.config/kicad/9.0/fp-lib-table`
   - Project-specific: `project-dir/fp-lib-table`

**Symbol Libraries** - `DynamicSymbolLoader` class (v2.2.2+):

1. **Parsing sym-lib-table files:**
   - Global: `~/.config/kicad/9.0/sym-lib-table`
   - Project-local: `project-dir/sym-lib-table` (added v2.2.2)

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

**2026-03-21 - v2.2.3+**
- ✅ Project-local symbol library support (v2.2.2)
- ✅ Project-local footprint library support (v2.2.2)
- ✅ 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.