nearxos/kicad-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Extend IPC backend with 21 commands and hybrid footprint placement

Browse Source 
- Add IPC handlers for zone operations (add_copper_pour, refill_zones)
- Add IPC handlers for board operations (add_board_outline, add_mounting_hole, get_layer_list)
- Add IPC handlers for component operations (rotate_component, get_component_properties)
- Add IPC handlers for net operations (delete_trace, get_nets_list)
- Implement hybrid footprint placement (SWIG library loading + IPC placement)
- Extend create_schematic to handle filename, title, projectName params
- Update documentation for IPC backend status and known issues

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
KiCAD MCP Bot
2025-12-03 08:48:37 -05:00
parent 03d7de980a
commit 119f1dfc16
6 changed files with 1040 additions and 446 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
docs/IPC_BACKEND_STATUS.md
View File

@@ -1,7 +1,7 @@
# KiCAD IPC Backend Implementation Status
**Status:** 🟢 **FULLY INTEGRATED**
**Date:** 2025-11-30
**Status:** Under Active Development and Testing
**Date:** 2025-12-02
**KiCAD Version:** 9.0.6
**kicad-python Version:** 0.5.0
@@ -9,80 +9,94 @@
## Overview
The IPC backend is now **fully integrated** as the **default backend** for all MCP tools. When KiCAD is running with IPC enabled, all commands automatically use real-time UI synchronization. Changes made through the MCP tools appear **instantly** in the KiCAD UI without requiring manual reload.
The IPC backend provides real-time UI synchronization with KiCAD 9.0+ via the official IPC API. When KiCAD is running with IPC enabled, commands can update the KiCAD UI immediately without requiring manual reload.
**SWIG backend is deprecated** and will be removed in a future version when KiCAD removes it (KiCAD 10.0).
This feature is experimental and under active testing. The server uses a hybrid approach: IPC when available, automatic fallback to SWIG when IPC is not connected.
## Key Benefits
## Key Differences
| Feature | SWIG (Old) | IPC (New) |
|---------|------------|-----------|
| UI Updates | Manual reload required | **Instant** |
| Undo/Redo | Not supported | **Transaction support** |
| API Stability | Deprecated, will break | **Stable, versioned** |
| Connection | File-based | **Live socket connection** |
| Future Support | Removed in KiCAD 10.0 | **Official & maintained** |
| Feature | SWIG | IPC |
|---------|------|-----|
| UI Updates | Manual reload required | Immediate (when working) |
| Undo/Redo | Not supported | Transaction support |
| API Stability | Deprecated in KiCAD 9 | Official, versioned |
| Connection | File-based | Live socket connection |
| KiCAD Required | No (file operations) | Yes (must be running) |
## Implemented Features
## Implemented IPC Commands
### Automatic IPC Routing
The following MCP commands **automatically use IPC** when available:
The following MCP commands have IPC handlers:
| Command | IPC Handler | Real-time |
|---------|-------------|-----------|
| `route_trace` | `_ipc_route_trace` | Yes |
| `add_via` | `_ipc_add_via` | Yes |
| `add_net` | `_ipc_add_net` | Yes |
| `add_text` | `_ipc_add_text` | Yes |
| `add_board_text` | `_ipc_add_text` | Yes |
| `set_board_size` | `_ipc_set_board_size` | Yes |
| `get_board_info` | `_ipc_get_board_info` | Yes |
| `place_component` | `_ipc_place_component` | Yes |
| `move_component` | `_ipc_move_component` | Yes |
| `delete_component` | `_ipc_delete_component` | Yes |
| `get_component_list` | `_ipc_get_component_list` | Yes |
| `save_project` | `_ipc_save_project` | Yes |
| Command | IPC Handler | Status |
|---------|-------------|--------|
| `route_trace` | `_ipc_route_trace` | Implemented |
| `add_via` | `_ipc_add_via` | Implemented |
| `add_net` | `_ipc_add_net` | Implemented |
| `delete_trace` | `_ipc_delete_trace` | Falls back to SWIG |
| `get_nets_list` | `_ipc_get_nets_list` | Implemented |
| `add_copper_pour` | `_ipc_add_copper_pour` | Implemented |
| `refill_zones` | `_ipc_refill_zones` | Implemented |
| `add_text` | `_ipc_add_text` | Implemented |
| `add_board_text` | `_ipc_add_text` | Implemented |
| `set_board_size` | `_ipc_set_board_size` | Implemented |
| `get_board_info` | `_ipc_get_board_info` | Implemented |
| `add_board_outline` | `_ipc_add_board_outline` | Implemented |
| `add_mounting_hole` | `_ipc_add_mounting_hole` | Implemented |
| `get_layer_list` | `_ipc_get_layer_list` | Implemented |
| `place_component` | `_ipc_place_component` | Implemented (hybrid) |
| `move_component` | `_ipc_move_component` | Implemented |
| `rotate_component` | `_ipc_rotate_component` | Implemented |
| `delete_component` | `_ipc_delete_component` | Implemented |
| `get_component_list` | `_ipc_get_component_list` | Implemented |
| `get_component_properties` | `_ipc_get_component_properties` | Implemented |
| `save_project` | `_ipc_save_project` | Implemented |
### Core Connection
- [x] Connect to running KiCAD instance
- [x] Auto-detect socket path (`/tmp/kicad/api.sock`)
- [x] Version checking and validation
- [x] Ping/health check
- [x] Auto-fallback to SWIG when IPC unavailable
- [x] Change notification callbacks
### Implemented Backend Features
### Board Operations
- [x] Get board reference
- [x] Get/Set board size (via Edge.Cuts)
- [x] List enabled layers
- [x] Save board
- [x] Get board bounding box
**Core Connection:**
- Connect to running KiCAD instance
- Auto-detect socket path (`/tmp/kicad/api.sock`)
- Version checking and validation
- Auto-fallback to SWIG when IPC unavailable
- Change notification callbacks
### Component Operations
- [x] List all components
- [x] Place component (real-time)
- [x] Move component (real-time)
- [x] Delete component (real-time)
- [x] Get component properties
**Board Operations:**
- Get board reference
- Get/Set board size
- List enabled layers
- Save board
- Add board outline segments
- Add mounting holes
### Routing Operations
- [x] Add track (real-time)
- [x] Add via (real-time)
- [x] Get all tracks
- [x] Get all vias
- [x] Get all nets
**Component Operations:**
- List all components
- Place component (hybrid: SWIG for library loading, IPC for placement)
- Move component
- Rotate component
- Delete component
- Get component properties
### UI Integration
- [x] Add text to board (real-time)
- [x] Get current selection
- [x] Clear selection
- [x] Refill zones
**Routing Operations:**
- Add track
- Add via
- Get all tracks
- Get all vias
- Get all nets
### Transaction Support
- [x] Begin transaction
- [x] Commit transaction (with description)
- [x] Rollback transaction
- [x] Proper undo/redo in KiCAD
**Zone Operations:**
- Add copper pour zones
- Get zones list
- Refill zones
**UI Integration:**
- Add text to board
- Get current selection
- Clear selection
**Transaction Support:**
- Begin transaction
- Commit transaction (with description for undo)
- Rollback transaction
## Usage
@@ -98,46 +112,7 @@ The following MCP commands **automatically use IPC** when available:
pip install kicad-python
```
### Basic Usage
```python
from kicad_api import create_backend
# Auto-detect and connect
backend = create_backend() # Will try IPC first, fall back to SWIG
backend.connect()
# Get board API
board = backend.get_board()
# Operations appear instantly in KiCAD UI!
board.add_track(
start_x=100.0, start_y=100.0,
end_x=120.0, end_y=100.0,
width=0.25, layer="F.Cu"
)
# With transaction support for undo
board.begin_transaction("Add components")
board.place_component("R1", "Resistor_SMD:R_0603", 50, 50)
board.place_component("C1", "Capacitor_SMD:C_0603", 60, 50)
board.commit_transaction("Added R1 and C1") # Single undo step
```
### Force Backend Selection
```python
# Force IPC backend
backend = create_backend('ipc')
# Force SWIG backend (deprecated)
backend = create_backend('swig')
# Or via environment variable
# export KICAD_BACKEND=ipc
```
## Testing
### Testing
Run the test script to verify IPC functionality:
@@ -146,46 +121,43 @@ Run the test script to verify IPC functionality:
./venv/bin/python python/test_ipc_backend.py
```
The test script will:
1. Connect to KiCAD
2. List components on the board
3. Add a test track (visible instantly in UI)
4. Add a test via (visible instantly in UI)
5. Add test text (visible instantly in UI)
6. Read the current selection
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Server (TypeScript/Node.js) │
└──────────────────────┬──────────────────────────────────────┘
│ JSON commands
┌──────────────────────▼──────────────────────────────────────┐
│ Python Interface Layer │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ kicad_api/ipc_backend.py │ │
│ │ - IPCBackend (connection management) │ │
│ │ - IPCBoardAPI (board operations) │ │
│ └────────────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────────┘
│ kicad-python (kipy) library
┌──────────────────────▼──────────────────────────────────────┐
│ Protocol Buffers over UNIX Sockets │
└──────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────────────┐
│ KiCAD 9.0+ (IPC Server) │
│ Changes appear instantly in UI! │
└─────────────────────────────────────────────────────────────┘
+-------------------------------------------------------------+
| MCP Server (TypeScript/Node.js) |
+---------------------------+---------------------------------+
| JSON commands
+---------------------------v---------------------------------+
| Python Interface Layer |
| +--------------------------------------------------------+ |
| | kicad_interface.py | |
| | - Routes commands to IPC or SWIG handlers | |
| | - IPC_CAPABLE_COMMANDS dict defines routing | |
| +--------------------------------------------------------+ |
| +--------------------------------------------------------+ |
| | kicad_api/ipc_backend.py | |
| | - IPCBackend (connection management) | |
| | - IPCBoardAPI (board operations) | |
| +--------------------------------------------------------+ |
+---------------------------+---------------------------------+
| kicad-python (kipy) library
+---------------------------v---------------------------------+
| Protocol Buffers over UNIX Sockets |
+---------------------------+---------------------------------+
|
+---------------------------v---------------------------------+
| KiCAD 9.0+ (IPC Server) |
+-------------------------------------------------------------+
```
## Known Limitations
1. **KiCAD must be running**: Unlike SWIG, IPC requires KiCAD to be open
2. **Project creation**: Must be done through KiCAD UI or file system
3. **Footprint library access**: Limited - best to use library management separately
4. **Layer management**: Layers are predefined in KiCAD
2. **Project creation**: Not supported via IPC, uses file system
3. **Footprint library access**: Uses hybrid approach (SWIG loads from library, IPC places)
4. **Delete trace**: Falls back to SWIG (IPC API doesn't support direct deletion)
5. **Some operations may not work as expected**: This is experimental code
## Troubleshooting
@@ -213,19 +185,20 @@ python/kicad_api/
├── __init__.py # Package exports
├── base.py # Abstract base classes
├── factory.py # Backend auto-detection
├── ipc_backend.py # IPC implementation (NEW)
├── ipc_backend.py # IPC implementation
└── swig_backend.py # Legacy SWIG wrapper
python/
└── test_ipc_backend.py # IPC test script
```
## Future Enhancements
## Future Work
1. **Footprint library integration via IPC** - Load footprints directly
2. **Schematic IPC support** - When available in kicad-python
3. **Event subscriptions** - React to changes made in KiCAD UI
4. **Multi-board support** - Handle multiple open boards
1. More comprehensive testing of all IPC commands
2. Footprint library integration via IPC (when kipy supports it)
3. Schematic IPC support (when available in kicad-python)
4. Event subscriptions to react to changes made in KiCAD UI
5. Multi-board support
## Related Documentation
@@ -236,5 +209,4 @@ python/
---
**Last Updated:** 2025-11-30
**Maintained by:** KiCAD MCP Team
**Last Updated:** 2025-12-02

