nearxos/kicad-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f047a4e4d1734faa66ee6c62949fdc55c1e1b6d5
kicad-mcp-server/docs/IPC_BACKEND_STATUS.md
KiCAD MCP Bot f047a4e4d1 docs: comprehensive documentation overhaul for v2.2.3 
Major documentation update bringing all docs current with the 122-tool,
16-category state of the project (previously frozen at v2.1.0-alpha/59 tools).

New documentation (9 files):
- FREEROUTING_GUIDE.md - autorouter setup, Docker/Podman, all 4 tools
- SCHEMATIC_TOOLS_REFERENCE.md - all 27 schematic tools with parameters
- ROUTING_TOOLS_REFERENCE.md - all 13 routing tools with examples
- FOOTPRINT_SYMBOL_CREATOR_GUIDE.md - 8 creator tools with examples
- SVG_IMPORT_GUIDE.md - SVG logo import tool
- DATASHEET_TOOLS_GUIDE.md - datasheet enrichment tools
- PCB_DESIGN_WORKFLOW.md - end-to-end design guide
- ARCHITECTURE.md - system architecture for contributors
- INDEX.md - documentation table of contents

Updated documentation (12 files):
- README.md - tool count 64->122, feature list, contributor credits
- TOOL_INVENTORY.md - complete rebuild with all 122 tools
- STATUS_SUMMARY.md - updated to v2.2.3 feature matrix
- ROADMAP.md - marked completed milestones, added v2.3+ vision
- KNOWN_ISSUES.md - removed resolved issues, added v2.2.x fixes
- CLIENT_CONFIGURATION.md - added KICAD_MCP_DEV, FREEROUTING_JAR env vars
- LIBRARY_INTEGRATION.md - added symbol and project-local library support
- ROUTER_ARCHITECTURE.md, ROUTER_QUICK_START.md - updated tool counts
- IPC_BACKEND_STATUS.md - updated dates
- JLCPCB_USAGE_GUIDE.md - added cross-reference note
- CONTRIBUTING.md - added ARCHITECTURE.md reference, updated tool count

Archived 10 completed planning docs to docs/archive/.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-21 01:31:44 -04:00

213 lines
7.2 KiB
Markdown
Raw Blame History

# KiCAD IPC Backend Implementation Status
**Status:** Under Active Development and Testing
**Date:** 2026-03-21
**KiCAD Version:** 9.0+
**kicad-python Version:** 0.5.0+
---
## Overview
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.
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 Differences
| 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 IPC Commands
The following MCP commands have IPC handlers:
| 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 |
### Implemented Backend Features
**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
**Board Operations:**
- Get board reference
- Get/Set board size
- List enabled layers
- Save board
- Add board outline segments
- Add mounting holes
**Component Operations:**
- List all components
- Place component (hybrid: SWIG for library loading, IPC for placement)
- Move component
- Rotate component
- Delete component
- Get component properties
**Routing Operations:**
- Add track
- Add via
- Get all tracks
- Get all vias
- Get all nets
**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
### Prerequisites
1. **KiCAD 9.0+** must be running
2. **IPC API must be enabled**: `Preferences > Plugins > Enable IPC API Server`
3. A board must be open in the PCB editor
### Installation
```bash
pip install kicad-python
```
### Testing
Run the test script to verify IPC functionality:
```bash
# Make sure KiCAD is running with IPC enabled and a board open
./venv/bin/python python/test_ipc_backend.py
```
## Architecture
```
+-------------------------------------------------------------+
| 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**: 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
### "Connection failed"
- Ensure KiCAD is running
- Enable IPC API: `Preferences > Plugins > Enable IPC API Server`
- Check if a board is open
### "kicad-python not found"
```bash
pip install kicad-python
```
### "Version mismatch"
- Update kicad-python: `pip install --upgrade kicad-python`
- Ensure KiCAD 9.0+ is installed
### "No board open"
- Open a board in KiCAD's PCB editor before connecting
## File Structure
```
python/kicad_api/
├── __init__.py # Package exports
├── base.py # Abstract base classes
├── factory.py # Backend auto-detection
├── ipc_backend.py # IPC implementation
└── swig_backend.py # Legacy SWIG wrapper
python/
└── test_ipc_backend.py # IPC test script
```
## Future Work
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
- [ROADMAP.md](./ROADMAP.md) - Project roadmap
- [IPC_API_MIGRATION_PLAN.md](./IPC_API_MIGRATION_PLAN.md) - Migration details
- [REALTIME_WORKFLOW.md](./REALTIME_WORKFLOW.md) - Collaboration workflows
- [kicad-python docs](https://docs.kicad.org/kicad-python-main/) - Official API docs
---
**Last Updated:** 2026-03-21
Reference in New Issue View Git Blame Copy Permalink