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

fix: reconnect IPC backend after KiCad starts (#140)

Browse Source 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
scorp508
2026-05-22 17:41:47 -04:00
committed by GitHub
parent f65eaf2798
commit 6113e0c27a
10 changed files with 927 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/IPC_BACKEND_STATUS.md
View File

@@ -11,7 +11,13 @@
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.
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, and runtime reconnect when KiCAD becomes available after the MCP
server has already started. Tools with IPC implementations recheck IPC
availability at runtime and reconnect if KiCAD is available, which prevents the
MCP from staying in SWIG for the entire session after an initial failure to
connect to IPC.
## Key Differences
@@ -33,6 +39,7 @@ The following MCP commands have IPC handlers:
| `add_via` | `_ipc_add_via` | Implemented |
| `add_net` | `_ipc_add_net` | Implemented |
| `delete_trace` | `_ipc_delete_trace` | Falls back to SWIG |
| `query_traces` | `_ipc_query_traces` | Implemented |
| `get_nets_list` | `_ipc_get_nets_list` | Implemented |
| `add_copper_pour` | `_ipc_add_copper_pour` | Implemented |
| `refill_zones` | `_ipc_refill_zones` | Implemented |
@@ -59,6 +66,7 @@ The following MCP commands have IPC handlers:
- Auto-detect socket path (`/tmp/kicad/api.sock`)
- Version checking and validation
- Auto-fallback to SWIG when IPC unavailable
- Runtime reconnect from SWIG to IPC when KiCAD starts after MCP
- Change notification callbacks
**Board Operations:**
@@ -86,6 +94,7 @@ The following MCP commands have IPC handlers:
- Get all tracks
- Get all vias
- Get all nets
- Query traces from the live board with net, layer, and bounding-box filters
**Zone Operations:**
@@ -119,6 +128,30 @@ The following MCP commands have IPC handlers:
pip install kicad-python
```
### Runtime Backend Selection
At startup, the server attempts IPC first when `KICAD_BACKEND` is `auto` or
`ipc`. If KiCAD is not running yet, `auto` mode falls back to SWIG so file-based
operations can still work.
IPC-capable board tools now retry the IPC connection at runtime. This means the
following workflow can switch from SWIG to IPC without restarting the MCP
server:
1. Start the MCP server before KiCAD is running.
2. Launch KiCAD manually or with `launch_kicad_ui`.
3. Open a board with IPC enabled in KiCAD.
4. Call a normal IPC-capable board tool such as `get_board_info`,
`get_layer_list`, `get_component_list`, `get_nets_list`, or `query_traces`.
When the reconnect succeeds, tool responses include `_backend: "ipc"` and
`_realtime: true`. If IPC is still unavailable or no board API can be opened,
the server continues to use SWIG and reports `_backend: "swig"` for the result.
Use `check_kicad_ui`, `launch_kicad_ui`, or `get_backend_info` to inspect the
current live backend status. These responses include `backend`,
`realtime_sync`, and `ipc_connected`.
### Testing
Run the test script to verify IPC functionality:
@@ -164,7 +197,9 @@ Run the test script to verify IPC functionality:
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
5. **Reconnect still requires IPC prerequisites**: Runtime reconnect only
succeeds when KiCAD is running with IPC enabled and a board is available
6. **Some operations may not work as expected**: This is experimental code
## Troubleshooting
@@ -173,6 +208,8 @@ Run the test script to verify IPC functionality:
- Ensure KiCAD is running
- Enable IPC API: `Preferences > Plugins > Enable IPC API Server`
- Check if a board is open
- If MCP started before KiCAD, call `check_kicad_ui` or retry an IPC-capable
board tool after KiCAD and the board are ready
### "kicad-python not found"

30
docs/UI_AUTO_LAUNCH.md
View File

@@ -71,7 +71,10 @@ Check if KiCAD is currently running.
"command": "/usr/bin/pcbnew /tmp/project.kicad_pcb"
}
],
"message": "KiCAD is running"
"message": "KiCAD is running",
"backend": "ipc",
"realtime_sync": true,
"ipc_connected": true
}
```
@@ -104,10 +107,26 @@ Launch KiCAD UI, optionally with a project file.
"launched": true,
"message": "KiCAD launched successfully",
"project": "/tmp/mcp_demo/New_Project.kicad_pcb",
"processes": [...]
"processes": [...],
"backend": "ipc",
"realtime_sync": true,
"ipc_connected": true
}
```
If IPC is not enabled, no board is open, or the IPC connection is otherwise not
available yet, these status fields report `backend: "swig"`,
`realtime_sync: false`, and `ipc_connected: false`.
### IPC Reconnect After Launch
When the MCP server starts before KiCAD, it may initially fall back to the SWIG
backend. `launch_kicad_ui` and `check_kicad_ui` now refresh the live backend
status after KiCAD is running, and normal IPC-capable board tools retry IPC on
their next call. Agents do not need to switch to special `ipc_*` tools; they can
retry standard tools such as `get_board_info`, `get_layer_list`,
`get_component_list`, `get_nets_list`, or `query_traces`.
---
## 🔄 Workflow Examples
@@ -383,16 +402,15 @@ await callKicadScript("launch_kicad_ui", {
- **Window Management:** Bring KiCAD to front, minimize/maximize
- **Multi-Instance:** Handle multiple KiCAD instances
- **IPC Integration:** Seamless integration with IPC backend
- **Status Notifications:** Push notifications when KiCAD state changes
- **Auto-Close:** Option to close KiCAD after operations complete
### IPC Mode (Coming Weeks 2-3)
### IPC Mode
When IPC backend is fully implemented:
When KiCAD is running with IPC enabled:
```
KiCAD runs in background → MCP connects via IPC → Real-time updates
KiCAD runs in background → MCP connects or reconnects via IPC → Real-time updates
No file reloading needed! Changes appear instantly.
```

112
docs/VISUAL_FEEDBACK.md
View File

@@ -2,15 +2,19 @@
This document explains how to see changes made by the MCP server in the KiCAD UI in real-time or near-real-time.
## Current Status (Week 1 - SWIG Backend)
## Current Status
**Active Backend:** SWIG (legacy pcbnew Python API)
**Real-time Updates:** Not available yet
**IPC Backend:** Skeleton implemented, operations coming in Weeks 2-3
**Active Backend:** Hybrid SWIG/IPC
**Real-time Updates:** Available for IPC-backed commands when KiCAD IPC is connected
**SWIG Fallback:** File-based commands still require KiCAD to reload from disk
**IPC Re-detect:** IPC-enabled tools detect at runtime if IPC is available again and switch from SWIG to IPC.
---
## 🎯 Best Current Workflow (SWIG + Manual Reload)
## 🎯 Best Current Workflow (Hybrid IPC + SWIG)
### Setup
@@ -24,10 +28,11 @@ This document explains how to see changes made by the MCP server in the KiCAD UI
- Example: Add board outline, mounting holes, etc.
- Each operation saves the file automatically
3. **Reload in KiCAD UI**
- **Option A (Automatic):** KiCAD 8.0+ detects file changes and shows a reload prompt
- **Option B (Manual):** File → Revert to reload from disk
- **Keyboard shortcut:** None by default (but you can assign one)
3. **Check whether reload is needed**
- If the MCP response reports `_backend: "ipc"` and `_realtime: true`, the change should appear in KiCAD immediately.
- If the MCP response reports `_backend: "swig"` or `_realtime: false`, reload the board from disk.
- **Option A (Automatic):** KiCAD 8.0+ detects file changes and shows a reload prompt.
- **Option B (Manual):** File → Revert to reload from disk.
### Workflow Example
@@ -57,34 +62,51 @@ This document explains how to see changes made by the MCP server in the KiCAD UI
---
## 🔮 Future: IPC Backend (Weeks 2-3)
## IPC Backend: Real-Time Updates (Experimental)
When fully implemented, the IPC backend will provide **true real-time updates**:
When KiCAD is running with the IPC API enabled, supported MCP board tools can
use the IPC backend for **true real-time UI updates** instead of relying on
file save/reload.
### How It Will Work
### How It Works
```
Claude MCP → IPC Socket → Running KiCAD → Instant UI Update
```text
Agent → MCP → IPC connection → Running KiCAD → Instant UI Update
```
**No file reloading required** - changes appear as you make them!
**No file reloading is required** for commands that successfully use IPC. Tool
responses include `_backend: "ipc"` and `_realtime: true` when the IPC path was
used. If IPC is unavailable, the server falls back to SWIG and the manual reload
workflow still applies. If IPC becomes available during the session,
IPC-capable tools can reconnect and use IPC without restarting the MCP server.
### IPC Setup (When Available)
### IPC Setup
1. **Enable IPC in KiCAD**
- Preferences → Advanced Preferences
- Search for "IPC"
- Enable: "Enable IPC API Server"
- Restart KiCAD
1. Enable IPC in KiCAD:
- Preferences → Plugins → Enable IPC API Server
- Restart KiCAD if required
2. **Install kicad-python** (Already installed ✓)
2. Install `kicad-python`:
```bash
pip install kicad-python
```
3. **Configure MCP Server**
Add to your MCP config:
The default `auto` backend mode is recommended when you want SWIG fallback
plus runtime reconnect. To make the setting explicit, add:
```json
{
"env": {
"KICAD_BACKEND": "auto"
}
}
```
Use strict `ipc` mode only when you want startup to fail if IPC is not
available:
```json
{
@@ -94,20 +116,23 @@ Claude MCP → IPC Socket → Running KiCAD → Instant UI Update
}
```
4. **Start KiCAD first, then use MCP**
- Changes will appear in real-time
- No manual reloading needed
4. Start KiCAD and open a board, or use `launch_kicad_ui`.
The MCP server **can** start before KiCAD. In `auto` backend mode, IPC-capable
board tools retry IPC at runtime after KiCAD is available, so agents can keep
using standard tools such as `get_board_info`, `get_layer_list`,
`get_component_list`, `get_nets_list`, and `query_traces`.
### Current IPC Status
| Feature | Status |
| -------------------- | ----------- |
| Connection to KiCAD | ✅ Working |
| Version checking | ✅ Working |
| Project operations | ⏳ Week 2-3 |
| Board operations | ⏳ Week 2-3 |
| Component operations | ⏳ Week 2-3 |
| Routing operations | ⏳ Week 2-3 |
| Feature | Status |
| ------------------------ | ------------------------------------------------------------- |
| Connection to KiCAD | Working when KiCAD IPC is enabled |
| Board operations | Partially implemented via IPC |
| Component operations | Partially implemented / hybrid |
| Routing operations | Partially implemented via IPC |
| SWIG fallback | Used automatically in `auto` mode when IPC is unavailable |
| Runtime reconnect to IPC | Used automatically in `auto` mode for IPC-capable board tools |
---
@@ -153,7 +178,7 @@ The MCP server auto-saves after each operation, so changes are immediately avail
For complex changes (multiple components, routing, etc.):
1. Make the change
2. Reload in KiCAD
2. Confirm the change in KiCAD; reload only if the response used SWIG
3. Verify it looks correct
4. Proceed with next change
@@ -171,6 +196,15 @@ For complex changes (multiple components, routing, etc.):
**Cause:** MCP operation may have failed
**Solution:** Check the MCP response for success: true
### Changes Still Require Reload
**Cause:** The tool response reported `_backend: "swig"` or `_realtime: false`.
SWIG-backed commands write files directly and still require KiCAD to reload the board from disk.
**Solution:** Ensure KiCAD is running with IPC enabled and a board is open, then
retry the IPC-capable board tool. If IPC reconnect succeeds, the response will
report `_backend: "ipc"` and `_realtime: true`.
### File is Locked
**Cause:** KiCAD has the file open exclusively
@@ -181,13 +215,5 @@ For complex changes (multiple components, routing, etc.):
---
## 📅 Roadmap
**Current (Week 1):** SWIG backend with manual reload
**Week 2-3:** IPC backend implementation
**Week 4+:** Real-time collaboration features
---
**Last Updated:** 2025-10-26
**Version:** 2.0.0-alpha.1