193
docs/KNOWN_ISSUES.md
View File

@@ -1,60 +1,17 @@
# Known Issues & Workarounds
**Last Updated:** 2025-10-26
**Version:** 2.0.0-alpha.2
**Last Updated:** 2025-12-02
**Version:** 2.1.0-alpha
This document tracks known issues and provides workarounds where available.
---
## 🐛 Current Issues
## Current Issues
### 1. Component Placement Fails - Library Path Not Found
### 1. `get_board_info` KiCAD 9.0 API Issue
**Status:** 🔴 **BLOCKING** - Cannot place components
**Symptoms:**
```
Error: Could not find footprint library
```
**Root Cause:** MCP server doesn't have access to KiCAD's footprint library paths
**Workaround:** None currently - feature not usable
**Fix Plan:** Week 2 priority
- Detect KiCAD library paths from environment
- Add configuration for custom library paths
- Integrate JLCPCB/Digikey part databases
**Tracking:** High Priority - Required for any real PCB design
---
### 2. Routing Operations Untested with KiCAD 9.0
**Status:** 🟡 **UNKNOWN** - May have API compatibility issues
**Affected Commands:**
- `route_trace`
- `add_via`
- `add_copper_pour`
- `route_differential_pair`
**Symptoms:** May fail with API type mismatch errors (like set_board_size did)
**Workaround:** None - needs testing and fixes
**Fix Plan:** Week 2 priority
- Test each routing command with KiCAD 9.0
- Fix API compatibility issues
- Add comprehensive routing examples
---
### 3. `get_board_info` KiCAD 9.0 API Issue
**Status:** 🟡 **KNOWN** - Non-critical
**Status:** KNOWN - Non-critical
**Symptoms:**
```
@@ -65,26 +22,37 @@ AttributeError: 'BOARD' object has no attribute 'LT_USER'
**Workaround:** Use `get_project_info` instead for basic project details
**Fix Plan:** Week 2
- Update to use KiCAD 9.0 layer constants
- Add backward compatibility for KiCAD 8.x
**Impact:** Low - informational command only
---
### 4. UI Auto-Reload Requires Manual Confirmation
### 2. Zone Filling via SWIG Causes Segfault
**Status:** 🟢 **BY DESIGN** - Will be fixed by IPC
**Status:** KNOWN - Workaround available
**Symptoms:**
- MCP makes changes
- KiCAD detects file change
- User must click "Reload" button to see changes
- Copper pours created but not filled automatically when using SWIG backend
- Calling `ZONE_FILLER` via SWIG causes segfault
**Workaround Options:**
1. Use IPC backend (zones fill correctly via IPC)
2. Open the board in KiCAD UI - zones fill automatically when opened
**Impact:** Medium - affects copper pour visualization until opened in KiCAD
---
### 3. UI Manual Reload Required (SWIG Backend)
**Status:** BY DESIGN - Fixed by IPC
**Symptoms:**
- MCP makes changes via SWIG backend
- KiCAD doesn't show changes until file is reloaded
**Current Workflow:**
```
1. Claude makes change via MCP
1. MCP makes change via SWIG
2. KiCAD shows: "File has been modified. Reload? [Yes] [No]"
3. User clicks "Yes"
4. Changes appear in UI
@@ -92,45 +60,88 @@ AttributeError: 'BOARD' object has no attribute 'LT_USER'
**Why:** SWIG-based backend requires file I/O, can't push changes to running UI
**Fix Plan:** Weeks 2-3 - IPC Backend Migration
- Connect to KiCAD via IPC socket
- Make changes directly in running instance
- No file reload needed - instant visual feedback
**Fix:** Use IPC backend for real-time updates (requires KiCAD to be running with IPC enabled)
**Workaround:** This is the current expected behavior - just click reload!
**Workaround:** Click reload prompt or use File > Revert
---
## 🔧 Recently Fixed
### 4. IPC Backend Experimental
### ✅ KiCAD Process Detection (Fixed 2025-10-26)
**Status:** UNDER DEVELOPMENT
**Description:**
The IPC backend is currently being implemented and tested. Some commands may not work as expected in all scenarios.
**Known IPC Limitations:**
- KiCAD must be running with IPC enabled
- Some commands fall back to SWIG (e.g., delete_trace)
- Footprint loading uses hybrid approach (SWIG for library, IPC for placement)
- Error handling may not be comprehensive in all cases
**Workaround:** If IPC fails, the server automatically falls back to SWIG backend
---
### 5. Schematic Support Limited
**Status:** KNOWN - Partial support
**Description:**
Schematic operations use the kicad-skip library which has some limitations with KiCAD 9.0 file format changes.
**Affected Commands:**
- `create_schematic`
- `add_schematic_component`
- `add_schematic_wire`
**Workaround:** Manual schematic creation may be more reliable for complex designs
---
## Recently Fixed
### Component Library Integration (Fixed 2025-11-01)
**Was:** Could not find footprint libraries
**Now:** Auto-discovers 153 KiCAD footprint libraries, search and list working
### Routing Operations KiCAD 9.0 (Fixed 2025-11-01)
**Was:** Multiple API compatibility issues with KiCAD 9.0
**Now:** All routing commands tested and working:
- `netinfo.FindNet()` -> `netinfo.NetsByName()[name]`
- `zone.SetPriority()` -> `zone.SetAssignedPriority()`
- `ZONE_FILL_MODE_POLYGON` -> `ZONE_FILL_MODE_POLYGONS`
### KiCAD Process Detection (Fixed 2025-10-26)
**Was:** `check_kicad_ui` detected MCP server's own processes
**Now:** Properly filters to only detect actual KiCAD binaries
### ✅ set_board_size KiCAD 9.0 (Fixed 2025-10-26)
### set_board_size KiCAD 9.0 (Fixed 2025-10-26)
**Was:** Failed with `BOX2I_SetSize` type error
**Now:** Works with KiCAD 9.0 API, backward compatible with 8.x
**Now:** Works with KiCAD 9.0 API
### ✅ add_board_text KiCAD 9.0 (Fixed 2025-10-26)
### add_board_text KiCAD 9.0 (Fixed 2025-10-26)
**Was:** Failed with `EDA_ANGLE` type error
**Now:** Works with KiCAD 9.0 API, backward compatible with 8.x
**Now:** Works with KiCAD 9.0 API
### ✅ Missing add_board_text Command (Fixed 2025-10-26)
### Schematic Parameter Mismatch (Fixed 2025-12-02)
**Was:** Command not found error
**Now:** Properly mapped to Python handler
**Was:** `create_schematic` failed due to parameter name differences between TypeScript and Python
**Now:** Accepts multiple parameter naming conventions (`name`, `projectName`, `title`, `filename`)
---
## 📋 Reporting New Issues
## Reporting New Issues
If you encounter an issue not listed here:
1. **Check MCP logs:** `~/.kicad-mcp/logs/kicad_interface.log`
2. **Check KiCAD version:** `pcbnew --version` (must be 9.0+)
2. **Check KiCAD version:** `python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"` (must be 9.0+)
3. **Try the operation in KiCAD directly** - is it a KiCAD issue?
4. **Open GitHub issue** with:
- Error message
@@ -141,18 +152,18 @@ If you encounter an issue not listed here:
---
## 🎯 Priority Matrix
## Priority Matrix
| Issue | Priority | Impact | Effort | Status |
|-------|----------|--------|--------|--------|
| Component Library Integration | 🔴 Critical | High | Medium | Week 2 |
| Routing KiCAD 9.0 Compatibility | 🟡 High | High | Low | Week 2 |
| IPC Backend (Real-time UI) | 🟡 High | Medium | High | Week 2-3 |
| get_board_info Fix | 🟢 Low | Low | Low | Week 2 |
| Issue | Priority | Impact | Status |
|-------|----------|--------|--------|
| IPC Backend Testing | High | Medium | In Progress |
| get_board_info Fix | Low | Low | Known |
| Zone Filling (SWIG) | Medium | Medium | Workaround Available |
| Schematic Support | Medium | Medium | Partial |
---
## 💡 General Workarounds
## General Workarounds
### Server Won't Start
```bash
@@ -169,15 +180,25 @@ python3 python/utils/platform_helper.py
# Always run open_project after server restart
```
### KiCAD UI Doesn't Show Changes
### KiCAD UI Doesn't Show Changes (SWIG Mode)
```
# File → Revert (or click reload prompt)
# File > Revert (or click reload prompt)
# Or: Close and reopen file in KiCAD
# Or: Use IPC backend for automatic updates
```
### IPC Not Connecting
```
# Ensure KiCAD is running
# Enable IPC: Preferences > Plugins > Enable IPC API Server
# Have a board open in PCB editor
# Check socket exists: ls /tmp/kicad/api.sock
```
---
**Need Help?**
- Check [docs/VISUAL_FEEDBACK.md](VISUAL_FEEDBACK.md) for workflow tips
- Check [docs/UI_AUTO_LAUNCH.md](UI_AUTO_LAUNCH.md) for UI setup
- Check [IPC_BACKEND_STATUS.md](IPC_BACKEND_STATUS.md) for IPC details
- Check [REALTIME_WORKFLOW.md](REALTIME_WORKFLOW.md) for workflow tips
- Check logs: `~/.kicad-mcp/logs/kicad_interface.log`
- Open an issue on GitHub

