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

docs: comprehensive documentation overhaul for v2.2.3

Browse Source 
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>
This commit is contained in:
KiCAD MCP Bot
2026-03-21 01:31:44 -04:00
parent e5179e5fab
commit f047a4e4d1
32 changed files with 3421 additions and 1070 deletions
Download Patch File Download Diff File Expand all files Collapse all files

376
docs/KNOWN_ISSUES.md
View File

@@ -1,203 +1,173 @@
# Known Issues & Workarounds
**Last Updated:** 2025-12-02
**Version:** 2.1.0-alpha
This document tracks known issues and provides workarounds where available.
---
## Current Issues
### 1. `get_board_info` KiCAD 9.0 API Issue
**Status:** KNOWN - Non-critical
**Symptoms:**
```
AttributeError: 'BOARD' object has no attribute 'LT_USER'
```
**Root Cause:** KiCAD 9.0 changed layer enumeration constants
**Workaround:** Use `get_project_info` instead for basic project details
**Impact:** Low - informational command only
---
### 2. Zone Filling via SWIG Causes Segfault
**Status:** KNOWN - Workaround available
**Symptoms:**
- 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. MCP makes change via SWIG
2. KiCAD shows: "File has been modified. Reload? [Yes] [No]"
3. User clicks "Yes"
4. Changes appear in UI
```
**Why:** SWIG-based backend requires file I/O, can't push changes to running UI
**Fix:** Use IPC backend for real-time updates (requires KiCAD to be running with IPC enabled)
**Workaround:** Click reload prompt or use File > Revert
---
### 4. IPC Backend Experimental
**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
---
---
## Recently Fixed
### Schematic Component Corruption (Fixed 2026-02-26)
**Was:** `add_schematic_component` corrupted .kicad_sch files due to sexpdata formatting issues
**Now:** Rewritten to use text manipulation, preserves KiCAD file formatting perfectly
**Impact:** Schematic workflow fully functional with all component types
**Fixed in:** PR #40, commit a69d288
### DRC Violations API KiCAD 9.0 (Fixed 2026-02-26)
**Was:** `get_drc_violations` failed with `AttributeError: 'BOARD' object has no attribute 'GetDRCMarkers'`
**Now:** Reimplemented to use `run_drc()` internally which calls kicad-cli
**Impact:** Maintains backward compatibility while using stable kicad-cli interface
### 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)
**Was:** Failed with `BOX2I_SetSize` type error
**Now:** Works with KiCAD 9.0 API
### add_board_text KiCAD 9.0 (Fixed 2025-10-26)
**Was:** Failed with `EDA_ANGLE` type error
**Now:** Works with KiCAD 9.0 API
### Schematic Parameter Mismatch (Fixed 2025-12-02)
**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
If you encounter an issue not listed here:
1. **Check MCP logs:** `~/.kicad-mcp/logs/kicad_interface.log`
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
- Log excerpt
- Steps to reproduce
- KiCAD version
- OS and version
---
## Priority Matrix
| 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
### Server Won't Start
```bash
# Check Python can import pcbnew
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"
# Check paths
python3 python/utils/platform_helper.py
```
### Commands Fail After Server Restart
```
# Board reference is lost on restart
# Always run open_project after server restart
```
### KiCAD UI Doesn't Show Changes (SWIG Mode)
```
# 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 [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
# Known Issues & Workarounds
**Last Updated:** 2026-03-21
**Version:** 2.2.3
This document tracks known issues and provides workarounds where available.
---
## Current Issues
### 1. `get_board_info` KiCAD 9.0 API Issue
**Status:** KNOWN - Non-critical
**Symptoms:**
```
AttributeError: 'BOARD' object has no attribute 'LT_USER'
```
**Root Cause:** KiCAD 9.0 changed layer enumeration constants
**Workaround:** Use `get_project_info` instead for basic project details
**Impact:** Low - informational command only
---
### 2. Zone Filling via SWIG Causes Segfault
**Status:** KNOWN - Workaround available
**Symptoms:**
- 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
3. Use `refill_zones` tool (may still segfault in some configurations)
**Impact:** Medium - affects copper pour visualization until opened in KiCAD
---
### 3. UI Manual Reload Required (SWIG Backend)
**Status:** BY DESIGN
**Symptoms:**
- MCP makes changes via SWIG backend
- KiCAD does not show changes until file is reloaded
**Why:** SWIG-based backend modifies files directly and cannot push changes to a running UI
**Fix:** Use IPC backend for real-time updates (requires KiCAD running with IPC enabled)
**Workaround:** Click the reload prompt in KiCAD or use File > Revert
---
### 4. IPC Backend Limitations
**Status:** EXPERIMENTAL
**Known Limitations:**
- KiCAD must be running with IPC enabled (Preferences > Plugins > Enable IPC API Server)
- Some commands fall back to SWIG (e.g., delete_trace)
- Footprint loading uses hybrid approach (SWIG for library, IPC for placement)
**Workaround:** The server automatically falls back to SWIG backend when IPC is unavailable
---
### 5. package.json Version Mismatch
**Status:** KNOWN - Non-critical
**Symptoms:** package.json shows version 2.1.0-alpha while CHANGELOG documents version 2.2.3
**Impact:** Cosmetic only. CHANGELOG.md is the authoritative version reference.
---
## Recently Fixed (v2.2.0 - v2.2.3)
### B.Cu Footprint Routing (Fixed v2.2.3)
- `route_pad_to_pad` now correctly detects B.Cu footprints and inserts vias
- KiCAD 9 SWIG `pad.GetLayerName()` always returned F.Cu for flipped footprints -- fixed using `footprint.GetLayer()`
### B.Cu Placement Hang (Fixed v2.2.3)
- Placing footprints on B.Cu no longer causes ~30s freeze
- Fix: call `board.Add()` before `Flip()`
### Board Outline Rounded Corners (Fixed v2.2.3)
- `add_board_outline` now correctly applies cornerRadius for rounded_rectangle shape
### Project-Local Library Resolution (Fixed v2.2.2)
- `add_schematic_component` and `place_component` now search project-local sym-lib-table and fp-lib-table
- Previously only global KiCAD library paths were searched
### Template File Corruption (Fixed v2.2.2)
- Removed invalid `;;` comment lines from template schematics
- Restored KiCAD 9 format version (20250114) in templates
### copy_routing_pattern Empty Results (Fixed v2.2.2)
- Added geometric fallback when pads have no net assignments
### Schematic Component Corruption (Fixed v2.2.1)
- `add_schematic_component` no longer corrupts .kicad_sch files
- Rewritten to use text manipulation instead of sexpdata formatting
### SWIG/UUID Comparison Bugs (Fixed v2.2.0)
- Fixed SwigPyObject UUID comparison
- Fixed SWIG iterator invalidation after board.Remove()
- Added board.SetModified() to prevent dangling pointer crashes
---
## Reporting New Issues
If you encounter an issue not listed here:
1. **Check MCP logs:** `~/.kicad-mcp/logs/kicad_interface.log`
2. **Enable developer mode:** Set `KICAD_MCP_DEV=1` to capture session logs
3. **Check KiCAD version:** `python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"` (must be 9.0+)
4. **Try the operation in KiCAD directly** -- is it a KiCAD issue?
5. **Open a GitHub issue** with:
- Error message and log excerpt
- Steps to reproduce
- KiCAD version and OS
- MCP session log (from `logs/` folder if dev mode is enabled)
---
## General Workarounds
### Server Will Not Start
```bash
# Check Python can import pcbnew
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"
# Check paths
python3 python/utils/platform_helper.py
```
### Commands Fail After Server Restart
```
# Board reference is lost on restart
# Always run open_project after server restart
```
### KiCAD UI Does Not Show Changes (SWIG Mode)
```
# 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 [IPC_BACKEND_STATUS.md](IPC_BACKEND_STATUS.md) for IPC details
- Check logs: `~/.kicad-mcp/logs/kicad_interface.log`
- Open an issue on GitHub