64
docs/WINDOWS_TROUBLESHOOTING.md
View File

@@ -45,10 +45,12 @@ If the automated setup fails, continue with the manual troubleshooting below.
2. **Test pcbnew import manually:**
```powershell
& "C:\Program Files\KiCad\9.0\bin\python.exe" -c "import pcbnew; print(pcbnew.GetBuildVersion())"
& "C:\Program Files\KiCad\10.0\bin\python.exe" -c "import pcbnew; print(pcbnew.GetBuildVersion())"
```
**Expected:** Prints KiCAD version like `9.0.0`
Replace `10.0` with your installed KiCAD version if needed.
**Expected:** Prints KiCAD version like `10.0.0`
**If it fails:**
- KiCAD's Python module isn't installed
@@ -61,7 +63,7 @@ If the automated setup fails, continue with the manual troubleshooting below.
"mcpServers": {
"kicad": {
"env": {
"PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages"
"PYTHONPATH": "C:\\Program Files\\KiCad\\10.0\\lib\\python3\\dist-packages"
}
}
}
@@ -74,25 +76,37 @@ If the automated setup fails, continue with the manual troubleshooting below.
**Symptom:** Log shows "No KiCAD installations found"
The server checks common Windows install locations, including both machine-wide
and per-user KiCAD installs:
- `%LOCALAPPDATA%\Programs\KiCad`
- `C:\Program Files\KiCad`
- `C:\Program Files (x86)\KiCad`
**Solution:**
1. **Check if KiCAD is installed:**
```powershell
Test-Path "C:\Program Files\KiCad\9.0"
Test-Path "C:\Program Files\KiCad\10.0"
Test-Path "$env:LOCALAPPDATA\Programs\KiCad\10.0"
```
Replace `10.0` with your installed KiCAD version if needed.
2. **If KiCAD is installed elsewhere:**
- Find your KiCAD installation directory
- Update PYTHONPATH in config to match your installation
- Example for version 8.0:
- Set `KICAD_PYTHON` to the bundled `python.exe`
- Update `PYTHONPATH` in config to match your installation if needed
- Example for a per-user 10.0 install:
```
"PYTHONPATH": "C:\\Program Files\\KiCad\\8.0\\lib\\python3\\dist-packages"
"KICAD_PYTHON": "C:\\Users\\YourName\\AppData\\Local\\Programs\\KiCad\\10.0\\bin\\python.exe",
"PYTHONPATH": "C:\\Users\\YourName\\AppData\\Local\\Programs\\KiCad\\10.0\\lib\\python3\\dist-packages"
```
3. **If KiCAD is not installed:**
- Download from https://www.kicad.org/download/windows/
- Install version 9.0 or higher
- Install KiCAD 9.0 or higher
- Use default installation path
---
@@ -162,7 +176,7 @@ If the automated setup fails, continue with the manual troubleshooting below.
1. **Install with KiCAD's Python:**
```powershell
& "C:\Program Files\KiCad\9.0\bin\python.exe" -m pip install -r requirements.txt
& "C:\Program Files\KiCad\10.0\bin\python.exe" -m pip install -r requirements.txt
```
2. **If pip is not available:**
@@ -172,10 +186,10 @@ If the automated setup fails, continue with the manual troubleshooting below.
Invoke-WebRequest -Uri https://bootstrap.pypa.io/get-pip.py -OutFile get-pip.py
# Install pip
& "C:\Program Files\KiCad\9.0\bin\python.exe" get-pip.py
& "C:\Program Files\KiCad\10.0\bin\python.exe" get-pip.py
# Then install requirements
& "C:\Program Files\KiCad\9.0\bin\python.exe" -m pip install -r requirements.txt
& "C:\Program Files\KiCad\10.0\bin\python.exe" -m pip install -r requirements.txt
```
---
@@ -232,7 +246,8 @@ If the automated setup fails, continue with the manual troubleshooting below.
**Solution:**
KiCAD MCP requires Python 3.10+. KiCAD 9.0 includes Python 3.11, which is perfect.
KiCAD MCP requires Python 3.10+. KiCAD 10.0 includes a compatible bundled Python,
and KiCAD 9.0+ is supported.
**Always use KiCAD's bundled Python:**
@@ -240,7 +255,7 @@ KiCAD MCP requires Python 3.10+. KiCAD 9.0 includes Python 3.11, which is perfec
{
"mcpServers": {
"kicad": {
"command": "C:\\Program Files\\KiCad\\9.0\\bin\\python.exe",
"command": "C:\\Program Files\\KiCad\\10.0\\bin\\python.exe",
"args": ["C:\\Users\\YourName\\KiCAD-MCP-Server\\python\\kicad_interface.py"]
}
}
@@ -264,7 +279,7 @@ Config location: `%APPDATA%\Claude\claude_desktop_config.json`
"command": "node",
"args": ["C:\\Users\\YourName\\KiCAD-MCP-Server\\dist\\index.js"],
"env": {
"PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages",
"PYTHONPATH": "C:\\Program Files\\KiCad\\10.0\\lib\\python3\\dist-packages",
"NODE_ENV": "production",
"LOG_LEVEL": "info"
}
@@ -284,7 +299,7 @@ Config location: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\setti
"command": "node",
"args": ["C:\\Users\\YourName\\KiCAD-MCP-Server\\dist\\index.js"],
"env": {
"PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages"
"PYTHONPATH": "C:\\Program Files\\KiCad\\10.0\\lib\\python3\\dist-packages"
},
"description": "KiCAD PCB Design Assistant"
}
@@ -300,10 +315,10 @@ If Node.js issues persist, run Python directly:
{
"mcpServers": {
"kicad": {
"command": "C:\\Program Files\\KiCad\\9.0\\bin\\python.exe",
"command": "C:\\Program Files\\KiCad\\10.0\\bin\\python.exe",
"args": ["C:\\Users\\YourName\\KiCAD-MCP-Server\\python\\kicad_interface.py"],
"env": {
"PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages"
"PYTHONPATH": "C:\\Program Files\\KiCad\\10.0\\lib\\python3\\dist-packages"
}
}
}
@@ -317,7 +332,7 @@ If Node.js issues persist, run Python directly:
### Test 1: Verify KiCAD Python
```powershell
& "C:\Program Files\KiCad\9.0\bin\python.exe" -c @"
& "C:\Program Files\KiCad\10.0\bin\python.exe" -c @"
import sys
print(f'Python version: {sys.version}')
import pcbnew
@@ -330,7 +345,7 @@ Expected output:
```
Python version: 3.11.x ...
pcbnew version: 9.0.0
pcbnew version: 10.0.0
SUCCESS!
```
@@ -353,7 +368,7 @@ Test-Path .\dist\index.js # Should output: True
### Test 4: Run Server Manually
```powershell
$env:PYTHONPATH = "C:\Program Files\KiCad\9.0\lib\python3\dist-packages"
$env:PYTHONPATH = "C:\Program Files\KiCad\10.0\lib\python3\dist-packages"
node .\dist\index.js
```
@@ -390,20 +405,20 @@ Add to your MCP config:
### Check Python sys.path
```powershell
& "C:\Program Files\KiCad\9.0\bin\python.exe" -c @"
& "C:\Program Files\KiCad\10.0\bin\python.exe" -c @"
import sys
for path in sys.path:
print(path)
"@
```
Should include: `C:\Program Files\KiCad\9.0\lib\python3\dist-packages`
Should include: `C:\Program Files\KiCad\10.0\lib\python3\dist-packages`
### Test MCP Communication
```powershell
# Start server
$env:PYTHONPATH = "C:\Program Files\KiCad\9.0\lib\python3\dist-packages"
$env:PYTHONPATH = "C:\Program Files\KiCad\10.0\lib\python3\dist-packages"
$process = Start-Process -FilePath "node" -ArgumentList ".\dist\index.js" -NoNewWindow -PassThru
# Wait 3 seconds
@@ -474,7 +489,8 @@ If none of the above solutions work:
When everything works, you should have:
- [ ] KiCAD 9.0+ installed at `C:\Program Files\KiCad\9.0`
- [ ] KiCAD 9.0 or higher installed under a versioned KiCAD directory such as
`C:\Program Files\KiCad\10.0` or `%LOCALAPPDATA%\Programs\KiCad\10.0`
- [ ] Node.js 18+ installed and in PATH
- [ ] Python can import pcbnew successfully
- [ ] `npm run build` completes without errors