317
docs/STATUS_SUMMARY.md
View File

@@ -1,8 +1,8 @@
# KiCAD MCP - Current Status Summary
**Date:** 2025-11-01
**Date:** 2025-12-02
**Version:** 2.1.0-alpha
**Phase:** Week 2 Nearly Complete - Production Features Ready
**Phase:** IPC Backend Implementation and Testing
---
@@ -11,17 +11,17 @@
| Metric | Value | Status |
|--------|-------|--------|
| Core Features Working | 18/20 | 90% |
| KiCAD 9.0 Compatible | Yes | Yes |
| UI Auto-launch | Working | Yes |
| Component Placement | Working | Yes |
| Component Libraries | 153 libraries | Yes |
| Routing Operations | Working | Yes |
| Real-time Collaboration | Working | Yes |
| KiCAD 9.0 Compatible | Yes | Verified |
| UI Auto-launch | Working | Verified |
| Component Placement | Working | Verified |
| Component Libraries | 153 libraries | Verified |
| Routing Operations | Working | Verified |
| IPC Backend | Under Testing | Experimental |
| Tests Passing | 18/20 | 90% |
---
## What's Working (Verified 2025-11-01)
## What's Working (Verified 2025-12-02)
### Project Management
- `create_project` - Create new KiCAD projects
@@ -38,7 +38,7 @@
- `set_active_layer` - Layer switching
- `get_layer_list` - List all layers
### Component Operations (NEW - WORKING)
### Component Operations
- `place_component` - Place components with library footprints (KiCAD 9.0 fixed)
- `move_component` - Move components
- `rotate_component` - Rotate components (EDA_ANGLE fixed)
@@ -57,7 +57,7 @@
- `GetOrientation()` returns `EDA_ANGLE`, call `.AsDegrees()`
- `GetFootprintName()` now `GetFPIDAsString()`
### Routing Operations (NEW - WORKING)
### Routing Operations
- `add_net` - Create electrical nets
- `route_trace` - Add copper traces (KiCAD 9.0 fixed)
- `add_via` - Add vias between layers (KiCAD 9.0 fixed)
@@ -69,18 +69,10 @@
- `zone.SetPriority()` now `zone.SetAssignedPriority()`
- `ZONE_FILL_MODE_POLYGON` now `ZONE_FILL_MODE_POLYGONS`
- Zone outline requires `outline.NewOutline()` first
- Zone filling disabled (SWIG API segfault) - zones filled when opened in UI
### Real-time Collaboration (NEW - TESTED)
- **MCP to UI Workflow:** AI places components, Human reloads in KiCAD UI, Components visible
- **UI to MCP Workflow:** Human edits in UI, Save, AI reads changes
- Latency: ~1-5 seconds (manual save/reload)
- Full documentation: [REALTIME_WORKFLOW.md](./REALTIME_WORKFLOW.md)
### UI Management
- `check_kicad_ui` - Detect running KiCAD
- `launch_kicad_ui` - Auto-launch with project
- Visual feedback workflow (manual reload)
### Export
- `export_gerber` - Manufacturing files
@@ -96,6 +88,59 @@
---
## IPC Backend (Under Development)
We are currently implementing and testing the KiCAD 9.0 IPC API for real-time UI synchronization. This is experimental and may not work perfectly in all scenarios.
### IPC-Capable Commands (21 total)
The following commands have IPC handlers implemented:
| Command | IPC Handler | Notes |
|---------|-------------|-------|
| `route_trace` | `_ipc_route_trace` | Implemented |
| `add_via` | `_ipc_add_via` | Implemented |
| `add_net` | `_ipc_add_net` | Implemented |
| `delete_trace` | `_ipc_delete_trace` | Falls back to SWIG |
| `get_nets_list` | `_ipc_get_nets_list` | Implemented |
| `add_copper_pour` | `_ipc_add_copper_pour` | Implemented |
| `refill_zones` | `_ipc_refill_zones` | Implemented |
| `add_text` | `_ipc_add_text` | Implemented |
| `add_board_text` | `_ipc_add_text` | Implemented |
| `set_board_size` | `_ipc_set_board_size` | Implemented |
| `get_board_info` | `_ipc_get_board_info` | Implemented |
| `add_board_outline` | `_ipc_add_board_outline` | Implemented |
| `add_mounting_hole` | `_ipc_add_mounting_hole` | Implemented |
| `get_layer_list` | `_ipc_get_layer_list` | Implemented |
| `place_component` | `_ipc_place_component` | Hybrid (SWIG+IPC) |
| `move_component` | `_ipc_move_component` | Implemented |
| `rotate_component` | `_ipc_rotate_component` | Implemented |
| `delete_component` | `_ipc_delete_component` | Implemented |
| `get_component_list` | `_ipc_get_component_list` | Implemented |
| `get_component_properties` | `_ipc_get_component_properties` | Implemented |
| `save_project` | `_ipc_save_project` | Implemented |
### How IPC Works
When KiCAD is running with IPC enabled:
1. Commands check if IPC is connected
2. If connected, use IPC handler for real-time UI updates
3. If not connected, fall back to SWIG API
**To enable IPC:**
1. KiCAD 9.0+ must be running
2. Enable IPC API: `Preferences > Plugins > Enable IPC API Server`
3. Have a board open in the PCB editor
### Known Limitations
- KiCAD must be running for IPC to work
- Some commands may not work as expected (still testing)
- Footprint loading uses hybrid approach (SWIG for library, IPC for placement)
- Delete trace falls back to SWIG (IPC API limitation)
---
## What Needs Work
### Minor Issues (NON-BLOCKING)
@@ -104,67 +149,37 @@
- Error: `AttributeError: 'BOARD' object has no attribute 'LT_USER'`
- Impact: Low (informational command only)
- Workaround: Use `get_project_info` or read components directly
- Fix: Update layer constants for KiCAD 9.0 (30 min task)
**2. Zone filling**
- Copper pours created but not filled automatically
**2. Zone filling via SWIG**
- Copper pours created but not filled automatically via SWIG
- Cause: SWIG API segfault when calling `ZONE_FILLER`
- Workaround: Zones are filled automatically when opened in KiCAD UI
- Fix: Will be resolved with IPC backend (Week 3)
- Workaround: Use IPC backend or zones are filled when opened in KiCAD UI
**3. UI manual reload**
- User must manually reload to see MCP changes
- Impact: Workflow friction (~2 seconds)
- Workaround: File → Revert or close/reopen PCB editor
- Fix: IPC backend will enable automatic refresh (Week 3)
---
## Current Progress
### Week 2 Goals (NEARLY COMPLETE)
**Must Have:**
1. **Component library integration** → 153 libraries auto-discovered, search working
2. **Routing operations** → All operations tested and working with KiCAD 9.0
3. **JLCPCB integration** → Planned and designed, ready to implement
**Should Have:**
4. Fix `get_board_info` API issue (deferred, low priority)
5. Create example project (LED blinker)
6. Real-time collaboration documented
**Bonus Achievements:**
- Real-time collaboration workflow tested end-to-end
- Comprehensive documentation (3 new docs created)
- All KiCAD 9.0 API compatibility issues resolved
### Overall v2.0 Progress
```
Week 1: ████████████████████ 100% Linux support + IPC prep
Week 2: ████████████████░░░░ 80% Libraries + Routing + Real-time
Week 3: ░░░░░░░░░░░░░░░░░░░░ 0% IPC Backend (next)
...
Overall: ████████░░░░░░░░░░░░ 40%
```
**Production Readiness:** 75% - Can design and manufacture PCBs, needs IPC for optimal UX
**3. UI manual reload (SWIG mode)**
- User must manually reload to see MCP changes when using SWIG
- Impact: Workflow friction
- Workaround: Use IPC backend for automatic updates
---
## Architecture Status
### SWIG Backend (Current) **PRODUCTION READY**
- **Status:** Stable and fully functional
### SWIG Backend (File-based)
- **Status:** Stable and functional
- **Pros:** No KiCAD process required, works offline, reliable
- **Cons:** Requires manual file reload for UI updates, no zone filling
- **Future:** Will be maintained alongside IPC as fallback/offline mode
- **Use Case:** Offline work, automated pipelines, batch operations
### IPC Backend (Week 3) **NEXT PRIORITY**
- **Status:** Planned, not yet implemented
- **Pros:** Real-time UI updates (<100ms), no file I/O, zone filling works
- **Cons:** Requires KiCAD running, more complex
- **Future:** Primary backend for interactive use
### IPC Backend (Real-time)
- **Status:** Under active development and testing
- **Pros:** Real-time UI updates, no file I/O for many operations, zone filling works
- **Cons:** Requires KiCAD running, experimental
- **Use Case:** Interactive design sessions, paired programming with AI
### Hybrid Approach
The server automatically selects the best backend:
- IPC when KiCAD is running with IPC enabled
- SWIG fallback when IPC is unavailable
---
@@ -175,40 +190,38 @@ Overall: ████████░░░░░░░░░░░░ 40%
| Project Management | 100% | Create, open, save, info |
| Board Setup | 100% | Size, outline, mounting holes |
| Component Placement | 100% | Place, move, rotate, delete + 153 libraries |
| Routing | 90% | Traces, vias, copper (no auto-fill) |
| Routing | 90% | Traces, vias, copper (zone filling via IPC) |
| Design Rules | 100% | Set, get, run DRC |
| Export | 100% | Gerber, PDF, SVG, 3D, BOM |
| UI Integration | 85% | Launch, check, manual reload |
| Real-time Collab | 85% | MCP↔UI sync (manual save/reload) |
| JLCPCB Integration | 0% | Planned, not implemented |
| IPC Backend | 0% | Planned for Week 3 |
| UI Integration | 85% | Launch, check, IPC auto-updates |
| IPC Backend | 60% | Under testing, 21 commands implemented |
| JLCPCB Integration | 0% | Planned |
---
## Developer Setup Status
### Linux **EXCELLENT**
- KiCAD 9.0 detection:
- Process management:
- venv support:
- Library discovery: (153 libraries)
- Testing:
- Real-time workflow:
### Linux - Primary Platform
- KiCAD 9.0 detection: Working
- Process management: Working
- venv support: Working
- Library discovery: Working (153 libraries)
- Testing: Working
- IPC backend: Under testing
### Windows **SUPPORTED**
### Windows - Supported
- Automated setup script (`setup-windows.ps1`)
- Process detection implemented
- Library paths auto-detected
- Comprehensive error diagnostics
- Startup validation with helpful errors
- Troubleshooting guide (WINDOWS_TROUBLESHOOTING.md)
- Community tested (needs more testing)
### macOS **UNTESTED**
### macOS - Untested
- Configuration provided
- Process detection implemented
- Library paths configured
- Needs testing
- Needs community testing
---
@@ -216,129 +229,59 @@ Overall: ████████░░░░░░░░░░░░ 40%
### Complete
- [x] README.md
- [x] CHANGELOG_2025-10-26.md
- [x] ROADMAP.md
- [x] IPC_BACKEND_STATUS.md
- [x] IPC_API_MIGRATION_PLAN.md
- [x] REALTIME_WORKFLOW.md
- [x] LIBRARY_INTEGRATION.md
- [x] KNOWN_ISSUES.md
- [x] UI_AUTO_LAUNCH.md
- [x] VISUAL_FEEDBACK.md
- [x] CLIENT_CONFIGURATION.md
- [x] BUILD_AND_TEST_SESSION.md
- [x] KNOWN_ISSUES.md
- [x] ROADMAP.md
- [x] STATUS_SUMMARY.md (this document)
- [x] **LIBRARY_INTEGRATION.md** (new 2025-11-01) ✨
- [x] **REALTIME_WORKFLOW.md** (new 2025-11-01) ✨
- [x] **JLCPCB_INTEGRATION_PLAN.md** (new 2025-11-01) ✨
- [x] WINDOWS_SETUP.md
- [x] WINDOWS_TROUBLESHOOTING.md
### Needed
- [ ] EXAMPLE_PROJECTS.md (LED blinker, Arduino shield)
- [ ] VIDEO_TUTORIALS.md (when created)
- [ ] EXAMPLE_PROJECTS.md
- [ ] CONTRIBUTING.md
- [ ] API_REFERENCE.md (comprehensive tool docs)
- [ ] IPC_BACKEND.md (Week 3)
---
## Recent Achievements (2025-11-01)
**Week 2 Major Milestones:**
1. **Component Library Integration**
- Auto-discovered 153 KiCAD footprint libraries
- Full search, list, and find functionality
- Supports both `Library:Footprint` and `Footprint` formats
- Component placement working end-to-end
2. **Routing Operations**
- All routing commands tested with KiCAD 9.0
- Fixed 6 API compatibility issues
- Nets, traces, vias, copper pours all working
- Comprehensive testing completed
3. **Real-time Collaboration**
- Tested MCP→UI workflow (AI places, human sees)
- Tested UI→MCP workflow (human edits, AI reads)
- Both directions confirmed working
- Documentation created with best practices
4. **KiCAD 9.0 Compatibility**
- All API breaking changes identified and fixed
- `EDA_ANGLE`, `NetsByName`, zone APIs updated
- No known API issues remaining
5. **JLCPCB Integration Planning**
- Researched official JLCPCB API
- Designed complete implementation architecture
- Ready to implement (~3-4 days estimated)
---
## Learning Resources
**For Users:**
1. Start with [README.md](../README.md) - Installation and quick start
2. Read [LIBRARY_INTEGRATION.md](LIBRARY_INTEGRATION.md) - Using footprint libraries
3. Read [REALTIME_WORKFLOW.md](REALTIME_WORKFLOW.md) - AI-human collaboration
4. Try example: "Place a 10k resistor at 50, 40mm using 0603 footprint"
5. Check [KNOWN_ISSUES.md](KNOWN_ISSUES.md) if you hit problems
**For Developers:**
1. Read [BUILD_AND_TEST_SESSION.md](BUILD_AND_TEST_SESSION.md) - Build setup
2. Check [ROADMAP.md](ROADMAP.md) - See what's coming next
3. Review [LIBRARY_INTEGRATION.md](LIBRARY_INTEGRATION.md) - Library system internals
4. See [JLCPCB_INTEGRATION_PLAN.md](JLCPCB_INTEGRATION_PLAN.md) - Next feature to build
5. Pick a task and contribute!
- [ ] API_REFERENCE.md
---
## What's Next?
### Immediate (Week 2 Completion)
1. **JLCPCB Parts Integration** (3-4 days)
- Download and cache ~108k parts database
- Parametric search (resistance, package, price)
- Map JLCPCB parts → KiCAD footprints
- Enable cost-optimized component selection
### Immediate Priorities
1. **Complete IPC Testing** - Verify all 21 IPC handlers work correctly
2. **Fix Edge Cases** - Address any issues found during testing
3. **Improve Error Handling** - Better fallback behavior
### Next Phase (Week 3)
2. **IPC Backend Implementation** (1 week)
- Replace file I/O with IPC socket communication
- Enable real-time UI updates (<100ms latency)
- Fix zone filling (no more SWIG segfaults)
- True paired programming experience
### Polish (Week 4+)
3. Example projects and tutorials
4. Windows/macOS testing
5. Performance optimization
6. v2.0 stable release preparation
### Planned Features
- JLCPCB parts integration
- Digikey API integration
- Advanced routing algorithms
- Smart BOM management
- Design pattern library (Arduino shields, RPi HATs)
---
## Call to Action
## Getting Help
**Ready to use it?**
1. Follow [installation guide](../README.md#installation)
2. Try placing components: "Place a 10k 0603 resistor at 50, 40mm"
3. Test real-time collaboration workflow
4. Report any issues you find
**For Users:**
1. Check [README.md](../README.md) for installation
2. Review [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for common problems
3. Check logs: `~/.kicad-mcp/logs/kicad_interface.log`
**Want to contribute?**
1. Check [ROADMAP.md](ROADMAP.md) for priorities
2. JLCPCB integration is ready to implement
3. Help test on Windows/macOS
4. Open a PR!
**For Developers:**
1. Read [BUILD_AND_TEST_SESSION.md](BUILD_AND_TEST_SESSION.md)
2. Check [ROADMAP.md](ROADMAP.md) for priorities
3. Review [IPC_BACKEND_STATUS.md](IPC_BACKEND_STATUS.md) for IPC details
**Need help?**
- Check documentation (now with 11 comprehensive guides!)
- Review logs: `~/.kicad-mcp/logs/kicad_interface.log`
- Open an issue on GitHub
**Issues:**
- Open an issue on GitHub with OS, KiCAD version, and error details
---
**Bottom Line:** Week 2 is 80% complete with major features working! Component placement, routing, and real-time collaboration all functional. JLCPCB integration planned, IPC backend next. On track for production-ready v2.0 release.
**Confidence Level:** Very High - Exceeding expectations
---
*Last Updated: 2025-11-01*
*Last Updated: 2025-12-02*
*Maintained by: KiCAD MCP Team*