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>
This commit is contained in:
KiCAD MCP Bot
@@ -6,6 +6,7 @@ Thank you for your interest in contributing to the KiCAD MCP Server! This guide
|
|||||||
|
|
||||||
- [Development Environment Setup](#development-environment-setup)
|
- [Development Environment Setup](#development-environment-setup)
|
||||||
- [Project Structure](#project-structure)
|
- [Project Structure](#project-structure)
|
||||||
|
- [Architecture Overview](#architecture-overview)
|
||||||
- [Development Workflow](#development-workflow)
|
- [Development Workflow](#development-workflow)
|
||||||
- [Testing](#testing)
|
- [Testing](#testing)
|
||||||
- [Code Style](#code-style)
|
- [Code Style](#code-style)
|
||||||
@@ -144,6 +145,22 @@ kicad-mcp-server/
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
The KiCAD MCP Server is organized into several key components:
|
||||||
|
|
||||||
|
- **TypeScript MCP Server** (`src/`) - Handles MCP protocol communication and tool routing
|
||||||
|
- **Python KiCAD Interface** (`python/`) - Interfaces with KiCAD's Python API (pcbnew)
|
||||||
|
- **Tool Router** - Organizes 122+ tools into 8 discoverable categories
|
||||||
|
- **Resource System** - Provides dynamic project/board state information
|
||||||
|
- **Prompt System** - Offers context-aware design prompts
|
||||||
|
|
||||||
|
**Current Tool Count:** 122+ tools across 8 categories (direct + routed)
|
||||||
|
|
||||||
|
For detailed architecture information, see `docs/ROUTER_ARCHITECTURE.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Development Workflow
|
## Development Workflow
|
||||||
|
|
||||||
### 1. Create a Feature Branch
|
### 1. Create a Feature Branch
|
||||||
|
|||||||
280
README.md
280
README.md
@@ -8,10 +8,14 @@ A Model Context Protocol (MCP) server that enables AI assistants like Claude to
|
|||||||
The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard from Anthropic that allows AI assistants to securely connect to external tools and data sources. This implementation provides a standardized bridge between AI assistants and KiCAD, enabling natural language control of PCB design operations.
|
The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard from Anthropic that allows AI assistants to securely connect to external tools and data sources. This implementation provides a standardized bridge between AI assistants and KiCAD, enabling natural language control of PCB design operations.
|
||||||
|
|
||||||
**Key Capabilities:**
|
**Key Capabilities:**
|
||||||
- 64 fully-documented tools with JSON Schema validation
|
- 122 tools across 16 categories with JSON Schema validation
|
||||||
- Smart tool discovery with router pattern (reduces AI context by 70%)
|
- Smart tool discovery with router pattern (reduces AI context by 70%)
|
||||||
- 8 dynamic resources exposing project state
|
- 8 dynamic resources exposing project state
|
||||||
|
- Complete schematic workflow with 27 tools and dynamic symbol loading (~10,000 symbols)
|
||||||
|
- Freerouting autorouter integration (Java, Docker, or Podman)
|
||||||
|
- Custom footprint and symbol creation tools
|
||||||
- JLCPCB parts integration with 2.5M+ component catalog and local library search
|
- JLCPCB parts integration with 2.5M+ component catalog and local library search
|
||||||
|
- Datasheet enrichment via LCSC
|
||||||
- Full MCP 2025-06-18 protocol compliance
|
- Full MCP 2025-06-18 protocol compliance
|
||||||
- Cross-platform support (Linux, Windows, macOS)
|
- Cross-platform support (Linux, Windows, macOS)
|
||||||
- Real-time KiCAD UI integration via IPC API (experimental)
|
- Real-time KiCAD UI integration via IPC API (experimental)
|
||||||
@@ -62,7 +66,7 @@ the MCP session log into the project's `logs/` folder on every `export_gerber` a
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
> ⚠️ **Privacy warning:** The session log contains your full tool call history
|
> **Privacy warning:** The session log contains your full tool call history
|
||||||
> (including file paths and design details). **Review or delete `logs/` before
|
> (including file paths and design details). **Review or delete `logs/` before
|
||||||
> sharing a project directory publicly.**
|
> sharing a project directory publicly.**
|
||||||
|
|
||||||
@@ -150,7 +154,7 @@ connections = ConnectionManager.get_net_connections(sch, "VCC", sch_path)
|
|||||||
- Net connectivity: 100% accurate (VCC: 2 connections, GND: 4 connections)
|
- Net connectivity: 100% accurate (VCC: 2 connections, GND: 4 connections)
|
||||||
- Netlist generation: Working with accurate pin-level connections
|
- Netlist generation: Working with accurate pin-level connections
|
||||||
|
|
||||||
See [Dynamic Loading Status](docs/DYNAMIC_LOADING_STATUS.md) and [Wiring Implementation Plan](docs/SCHEMATIC_WIRING_PLAN.md) for technical details.
|
See [Schematic Tools Reference](docs/SCHEMATIC_TOOLS_REFERENCE.md) for the complete schematic tool documentation.
|
||||||
|
|
||||||
### IPC Backend (Experimental)
|
### IPC Backend (Experimental)
|
||||||
We are currently implementing and testing the KiCAD 9.0 IPC API for real-time UI synchronization:
|
We are currently implementing and testing the KiCAD 9.0 IPC API for real-time UI synchronization:
|
||||||
@@ -163,15 +167,16 @@ Note: IPC features are under active development and testing. Enable IPC in KiCAD
|
|||||||
|
|
||||||
### Tool Discovery & Router Pattern
|
### Tool Discovery & Router Pattern
|
||||||
We've implemented an intelligent tool router to keep AI context efficient while maintaining full functionality:
|
We've implemented an intelligent tool router to keep AI context efficient while maintaining full functionality:
|
||||||
- **12 direct tools** always visible for high-frequency operations
|
- **18 direct tools** always visible for high-frequency operations
|
||||||
- **47 routed tools** organized into 7 categories (board, component, export, drc, schematic, library, routing)
|
- **65 routed tools** organized into 8 categories (board, component, export, drc, schematic, library, routing, autoroute)
|
||||||
|
- **35 additional tools** always visible (symbol/footprint creators, JLCPCB, datasheet, advanced routing)
|
||||||
- **4 router tools** for discovery and execution:
|
- **4 router tools** for discovery and execution:
|
||||||
- `list_tool_categories` - Browse all available categories
|
- `list_tool_categories` - Browse all available categories
|
||||||
- `get_category_tools` - View tools in a specific category
|
- `get_category_tools` - View tools in a specific category
|
||||||
- `search_tools` - Find tools by keyword
|
- `search_tools` - Find tools by keyword
|
||||||
- `execute_tool` - Run any tool with parameters
|
- `execute_tool` - Run any tool with parameters
|
||||||
|
|
||||||
**Why this matters:** By organizing tools into discoverable categories, Claude can intelligently find and use the right tool for your task without loading all 64 tool schemas into every conversation. This reduces context consumption by up to 70% while maintaining full access to all functionality.
|
**Why this matters:** By organizing tools into discoverable categories, Claude can intelligently find and use the right tool for your task without loading all 122 tool schemas into every conversation. This reduces context consumption while maintaining full access to all functionality.
|
||||||
|
|
||||||
**Usage is seamless:** Just ask naturally - "export gerber files" or "add mounting holes" - and Claude will discover and execute the appropriate tools automatically.
|
**Usage is seamless:** Just ask naturally - "export gerber files" or "add mounting holes" - and Claude will discover and execute the appropriate tools automatically.
|
||||||
|
|
||||||
@@ -225,106 +230,148 @@ Access project state without executing tools:
|
|||||||
|
|
||||||
## Available Tools
|
## Available Tools
|
||||||
|
|
||||||
The server provides 64 tools organized into functional categories. With the new router pattern, tools are automatically discovered as needed - just ask Claude what you want to accomplish!
|
The server provides **122 tools** organized into 16 functional categories. With the router pattern, tools are automatically discovered as needed -- just ask Claude what you want to accomplish.
|
||||||
|
|
||||||
### Project Management (4 tools)
|
For the complete tool reference with access types (direct/routed/additional), see [Tool Inventory](docs/TOOL_INVENTORY.md).
|
||||||
|
|
||||||
|
### Project Management (5 tools)
|
||||||
- `create_project` - Initialize new KiCAD projects
|
- `create_project` - Initialize new KiCAD projects
|
||||||
- `open_project` - Load existing project files
|
- `open_project` - Load existing project files
|
||||||
- `save_project` - Save current project state
|
- `save_project` - Save current project state
|
||||||
- `get_project_info` - Retrieve project metadata
|
- `get_project_info` - Retrieve project metadata
|
||||||
|
- `snapshot_project` - Save named checkpoint snapshot
|
||||||
|
|
||||||
### Board Operations (9 tools)
|
### Board Operations (12 tools)
|
||||||
- `set_board_size` - Configure PCB dimensions
|
- `set_board_size` - Configure PCB dimensions
|
||||||
- `add_board_outline` - Create board edge (rectangle, circle, polygon)
|
- `add_board_outline` - Create board edge (rectangle, circle, polygon, rounded rectangle)
|
||||||
- `add_layer` - Add custom layers to stack
|
- `add_layer` - Add custom layers to stack
|
||||||
- `set_active_layer` - Switch working layer
|
- `set_active_layer` - Switch working layer
|
||||||
- `get_layer_list` - List all board layers
|
- `get_layer_list` - List all board layers
|
||||||
- `get_board_info` - Retrieve board properties
|
- `get_board_info` - Retrieve board properties
|
||||||
- `get_board_2d_view` - Generate board preview image
|
- `get_board_2d_view` - Generate board preview image
|
||||||
|
- `get_board_extents` - Get board bounding box
|
||||||
- `add_mounting_hole` - Place mounting holes
|
- `add_mounting_hole` - Place mounting holes
|
||||||
- `add_board_text` - Add text annotations
|
- `add_board_text` - Add text annotations
|
||||||
|
- `add_zone` - Add copper zone/pour with clearance settings
|
||||||
|
- `import_svg_logo` - Import SVG file as PCB silkscreen polygons
|
||||||
|
|
||||||
### Component Placement (10 tools)
|
### Component Management (16 tools)
|
||||||
- `place_component` - Place single component with footprint
|
- `place_component` - Place single component with footprint
|
||||||
- `move_component` - Reposition existing component
|
- `move_component` - Reposition existing component
|
||||||
- `rotate_component` - Rotate component by angle
|
- `rotate_component` - Rotate component by angle
|
||||||
- `delete_component` - Remove component from board
|
- `delete_component` - Remove component from board
|
||||||
- `edit_component` - Modify component properties
|
- `edit_component` - Modify component properties
|
||||||
|
- `find_component` - Search by reference or value
|
||||||
- `get_component_properties` - Query component details
|
- `get_component_properties` - Query component details
|
||||||
|
- `add_component_annotation` - Add annotation/comment
|
||||||
|
- `group_components` - Group multiple components
|
||||||
|
- `replace_component` - Replace with different footprint
|
||||||
|
- `get_component_pads` - Get all pad information
|
||||||
- `get_component_list` - List all placed components
|
- `get_component_list` - List all placed components
|
||||||
|
- `get_pad_position` - Get precise pad position
|
||||||
- `place_component_array` - Create component grids/patterns
|
- `place_component_array` - Create component grids/patterns
|
||||||
- `align_components` - Align multiple components
|
- `align_components` - Align multiple components
|
||||||
- `duplicate_component` - Copy existing component
|
- `duplicate_component` - Copy existing component
|
||||||
|
|
||||||
### Routing & Nets (8 tools)
|
### Routing (13 tools)
|
||||||
- `add_net` - Create electrical net
|
- `add_net` - Create electrical net
|
||||||
- `route_trace` - Route copper traces
|
- `route_trace` - Route copper traces between XY points
|
||||||
|
- `route_pad_to_pad` - Route between pads with auto-via insertion
|
||||||
- `add_via` - Place vias for layer transitions
|
- `add_via` - Place vias for layer transitions
|
||||||
- `delete_trace` - Remove traces
|
- `delete_trace` - Remove traces (by UUID, position, or net)
|
||||||
- `get_nets_list` - List all nets
|
- `query_traces` - Query/filter traces
|
||||||
|
- `get_nets_list` - List all nets with statistics
|
||||||
|
- `modify_trace` - Change trace width, layer, or net
|
||||||
- `create_netclass` - Define net class with rules
|
- `create_netclass` - Define net class with rules
|
||||||
- `add_copper_pour` - Create copper zones/pours
|
- `add_copper_pour` - Create copper zones/pours
|
||||||
- `route_differential_pair` - Route differential signals
|
- `route_differential_pair` - Route differential signals
|
||||||
|
- `refill_zones` - Refill all copper zones
|
||||||
|
- `copy_routing_pattern` - Replicate routing between component groups
|
||||||
|
|
||||||
### Library Management (4 tools)
|
### Schematic (27 tools)
|
||||||
- `list_libraries` - List available footprint libraries
|
Complete schematic workflow with dynamic symbol loading (~10,000 symbols) and intelligent wiring.
|
||||||
- `search_footprints` - Search for footprints
|
|
||||||
- `list_library_footprints` - List footprints in library
|
**Component Operations:**
|
||||||
- `get_footprint_info` - Get footprint details
|
- `add_schematic_component` - Place symbols from any KiCad library
|
||||||
|
- `delete_schematic_component` - Remove component
|
||||||
|
- `edit_schematic_component` - Edit properties and fields
|
||||||
|
- `get_schematic_component` - Get component info with field positions
|
||||||
|
- `list_schematic_components` - List all components
|
||||||
|
- `move_schematic_component` - Reposition component
|
||||||
|
- `rotate_schematic_component` - Rotate component
|
||||||
|
- `annotate_schematic` - Auto-assign reference designators
|
||||||
|
|
||||||
|
**Wiring and Connections:**
|
||||||
|
- `add_wire` - Create wire between points
|
||||||
|
- `delete_schematic_wire` - Remove wire segment
|
||||||
|
- `add_schematic_connection` - Auto-connect pins with routing
|
||||||
|
- `add_schematic_net_label` - Add net labels (VCC, GND, signals)
|
||||||
|
- `delete_schematic_net_label` - Remove net label
|
||||||
|
- `connect_to_net` - Connect pin to named net
|
||||||
|
- `connect_passthrough` - Wire all matching pins between connectors (FFC/ribbon)
|
||||||
|
- `get_schematic_pin_locations` - Get pin locations for component
|
||||||
|
|
||||||
|
**Analysis and Export:**
|
||||||
|
- `get_net_connections` - Trace net connectivity
|
||||||
|
- `list_schematic_nets` / `list_schematic_wires` / `list_schematic_labels`
|
||||||
|
- `create_schematic` - Create new schematic file
|
||||||
|
- `get_schematic_view` - Rasterized schematic preview
|
||||||
|
- `export_schematic_svg` / `export_schematic_pdf`
|
||||||
|
- `run_erc` - Electrical rule check
|
||||||
|
- `generate_netlist` - Generate netlist from schematic
|
||||||
|
- `sync_schematic_to_board` - Import nets/pads to PCB (F8 equivalent)
|
||||||
|
|
||||||
|
See [Schematic Tools Reference](docs/SCHEMATIC_TOOLS_REFERENCE.md) for details and examples.
|
||||||
|
|
||||||
|
### Design Rules / DRC (8 tools)
|
||||||
|
- `set_design_rules` / `get_design_rules` - Configure and inspect rules
|
||||||
|
- `run_drc` - Execute design rule check
|
||||||
|
- `get_drc_violations` - Get violation list by severity
|
||||||
|
- `add_net_class` / `assign_net_to_class` - Net class management
|
||||||
|
- `set_layer_constraints` / `check_clearance` - Layer and clearance rules
|
||||||
|
|
||||||
|
### Export (8 tools)
|
||||||
|
- `export_gerber` - Gerber fabrication files
|
||||||
|
- `export_pdf` / `export_svg` - Documentation and vector graphics
|
||||||
|
- `export_3d` - 3D models (STEP, STL, VRML, OBJ)
|
||||||
|
- `export_bom` - Bill of materials (CSV, XML, HTML, JSON)
|
||||||
|
- `export_netlist` - Netlist (KiCad, Spice, Cadstar, OrcadPCB2)
|
||||||
|
- `export_position_file` - Component positions for pick and place
|
||||||
|
- `export_vrml` - VRML 3D model
|
||||||
|
|
||||||
|
### Footprint Libraries (4 tools) and Symbol Libraries (4 tools)
|
||||||
|
- `list_libraries` / `list_symbol_libraries` - Browse available libraries
|
||||||
|
- `search_footprints` / `search_symbols` - Search across all libraries
|
||||||
|
- `list_library_footprints` / `list_library_symbols` - Browse specific library
|
||||||
|
- `get_footprint_info` / `get_symbol_info` - Detailed information
|
||||||
|
|
||||||
|
### Footprint Creator (4 tools) and Symbol Creator (4 tools)
|
||||||
|
Create custom components when existing libraries do not have what you need.
|
||||||
|
- `create_footprint` / `create_symbol` - Build from scratch with pads/pins
|
||||||
|
- `edit_footprint_pad` - Modify pad properties
|
||||||
|
- `register_footprint_library` / `register_symbol_library` - Register in lib-table
|
||||||
|
- `list_footprint_libraries` / `list_symbols_in_library` - Browse custom libraries
|
||||||
|
- `delete_symbol` - Remove symbol from library
|
||||||
|
|
||||||
|
See [Footprint and Symbol Creator Guide](docs/FOOTPRINT_SYMBOL_CREATOR_GUIDE.md) for details.
|
||||||
|
|
||||||
|
### Datasheet Tools (2 tools)
|
||||||
|
- `enrich_datasheets` - Auto-populate datasheet URLs using LCSC part numbers
|
||||||
|
- `get_datasheet_url` - Get LCSC datasheet URL for a component
|
||||||
|
|
||||||
### JLCPCB Integration (5 tools)
|
### JLCPCB Integration (5 tools)
|
||||||
- `download_jlcpcb_database` - Download complete JLCPCB parts catalog (one-time setup)
|
- `download_jlcpcb_database` - Download 2.5M+ parts catalog (one-time setup)
|
||||||
- `search_jlcpcb_parts` - Search 2.5M+ parts with parametric filters
|
- `search_jlcpcb_parts` - Search with parametric filters
|
||||||
- `get_jlcpcb_part` - Get detailed part info with pricing and footprints
|
- `get_jlcpcb_part` - Detailed part info with pricing
|
||||||
- `get_jlcpcb_database_stats` - View database statistics and coverage
|
- `get_jlcpcb_database_stats` - Database statistics
|
||||||
- `suggest_jlcpcb_alternatives` - Find cheaper or more available alternatives
|
- `suggest_jlcpcb_alternatives` - Find cheaper or in-stock alternatives
|
||||||
|
|
||||||
### Design Rules (4 tools)
|
### Freerouting Autorouter (4 tools)
|
||||||
- `set_design_rules` - Configure DRC parameters
|
- `autoroute` - Run Freerouting autorouter (DSN export, route, SES import)
|
||||||
- `get_design_rules` - Retrieve current rules
|
- `export_dsn` / `import_ses` - Manual Specctra DSN/SES workflow
|
||||||
- `run_drc` - Execute design rule check
|
- `check_freerouting` - Verify Java and Freerouting availability
|
||||||
- `get_drc_violations` - Get DRC error report
|
|
||||||
|
|
||||||
### Export (5 tools)
|
See [Freerouting Guide](docs/FREEROUTING_GUIDE.md) for setup and usage.
|
||||||
- `export_gerber` - Generate Gerber fabrication files
|
|
||||||
- `export_pdf` - Export PDF documentation
|
|
||||||
- `export_svg` - Create SVG vector graphics
|
|
||||||
- `export_3d` - Generate 3D models (STEP/VRML)
|
|
||||||
- `export_bom` - Produce bill of materials
|
|
||||||
|
|
||||||
### Schematic Design (9 tools)
|
|
||||||
**Now fully functional with DYNAMIC SYMBOL LOADING + INTELLIGENT WIRING!** (Fixed in v2.1.0 - see Issue #26)
|
|
||||||
|
|
||||||
**Component Placement:**
|
|
||||||
- `create_schematic` - Initialize new schematic from template
|
|
||||||
- `load_schematic` - Open existing schematic
|
|
||||||
- `add_schematic_component` - Place symbols with automatic dynamic loading from KiCad libraries
|
|
||||||
- `list_schematic_libraries` - List symbol libraries
|
|
||||||
- `export_schematic_pdf` - Export schematic PDF
|
|
||||||
|
|
||||||
**Wiring & Connections:** NEW in v2.1.0
|
|
||||||
- `add_schematic_wire` - Create wires between points with customizable stroke
|
|
||||||
- `add_schematic_connection` - Auto-connect pins with intelligent routing (direct, orthogonal)
|
|
||||||
- `add_schematic_net_label` - Add net labels (VCC, GND, signals) with orientation control
|
|
||||||
- `connect_to_net` - Connect component pins to named nets
|
|
||||||
|
|
||||||
**Major Enhancements:**
|
|
||||||
|
|
||||||
1. **Dynamic Symbol Loading** - Access to **ALL ~10,000 KiCad symbols**! Specify any `library` and `type` (e.g., `"library": "MCU_ST_STM32F1", "type": "STM32F103C8Tx"`) and the system automatically:
|
|
||||||
- Searches KiCad symbol libraries
|
|
||||||
- Injects symbol definition into your schematic
|
|
||||||
- Creates cloneable template instance
|
|
||||||
- Places component seamlessly
|
|
||||||
- Fallback to 13 static templates (R, C, L, LED, etc.) when needed
|
|
||||||
|
|
||||||
2. **Intelligent Wiring System** - Professional schematic wiring with automation:
|
|
||||||
- **Automatic pin discovery** - rotation-aware (0°, 90°, 180°, 270°)
|
|
||||||
- **Smart routing** - direct lines or orthogonal (right-angle) paths
|
|
||||||
- **Power symbol support** - VCC, GND, +3V3, +5V, etc.
|
|
||||||
- **Wire graph analysis** - geometric tracing for accurate net connectivity
|
|
||||||
- **Net label management** - local, global, and hierarchical labels
|
|
||||||
- **Netlist generation** - accurate component/pin connection tracking
|
|
||||||
- **S-expression precision** - guaranteed KiCad format compliance
|
|
||||||
|
|
||||||
### UI Management (2 tools)
|
### UI Management (2 tools)
|
||||||
- `check_kicad_ui` - Check if KiCAD is running
|
- `check_kicad_ui` - Check if KiCAD is running
|
||||||
@@ -705,8 +752,8 @@ How many Basic parts are available?
|
|||||||
### MCP Protocol Layer
|
### MCP Protocol Layer
|
||||||
- **JSON-RPC 2.0 Transport:** Bi-directional communication via STDIO
|
- **JSON-RPC 2.0 Transport:** Bi-directional communication via STDIO
|
||||||
- **Protocol Version:** MCP 2025-06-18
|
- **Protocol Version:** MCP 2025-06-18
|
||||||
- **Capabilities:** Tools (59), Resources (8)
|
- **Capabilities:** Tools (122), Resources (8)
|
||||||
- **Tool Router:** Intelligent discovery system with 7 categories
|
- **Tool Router:** Intelligent discovery system with 8 categories
|
||||||
- **Error Handling:** Standard JSON-RPC error codes
|
- **Error Handling:** Standard JSON-RPC error codes
|
||||||
|
|
||||||
### TypeScript Server (`src/`)
|
### TypeScript Server (`src/`)
|
||||||
@@ -842,62 +889,46 @@ npm run format
|
|||||||
|
|
||||||
## Project Status
|
## Project Status
|
||||||
|
|
||||||
**Current Version:** 2.1.0-alpha
|
**Current Version:** 2.2.3
|
||||||
|
|
||||||
**Working Features:**
|
See [STATUS_SUMMARY.md](docs/STATUS_SUMMARY.md) for the complete status matrix and [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
|
||||||
- Project creation and management (PCB + Schematic)
|
|
||||||
- Board outline and sizing
|
|
||||||
- Layer management
|
|
||||||
- Component placement with footprint library loading
|
|
||||||
- Mounting holes and text annotations
|
|
||||||
- Design rule checking
|
|
||||||
- Export to Gerber, PDF, SVG, 3D
|
|
||||||
- **Schematic creation and editing (Issue #26 RESOLVED - fully functional!)**
|
|
||||||
- **DYNAMIC SYMBOL LOADING - Access to ALL ~10,000 KiCad symbols! 🚀**
|
|
||||||
- Template-based schematic workflow with automatic dynamic injection
|
|
||||||
- Symbol cloning from static templates (13 types) and dynamic libraries
|
|
||||||
- UI auto-launch
|
|
||||||
- Full MCP protocol compliance
|
|
||||||
- JLCPCB parts integration (local libraries + JLCSearch API)
|
|
||||||
- Cost optimization and component selection with 2.5M+ parts catalog
|
|
||||||
|
|
||||||
**Under Active Development (IPC Backend):**
|
**Working Features (122 tools):**
|
||||||
|
- Project management with snapshot checkpointing
|
||||||
|
- Complete board design (outline, layers, zones, mounting holes, text, SVG logos)
|
||||||
|
- Component placement with arrays, alignment, and duplication
|
||||||
|
- Advanced routing (pad-to-pad with auto-via, differential pairs, pattern copying)
|
||||||
|
- Complete schematic workflow with dynamic symbol loading (~10,000 symbols)
|
||||||
|
- Intelligent wiring system with pin discovery and smart routing
|
||||||
|
- FFC/ribbon cable passthrough workflow
|
||||||
|
- Schematic-to-board synchronization
|
||||||
|
- Design rule checking (DRC and ERC)
|
||||||
|
- Export to Gerber, PDF, SVG, 3D, BOM, netlist, position file
|
||||||
|
- Custom footprint and symbol creation
|
||||||
|
- JLCPCB parts integration (2.5M+ parts catalog)
|
||||||
|
- Datasheet enrichment via LCSC
|
||||||
|
- Freerouting autorouter integration (Java, Docker, Podman)
|
||||||
|
- UI auto-launch and management
|
||||||
|
- Full MCP 2025-06-18 protocol compliance
|
||||||
|
|
||||||
|
**IPC Backend (Experimental):**
|
||||||
- Real-time UI synchronization via KiCAD 9.0 IPC API
|
- Real-time UI synchronization via KiCAD 9.0 IPC API
|
||||||
- IPC-enabled commands: route_trace, add_via, place_component, move_component, delete_component, add_copper_pour, refill_zones, add_board_outline, add_mounting_hole, and more
|
- 21 IPC-enabled commands with automatic SWIG fallback
|
||||||
- Hybrid footprint loading (SWIG for library access, IPC for placement)
|
- Hybrid footprint loading (SWIG for library access, IPC for placement)
|
||||||
- Zone/copper pour support via IPC
|
|
||||||
|
|
||||||
Note: IPC features are experimental and under testing. Some commands may not work as expected in all scenarios.
|
**Developer Mode:**
|
||||||
|
Set `KICAD_MCP_DEV=1` to capture MCP session logs for debugging. See CHANGELOG v2.2.3 for details.
|
||||||
|
|
||||||
**Planned:**
|
See [ROADMAP.md](docs/ROADMAP.md) for planned features.
|
||||||
- Digikey API integration
|
|
||||||
- Mouser API integration
|
|
||||||
- Advanced routing algorithms
|
|
||||||
- Smart BOM management with real-time pricing
|
|
||||||
- AI-assisted component selection and optimization
|
|
||||||
- Design pattern library (Arduino shields, RPi HATs)
|
|
||||||
- Panelization support
|
|
||||||
|
|
||||||
See [ROADMAP.md](docs/ROADMAP.md) for detailed development timeline.
|
|
||||||
|
|
||||||
## What Do You Want to See Next?
|
## What Do You Want to See Next?
|
||||||
|
|
||||||
We're actively developing new features and tools for the KiCAD MCP Server. **Your input matters!**
|
We are actively developing new features. Your feedback directly shapes development priorities.
|
||||||
|
|
||||||
**We'd love to hear from you:**
|
|
||||||
- What PCB design workflows could be automated?
|
|
||||||
- Which component suppliers should we integrate next (Digikey, Mouser, Arrow, etc.)?
|
|
||||||
- What export formats or manufacturing outputs do you need?
|
|
||||||
- Are there specific routing algorithms or design patterns you want?
|
|
||||||
- What pain points in your KiCAD workflow could AI help solve?
|
|
||||||
- How can we improve the JLCPCB integration?
|
|
||||||
|
|
||||||
**Share your ideas:**
|
**Share your ideas:**
|
||||||
1. 💡 [Open a feature request](https://github.com/mixelpixx/KiCAD-MCP-Server/issues/new?labels=enhancement&template=feature_request.md)
|
1. [Open a feature request](https://github.com/mixelpixx/KiCAD-MCP-Server/issues/new?labels=enhancement&template=feature_request.md)
|
||||||
2. 💬 [Join the discussion](https://github.com/mixelpixx/KiCAD-MCP-Server/discussions)
|
2. [Join the discussion](https://github.com/mixelpixx/KiCAD-MCP-Server/discussions)
|
||||||
3. ⭐ Star the repo if you find it useful!
|
3. Star the repo if you find it useful
|
||||||
|
|
||||||
Your feedback directly shapes our development priorities. Whether it's a small quality-of-life improvement or a major new capability, we want to hear about it.
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
@@ -924,10 +955,21 @@ This project is licensed under the MIT License. See [LICENSE](LICENSE) for detai
|
|||||||
- Built on the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
|
- Built on the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
|
||||||
- Powered by [KiCAD](https://www.kicad.org/) open-source PCB design software
|
- Powered by [KiCAD](https://www.kicad.org/) open-source PCB design software
|
||||||
- Uses [kicad-skip](https://github.com/kicad-skip) for schematic manipulation
|
- Uses [kicad-skip](https://github.com/kicad-skip) for schematic manipulation
|
||||||
- JLCPCB local library search contributed by [@l3wi](https://github.com/l3wi) - [PR #25](https://github.com/mixelpixx/KiCAD-MCP-Server/pull/25)
|
|
||||||
- [JLCSearch API](https://jlcsearch.tscircuit.com/) by [@tscircuit](https://github.com/tscircuit/jlcsearch) - Public JLCPCB parts API
|
- [JLCSearch API](https://jlcsearch.tscircuit.com/) by [@tscircuit](https://github.com/tscircuit/jlcsearch) - Public JLCPCB parts API
|
||||||
- [JLCParts Database](https://github.com/yaqwsx/jlcparts) by [@yaqwsx](https://github.com/yaqwsx) - JLCPCB parts data
|
- [JLCParts Database](https://github.com/yaqwsx/jlcparts) by [@yaqwsx](https://github.com/yaqwsx) - JLCPCB parts data
|
||||||
|
|
||||||
|
### Community Contributors
|
||||||
|
|
||||||
|
- [@Kletternaut](https://github.com/Kletternaut) - Routing/component tools, footprint/symbol creators, passthrough workflow, template fixes (PRs #44, #48, #49, #51, #53, #57, #59)
|
||||||
|
- [@Mehanik](https://github.com/Mehanik) - Schematic inspection/editing tools, component field positions (PRs #60, #66, #67)
|
||||||
|
- [@jflaflamme](https://github.com/jflaflamme) - Freerouting autorouter integration with Docker/Podman support (PR #68)
|
||||||
|
- [@l3wi](https://github.com/l3wi) - Local symbol library search, JLCPCB third-party library support (PR #25)
|
||||||
|
- [@gwall-ceres](https://github.com/gwall-ceres) - MCP protocol compliance, Windows compatibility (PR #10)
|
||||||
|
- [@fariouche](https://github.com/fariouche) - Bug fixes (PR #17)
|
||||||
|
- [@shuofengzhang](https://github.com/shuofengzhang) - XDG relative path handling (PR #58)
|
||||||
|
- [@sid115](https://github.com/sid115) - Windows setup script improvements (PR #13)
|
||||||
|
- [@pasrom](https://github.com/pasrom) - MCP server bug fixes (PR #50)
|
||||||
|
|
||||||
## Citation
|
## Citation
|
||||||
|
|
||||||
If you use this project in your research or publication, please cite:
|
If you use this project in your research or publication, please cite:
|
||||||
@@ -938,7 +980,7 @@ If you use this project in your research or publication, please cite:
|
|||||||
author = {mixelpixx},
|
author = {mixelpixx},
|
||||||
year = {2025},
|
year = {2025},
|
||||||
url = {https://github.com/mixelpixx/KiCAD-MCP-Server},
|
url = {https://github.com/mixelpixx/KiCAD-MCP-Server},
|
||||||
version = {2.1.0-alpha}
|
version = {2.2.3}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
314
docs/ARCHITECTURE.md
Normal file
314
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,314 @@
|
|||||||
|
# KiCAD MCP Server Architecture
|
||||||
|
|
||||||
|
This document describes the system architecture for contributors who want to understand, modify, or extend the server.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## System Overview
|
||||||
|
|
||||||
|
```
|
||||||
|
AI Assistant (Claude, etc.)
|
||||||
|
|
|
||||||
|
| MCP Protocol (JSON-RPC 2.0 over STDIO)
|
||||||
|
v
|
||||||
|
TypeScript MCP Server (src/)
|
||||||
|
|
|
||||||
|
| Spawn Python subprocess, pass JSON commands
|
||||||
|
v
|
||||||
|
Python KiCAD Interface (python/)
|
||||||
|
|
|
||||||
|
| pcbnew SWIG API or KiCAD IPC API
|
||||||
|
v
|
||||||
|
KiCAD 9.0+
|
||||||
|
```
|
||||||
|
|
||||||
|
The server has two layers:
|
||||||
|
|
||||||
|
1. **TypeScript layer** -- implements the MCP protocol, registers tools with schemas, validates input, manages the Python subprocess
|
||||||
|
2. **Python layer** -- interfaces with KiCAD's pcbnew API (SWIG bindings) or IPC API for actual PCB/schematic operations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
KiCAD-MCP-Server/
|
||||||
|
src/ # TypeScript MCP server
|
||||||
|
server.ts # Main server, tool registration, Python subprocess
|
||||||
|
logger.ts # Logging configuration
|
||||||
|
tools/ # Tool definitions (one file per category)
|
||||||
|
registry.ts # Tool category definitions and lookup
|
||||||
|
router.ts # Router tools (list/search/execute)
|
||||||
|
project.ts # Project management tools
|
||||||
|
board.ts # Board operations tools
|
||||||
|
component.ts # Component tools
|
||||||
|
routing.ts # Routing tools
|
||||||
|
design-rules.ts # DRC tools
|
||||||
|
export.ts # Export tools
|
||||||
|
schematic.ts # Schematic tools
|
||||||
|
library.ts # Footprint library tools
|
||||||
|
library-symbol.ts # Symbol library tools
|
||||||
|
footprint.ts # Footprint creator tools
|
||||||
|
symbol-creator.ts # Symbol creator tools
|
||||||
|
datasheet.ts # Datasheet tools
|
||||||
|
jlcpcb-api.ts # JLCPCB integration tools
|
||||||
|
freerouting.ts # Autorouter tools
|
||||||
|
ui.ts # UI management tools
|
||||||
|
resources/ # MCP resource definitions
|
||||||
|
prompts/ # MCP prompt templates
|
||||||
|
utils/ # Utility functions
|
||||||
|
|
||||||
|
python/ # Python KiCAD interface
|
||||||
|
kicad_interface.py # Main entry point, command router
|
||||||
|
commands/ # Command implementations
|
||||||
|
project.py # Project operations
|
||||||
|
board.py # Board manipulation
|
||||||
|
component.py # PCB component operations
|
||||||
|
component_schematic.py # Schematic component operations
|
||||||
|
connection_schematic.py # Schematic wiring and connections
|
||||||
|
schematic.py # Schematic file management
|
||||||
|
routing.py # Trace routing
|
||||||
|
design_rules.py # DRC operations
|
||||||
|
export.py # File export
|
||||||
|
library.py # Footprint library access
|
||||||
|
library_symbol.py # Symbol library access
|
||||||
|
footprint.py # Custom footprint creation
|
||||||
|
symbol_creator.py # Custom symbol creation
|
||||||
|
datasheet_manager.py # Datasheet enrichment
|
||||||
|
jlcpcb.py # JLCPCB API client
|
||||||
|
jlcsearch.py # JLCSearch public API client
|
||||||
|
jlcpcb_parts.py # JLCPCB parts database
|
||||||
|
freerouting.py # Freerouting autorouter
|
||||||
|
svg_import.py # SVG to PCB polygon conversion
|
||||||
|
dynamic_symbol_loader.py # Dynamic symbol injection
|
||||||
|
wire_manager.py # S-expression wire creation
|
||||||
|
pin_locator.py # Pin position discovery
|
||||||
|
layers.py # Layer utilities
|
||||||
|
outline.py # Board outline utilities
|
||||||
|
size.py # Size/dimension utilities
|
||||||
|
view.py # Board rendering utilities
|
||||||
|
kicad_api/ # Backend abstraction
|
||||||
|
base.py # Abstract base class
|
||||||
|
factory.py # Backend auto-detection
|
||||||
|
swig_backend.py # pcbnew SWIG API backend
|
||||||
|
ipc_backend.py # KiCAD 9.0 IPC API backend
|
||||||
|
schemas/ # JSON Schema definitions
|
||||||
|
tool_schemas.py # Tool parameter schemas
|
||||||
|
resources/ # Resource handlers
|
||||||
|
templates/ # Schematic/project templates
|
||||||
|
tests/ # Python test suite
|
||||||
|
utils/ # Platform detection, helpers
|
||||||
|
|
||||||
|
docs/ # Documentation
|
||||||
|
config/ # Configuration examples
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## TypeScript Layer
|
||||||
|
|
||||||
|
### Server Startup (`src/server.ts`)
|
||||||
|
|
||||||
|
1. Creates an MCP server instance
|
||||||
|
2. Registers all tools from each tool file (registerProjectTools, registerBoardTools, etc.)
|
||||||
|
3. Registers resources and prompts
|
||||||
|
4. Starts the STDIO transport for MCP communication
|
||||||
|
5. On first tool call, spawns the Python subprocess
|
||||||
|
|
||||||
|
### Tool Registration
|
||||||
|
|
||||||
|
Each tool file exports a `register*Tools(server, callKicadScript)` function that:
|
||||||
|
- Defines tool name, description, and Zod schema for parameters
|
||||||
|
- Registers a handler that calls `callKicadScript(command, args)`
|
||||||
|
|
||||||
|
Example from `src/tools/project.ts`:
|
||||||
|
```typescript
|
||||||
|
server.tool(
|
||||||
|
"create_project",
|
||||||
|
"Create a new KiCAD project",
|
||||||
|
{ name: z.string(), path: z.string() },
|
||||||
|
async (args) => {
|
||||||
|
const result = await callKicadScript("create_project", args);
|
||||||
|
return { content: [{ type: "text", text: JSON.stringify(result) }] };
|
||||||
|
}
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tool Router (`src/tools/router.ts` and `src/tools/registry.ts`)
|
||||||
|
|
||||||
|
The router pattern reduces AI context usage:
|
||||||
|
- `registry.ts` defines tool categories and which tools are "direct" (always visible) vs "routed" (discoverable)
|
||||||
|
- `router.ts` provides 4 meta-tools: `list_tool_categories`, `get_category_tools`, `search_tools`, `execute_tool`
|
||||||
|
- Routed tools are not registered as individual MCP tools -- they are invoked through `execute_tool`
|
||||||
|
|
||||||
|
### Python Subprocess Communication
|
||||||
|
|
||||||
|
`callKicadScript(command, args)` in `server.ts`:
|
||||||
|
1. Spawns `python3 python/kicad_interface.py` (if not already running)
|
||||||
|
2. Sends a JSON message: `{"command": "...", "params": {...}}`
|
||||||
|
3. Reads the JSON response
|
||||||
|
4. Returns the result to the MCP tool handler
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Python Layer
|
||||||
|
|
||||||
|
### Main Entry Point (`python/kicad_interface.py`)
|
||||||
|
|
||||||
|
- Reads JSON commands from stdin
|
||||||
|
- Routes commands to the appropriate handler
|
||||||
|
- Manages the pcbnew board object lifecycle
|
||||||
|
- Handles backend selection (SWIG vs IPC)
|
||||||
|
- Auto-saves after board-modifying operations
|
||||||
|
|
||||||
|
### Command Routing
|
||||||
|
|
||||||
|
Commands are routed by name to handler methods. The mapping is defined in `kicad_interface.py`. Each handler:
|
||||||
|
1. Receives a params dict
|
||||||
|
2. Calls the appropriate command class method
|
||||||
|
3. Returns a result dict with `success`, `message`, and any additional data
|
||||||
|
|
||||||
|
### Backend System (`python/kicad_api/`)
|
||||||
|
|
||||||
|
Two backends for interacting with KiCAD:
|
||||||
|
|
||||||
|
**SWIG Backend** (default):
|
||||||
|
- Direct Python bindings to KiCAD's C++ API via SWIG
|
||||||
|
- Operates on files -- loads .kicad_pcb, modifies in memory, saves back
|
||||||
|
- Works without KiCAD running
|
||||||
|
- Requires manual UI reload to see changes
|
||||||
|
|
||||||
|
**IPC Backend** (experimental):
|
||||||
|
- Communicates with running KiCAD via IPC API socket
|
||||||
|
- Changes appear in the UI immediately
|
||||||
|
- Requires KiCAD 9.0+ running with IPC enabled
|
||||||
|
- Falls back to SWIG when unavailable
|
||||||
|
|
||||||
|
`factory.py` auto-detects which backend to use.
|
||||||
|
|
||||||
|
### Schematic System
|
||||||
|
|
||||||
|
Schematic manipulation uses a different stack than PCB operations:
|
||||||
|
- **kicad-skip** library for reading/modifying schematic files
|
||||||
|
- **S-expression parsing** for direct file manipulation (wires, symbols)
|
||||||
|
- **DynamicSymbolLoader** for injecting any KiCad symbol into a schematic
|
||||||
|
- **WireManager** for creating wires via S-expression injection
|
||||||
|
- **PinLocator** for discovering pin positions with rotation support
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Adding a New Tool
|
||||||
|
|
||||||
|
### Step 1: Define the TypeScript Schema
|
||||||
|
|
||||||
|
Create or edit a file in `src/tools/`. Register the tool with `server.tool()`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
server.tool(
|
||||||
|
"my_new_tool",
|
||||||
|
"Description of what the tool does",
|
||||||
|
{
|
||||||
|
param1: z.string().describe("Description of param1"),
|
||||||
|
param2: z.number().optional().describe("Optional param2"),
|
||||||
|
},
|
||||||
|
async (args) => {
|
||||||
|
const result = await callKicadScript("my_new_tool", args);
|
||||||
|
return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
|
||||||
|
}
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Add to Registry (if routed)
|
||||||
|
|
||||||
|
If the tool should be discoverable via the router (not always visible), add it to a category in `src/tools/registry.ts`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
name: "category_name",
|
||||||
|
tools: ["existing_tool", "my_new_tool"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If the tool should always be visible, add it to `directToolNames` instead.
|
||||||
|
|
||||||
|
### Step 3: Import in server.ts
|
||||||
|
|
||||||
|
Import and call the registration function in `src/server.ts`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { registerMyTools } from "./tools/my-tools.js";
|
||||||
|
registerMyTools(server, callKicadScript);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Implement the Python Handler
|
||||||
|
|
||||||
|
Add a handler in `python/kicad_interface.py` or create a new command module in `python/commands/`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def handle_my_new_tool(self, params):
|
||||||
|
# Implementation using pcbnew API
|
||||||
|
return {"success": True, "message": "Done", "data": result}
|
||||||
|
```
|
||||||
|
|
||||||
|
Route the command in the main handler:
|
||||||
|
|
||||||
|
```python
|
||||||
|
elif command == "my_new_tool":
|
||||||
|
return self.handle_my_new_tool(params)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5: Build and Test
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build # Compile TypeScript
|
||||||
|
npm run test:py # Run Python tests
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
### Python Tests
|
||||||
|
|
||||||
|
Located in `python/tests/`. Run with:
|
||||||
|
```bash
|
||||||
|
pytest python/tests/ -v
|
||||||
|
```
|
||||||
|
|
||||||
|
Key test files:
|
||||||
|
- `test_schematic_tools.py` -- schematic tool tests
|
||||||
|
- `test_freerouting.py` -- autorouter tests
|
||||||
|
- `test_delete_schematic_component.py` -- component deletion tests
|
||||||
|
- `test_schematic_component_fields.py` -- field inspection tests
|
||||||
|
- `test_platform_helper.py` -- platform detection tests
|
||||||
|
|
||||||
|
### Manual Testing
|
||||||
|
|
||||||
|
1. Build the server: `npm run build`
|
||||||
|
2. Configure in Claude Desktop or Claude Code
|
||||||
|
3. Test tools interactively through your MCP client
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Design Decisions
|
||||||
|
|
||||||
|
- **TypeScript + Python split**: TypeScript handles MCP protocol (well-supported SDK), Python handles KiCAD (only available API)
|
||||||
|
- **Router pattern**: Reduces AI context from ~80K tokens (122 tools) to manageable size
|
||||||
|
- **Auto-save**: Every board-modifying SWIG operation auto-saves to prevent data loss
|
||||||
|
- **Dynamic symbol loading**: Works around kicad-skip's inability to create symbols from scratch
|
||||||
|
- **S-expression wire injection**: Works around kicad-skip's inability to create wires
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Source Files Reference
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `src/server.ts` | MCP server, subprocess management |
|
||||||
|
| `src/tools/registry.ts` | Tool categories and organization |
|
||||||
|
| `src/tools/router.ts` | Router meta-tools |
|
||||||
|
| `python/kicad_interface.py` | Python entry point, command routing |
|
||||||
|
| `python/kicad_api/factory.py` | Backend selection |
|
||||||
|
| `python/commands/dynamic_symbol_loader.py` | Symbol injection system |
|
||||||
|
| `python/commands/wire_manager.py` | Wire creation engine |
|
||||||
|
| `python/commands/pin_locator.py` | Pin position discovery |
|
||||||
@@ -220,6 +220,8 @@ For any MCP-compatible client that supports STDIO transport:
|
|||||||
| `LOG_LEVEL` | Logging verbosity | `info` |
|
| `LOG_LEVEL` | Logging verbosity | `info` |
|
||||||
| `NODE_ENV` | Node environment | `development` |
|
| `NODE_ENV` | Node environment | `development` |
|
||||||
| `KICAD_BACKEND` | Force backend (`swig` or `ipc`) | Auto-detect |
|
| `KICAD_BACKEND` | Force backend (`swig` or `ipc`) | Auto-detect |
|
||||||
|
| `KICAD_MCP_DEV` | Enable developer mode (auto-save logs to project) | `0` (disabled) |
|
||||||
|
| `FREEROUTING_JAR` | Path to FreeRouting JAR file for autorouting | Not set |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -537,5 +539,5 @@ For bugs or feature requests, open an issue on GitHub.
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Last Updated:** October 25, 2025
|
**Last Updated:** March 21, 2026
|
||||||
**Version:** 2.0.0-alpha.1
|
**Version:** 2.2.3+
|
||||||
|
|||||||
102
docs/DATASHEET_TOOLS_GUIDE.md
Normal file
102
docs/DATASHEET_TOOLS_GUIDE.md
Normal file
@@ -0,0 +1,102 @@
|
|||||||
|
# Datasheet Management Tools
|
||||||
|
|
||||||
|
**Added in:** v2.2.0-alpha
|
||||||
|
|
||||||
|
Two tools for managing component datasheets using LCSC part numbers. Datasheet URLs are constructed directly from LCSC numbers -- no API key or network requests required.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tools Reference
|
||||||
|
|
||||||
|
### `enrich_datasheets`
|
||||||
|
|
||||||
|
Scans a KiCAD schematic and fills in missing Datasheet URLs for components that have an LCSC part number set.
|
||||||
|
|
||||||
|
**How it works:**
|
||||||
|
|
||||||
|
For every placed symbol that has:
|
||||||
|
- An LCSC property set (e.g., `(property "LCSC" "C123456")`)
|
||||||
|
- An empty or missing Datasheet field
|
||||||
|
|
||||||
|
The tool sets the Datasheet field to: `https://www.lcsc.com/datasheet/C123456.pdf`
|
||||||
|
|
||||||
|
The URL is then visible in KiCAD's footprint browser, symbol properties dialog, and any tool that reads the standard Datasheet field.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Default | Description |
|
||||||
|
|-----------|------|----------|---------|-------------|
|
||||||
|
| `schematic_path` | string | Yes | -- | Path to the .kicad_sch file to enrich |
|
||||||
|
| `dry_run` | boolean | No | false | Preview changes without writing to disk |
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
- Number of components updated
|
||||||
|
- Number already set (skipped)
|
||||||
|
- Number without LCSC number
|
||||||
|
- Details of each updated component (reference, LCSC number, URL)
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
Enrich datasheets for all components in ~/Projects/MyBoard/MyBoard.kicad_sch
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `dry_run=true` to preview what would change:
|
||||||
|
```
|
||||||
|
Preview datasheet enrichment for ~/Projects/MyBoard/MyBoard.kicad_sch with dry run enabled.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `get_datasheet_url`
|
||||||
|
|
||||||
|
Get the LCSC datasheet URL for a single component by LCSC number.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `lcsc` | string | Yes | LCSC part number, with or without "C" prefix (e.g., "C179739" or "179739") |
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
- Datasheet PDF URL
|
||||||
|
- Product page URL
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
Get the datasheet URL for LCSC part C179739.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
### Adding Datasheets to a Design
|
||||||
|
|
||||||
|
1. **Add components with LCSC numbers** -- When placing components from JLCPCB libraries or manually setting the LCSC property, each component gets an LCSC part number
|
||||||
|
2. **Run enrich_datasheets** -- Scans all components and fills in any missing Datasheet URLs
|
||||||
|
3. **Verify in KiCAD** -- Open the schematic in KiCAD and check that Datasheet fields are populated. Double-clicking a component shows the URL in its properties
|
||||||
|
|
||||||
|
### Integration with JLCPCB Workflow
|
||||||
|
|
||||||
|
These tools complement the JLCPCB integration:
|
||||||
|
|
||||||
|
1. Use `search_jlcpcb_parts` to find components
|
||||||
|
2. Place components with LCSC numbers from the search results
|
||||||
|
3. Run `enrich_datasheets` to auto-populate datasheet URLs
|
||||||
|
4. Use `export_bom` to generate a BOM with datasheet links
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- The datasheet URL format (`https://www.lcsc.com/datasheet/<LCSC#>.pdf`) works for the vast majority of LCSC parts
|
||||||
|
- No network request is made -- the URL is constructed from the part number alone
|
||||||
|
- Components without an LCSC property are skipped silently
|
||||||
|
- Components that already have a Datasheet URL set are not overwritten
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Source Files
|
||||||
|
|
||||||
|
- TypeScript tool definitions: `src/tools/datasheet.ts`
|
||||||
|
- Python implementation: `python/commands/datasheet_manager.py`
|
||||||
411
docs/FOOTPRINT_SYMBOL_CREATOR_GUIDE.md
Normal file
411
docs/FOOTPRINT_SYMBOL_CREATOR_GUIDE.md
Normal file
@@ -0,0 +1,411 @@
|
|||||||
|
# Creating Custom Footprints and Symbols
|
||||||
|
|
||||||
|
Added in: v2.2.1-alpha (PRs #48, #49, contributor: @Kletternaut)
|
||||||
|
|
||||||
|
When existing KiCAD libraries don't have the component you need, these 8 tools let you create custom footprints and symbols programmatically. This enables automated part creation for custom PCB designs, specialized components, or rapid prototyping workflows where manual library editing would be time-consuming.
|
||||||
|
|
||||||
|
## Part 1: Footprint Creator
|
||||||
|
|
||||||
|
Footprints define the physical copper pads, silkscreen markings, and courtyard boundaries for PCB components. The footprint creator tools generate `.kicad_mod` files inside `.pretty` library directories.
|
||||||
|
|
||||||
|
### create_footprint
|
||||||
|
|
||||||
|
Create a new KiCAD footprint (.kicad_mod) inside a .pretty library directory. Supports SMD and THT pads, courtyard, silkscreen, and fab-layer rectangles.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `libraryPath` | string | Yes | Path to the .pretty library directory (created if missing). E.g. C:/MyProject/MyLib.pretty |
|
||||||
|
| `name` | string | Yes | Footprint name, e.g. 'R_0603_Custom' |
|
||||||
|
| `description` | string | No | Human-readable description |
|
||||||
|
| `tags` | string | No | Space-separated tag string, e.g. 'resistor SMD 0603' |
|
||||||
|
| `pads` | array | No | List of pad objects (see Pad Schema below). Can be empty for outlines-only footprints |
|
||||||
|
| `courtyard` | object | No | Courtyard rectangle on F.CrtYd (recommended: 0.25 mm clearance around pads) |
|
||||||
|
| `silkscreen` | object | No | Silkscreen rectangle on F.SilkS |
|
||||||
|
| `fabLayer` | object | No | Fab-layer rectangle on F.Fab (shows component body) |
|
||||||
|
| `refPosition` | object | No | Position of the REF** text, e.g. {x: 0, y: -1.27} (default: 0, -1.27) |
|
||||||
|
| `valuePosition` | object | No | Position of the Value text, e.g. {x: 0, y: 1.27} (default: 0, 1.27) |
|
||||||
|
| `overwrite` | boolean | No | Replace existing footprint file (default: false) |
|
||||||
|
|
||||||
|
#### Pad Schema
|
||||||
|
|
||||||
|
Each pad object in the `pads` array supports:
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `number` | string | Yes | Pad number / name, e.g. '1', '2', 'A1' |
|
||||||
|
| `type` | enum | Yes | Pad type: `smd`, `thru_hole`, or `np_thru_hole` |
|
||||||
|
| `shape` | enum | No | Pad shape: `rect`, `circle`, `oval`, or `roundrect` (default: rect for SMD, circle for THT) |
|
||||||
|
| `at` | object | Yes | Pad centre position: {x: number, y: number, angle?: number} in mm |
|
||||||
|
| `size` | object | Yes | Pad size: {w: number, h: number} in mm |
|
||||||
|
| `drill` | number or object | No | Round drill diameter (mm) or oval drill {w: number, h: number} (required for thru_hole pads) |
|
||||||
|
| `layers` | array | No | Override default layer list, e.g. ['F.Cu','F.Paste','F.Mask'] |
|
||||||
|
| `roundrect_ratio` | number | No | Corner radius ratio for roundrect shape (0.0-0.5, default 0.25) |
|
||||||
|
|
||||||
|
#### Rectangle Schema (courtyard, silkscreen, fabLayer)
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `x1` | number | Yes | Left X in mm |
|
||||||
|
| `y1` | number | Yes | Top Y in mm |
|
||||||
|
| `x2` | number | Yes | Right X in mm |
|
||||||
|
| `y2` | number | Yes | Bottom Y in mm |
|
||||||
|
| `width` | number | No | Line width in mm |
|
||||||
|
|
||||||
|
#### Pad Types
|
||||||
|
|
||||||
|
- **SMD (smd)**: Surface-mount pads for components that sit on top of the PCB. Default layers: F.Cu, F.Paste, F.Mask
|
||||||
|
- **THT (thru_hole)**: Through-hole pads for components with leads that pass through the PCB. Requires `drill` parameter. Default layers: *.Cu, F.Mask, B.Mask
|
||||||
|
- **NPTH (np_thru_hole)**: Non-plated through-holes for mechanical mounting. Requires `drill` parameter. Default layers: *.Mask
|
||||||
|
|
||||||
|
### edit_footprint_pad
|
||||||
|
|
||||||
|
Edit an existing pad inside a .kicad_mod footprint file. Updates size, position, drill, or shape without recreating the whole footprint.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `footprintPath` | string | Yes | Full path to the .kicad_mod file, e.g. C:/MyLib.pretty/R_Custom.kicad_mod |
|
||||||
|
| `padNumber` | string or number | Yes | Pad number to edit, e.g. '1' or 2 |
|
||||||
|
| `size` | object | No | New pad size: {w: number, h: number} in mm |
|
||||||
|
| `at` | object | No | New pad position: {x: number, y: number, angle?: number} in mm |
|
||||||
|
| `drill` | number or object | No | New drill size: number (round) or {w: number, h: number} (oval) for THT pads |
|
||||||
|
| `shape` | enum | No | New pad shape: `rect`, `circle`, `oval`, or `roundrect` |
|
||||||
|
|
||||||
|
**When to use:** Use this tool when you need to adjust an existing footprint's pad dimensions or positions without recreating the entire footprint. Useful for fine-tuning after initial creation or adapting existing footprints.
|
||||||
|
|
||||||
|
### register_footprint_library
|
||||||
|
|
||||||
|
Register a .pretty footprint library in KiCAD's fp-lib-table so KiCAD can find the footprints. Run this after create_footprint when KiCAD shows 'library not found in footprint library table'.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `libraryPath` | string | Yes | Full path to the .pretty directory to register |
|
||||||
|
| `libraryName` | string | No | Nickname for the library in KiCAD (default: directory name without .pretty) |
|
||||||
|
| `description` | string | No | Optional description |
|
||||||
|
| `scope` | enum | No | `project` = writes fp-lib-table next to the .kicad_pro file (default); `global` = writes to the user's global KiCAD config |
|
||||||
|
| `projectPath` | string | No | Path to the .kicad_pro file or its directory (required for scope=project when the library is not in the project folder) |
|
||||||
|
|
||||||
|
**How fp-lib-table works:** KiCAD maintains a table mapping library nicknames to filesystem paths. Project-scope tables (fp-lib-table in the project directory) take precedence over global tables. This allows project-specific libraries without polluting the global configuration.
|
||||||
|
|
||||||
|
### list_footprint_libraries
|
||||||
|
|
||||||
|
List available .pretty footprint libraries and their contents (first 20 footprints per library). Searches KiCAD standard install paths by default.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `searchPaths` | array | No | Override default search paths. Each entry should be a directory that contains .pretty subdirs |
|
||||||
|
|
||||||
|
### Example: Creating a Custom SOT-23 Footprint
|
||||||
|
|
||||||
|
This example creates a simple 3-pad SMD footprint for a SOT-23 transistor package:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Step 1: Create the footprint
|
||||||
|
{
|
||||||
|
"libraryPath": "/home/user/myproject/CustomParts.pretty",
|
||||||
|
"name": "SOT-23_Custom",
|
||||||
|
"description": "SOT-23 3-pin SMD package, custom pitch",
|
||||||
|
"tags": "SOT-23 transistor SMD",
|
||||||
|
"pads": [
|
||||||
|
{
|
||||||
|
"number": "1",
|
||||||
|
"type": "smd",
|
||||||
|
"shape": "rect",
|
||||||
|
"at": {"x": -0.95, "y": 1.0},
|
||||||
|
"size": {"w": 0.6, "h": 0.7}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"number": "2",
|
||||||
|
"type": "smd",
|
||||||
|
"shape": "rect",
|
||||||
|
"at": {"x": 0.95, "y": 1.0},
|
||||||
|
"size": {"w": 0.6, "h": 0.7}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"number": "3",
|
||||||
|
"type": "smd",
|
||||||
|
"shape": "rect",
|
||||||
|
"at": {"x": 0, "y": -1.0},
|
||||||
|
"size": {"w": 0.6, "h": 0.7}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"courtyard": {
|
||||||
|
"x1": -1.5,
|
||||||
|
"y1": -1.5,
|
||||||
|
"x2": 1.5,
|
||||||
|
"y2": 1.5,
|
||||||
|
"width": 0.05
|
||||||
|
},
|
||||||
|
"silkscreen": {
|
||||||
|
"x1": -1.3,
|
||||||
|
"y1": -0.3,
|
||||||
|
"x2": 1.3,
|
||||||
|
"y2": 0.3,
|
||||||
|
"width": 0.12
|
||||||
|
},
|
||||||
|
"fabLayer": {
|
||||||
|
"x1": -1.25,
|
||||||
|
"y1": -0.25,
|
||||||
|
"x2": 1.25,
|
||||||
|
"y2": 0.25,
|
||||||
|
"width": 0.1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Step 2: Register the library so KiCAD can find it
|
||||||
|
{
|
||||||
|
"libraryPath": "/home/user/myproject/CustomParts.pretty",
|
||||||
|
"scope": "project",
|
||||||
|
"projectPath": "/home/user/myproject/myproject.kicad_pro"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The footprint will be saved as `/home/user/myproject/CustomParts.pretty/SOT-23_Custom.kicad_mod` and will be available in KiCAD's footprint browser under the library name "CustomParts".
|
||||||
|
|
||||||
|
## Part 2: Symbol Creator
|
||||||
|
|
||||||
|
Symbols define the schematic representation of electronic components, including pins, graphical body shapes, and electrical properties. The symbol creator tools generate and manage `.kicad_sym` library files.
|
||||||
|
|
||||||
|
### create_symbol
|
||||||
|
|
||||||
|
Create a new schematic symbol in a .kicad_sym library file (created if missing). After creation, use register_symbol_library so KiCAD finds it.
|
||||||
|
|
||||||
|
Pin positions are where the wire connects; the symbol body is drawn between them.
|
||||||
|
|
||||||
|
**Coordinate tips:**
|
||||||
|
- Body rectangle typically spans ±2.54 to ±5.08 mm
|
||||||
|
- Pins on left side: at.x = body_left - length, angle=0 (wire goes right)
|
||||||
|
- Pins on right side: at.x = body_right + length, angle=180 (wire goes left)
|
||||||
|
- Pins on top: at.y = body_top + length, angle=270 (wire goes down)
|
||||||
|
- Pins on bottom: at.y = body_bottom - length, angle=90 (wire goes up)
|
||||||
|
- Standard pin length: 2.54 mm, standard grid: 2.54 mm
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `libraryPath` | string | Yes | Path to the .kicad_sym file (created if missing) |
|
||||||
|
| `name` | string | Yes | Symbol name, e.g. 'TMC2209', 'MyOpAmp' |
|
||||||
|
| `referencePrefix` | string | No | Schematic reference prefix: 'U' (IC), 'R' (resistor), 'J' (connector), etc. Default: 'U' |
|
||||||
|
| `description` | string | No | Human-readable description |
|
||||||
|
| `keywords` | string | No | Space-separated search keywords |
|
||||||
|
| `datasheet` | string | No | Datasheet URL or '~' |
|
||||||
|
| `footprint` | string | No | Default footprint, e.g. 'Package_SO:SOIC-8_3.9x4.9mm_P1.27mm' |
|
||||||
|
| `inBom` | boolean | No | Include in BOM (default true) |
|
||||||
|
| `onBoard` | boolean | No | Include in netlist for PCB (default true) |
|
||||||
|
| `pins` | array | No | List of pin objects (see Pin Schema below). Can be empty for graphical-only symbols |
|
||||||
|
| `rectangles` | array | No | Body rectangle(s). Typically one rectangle defining the IC body |
|
||||||
|
| `polylines` | array | No | Polyline graphics for custom body shapes (op-amp triangles, etc.) |
|
||||||
|
| `overwrite` | boolean | No | Replace existing symbol with same name (default false) |
|
||||||
|
|
||||||
|
#### Pin Schema
|
||||||
|
|
||||||
|
Each pin object in the `pins` array supports:
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `name` | string | Yes | Pin name, e.g. 'VCC', 'GND', 'IN+', '~' for unnamed |
|
||||||
|
| `number` | string or number | Yes | Pin number, e.g. '1', '2', 'A1' |
|
||||||
|
| `type` | enum | Yes | Electrical pin type (see Pin Types below) |
|
||||||
|
| `at` | object | Yes | Pin endpoint position: {x: number, y: number, angle: number} where angle is the direction the pin wire extends FROM the symbol body |
|
||||||
|
| `length` | number | No | Pin length in mm (default 2.54) |
|
||||||
|
| `shape` | enum | No | Pin graphic shape (default: line) |
|
||||||
|
|
||||||
|
**Pin angle conventions:**
|
||||||
|
- 0 = right (wire extends to the right from the symbol body)
|
||||||
|
- 90 = up (wire extends upward)
|
||||||
|
- 180 = left (wire extends to the left)
|
||||||
|
- 270 = down (wire extends downward)
|
||||||
|
|
||||||
|
#### Pin Types (Electrical)
|
||||||
|
|
||||||
|
| Type | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `input` | Input pin |
|
||||||
|
| `output` | Output pin |
|
||||||
|
| `bidirectional` | Bidirectional I/O |
|
||||||
|
| `tri_state` | Tri-state output |
|
||||||
|
| `passive` | Passive component (resistors, capacitors) |
|
||||||
|
| `free` | Free pin (no electrical rule checking) |
|
||||||
|
| `unspecified` | Unspecified type |
|
||||||
|
| `power_in` | Power input (VCC, VDD) |
|
||||||
|
| `power_out` | Power output (regulators) |
|
||||||
|
| `open_collector` | Open collector output |
|
||||||
|
| `open_emitter` | Open emitter output |
|
||||||
|
| `no_connect` | Not connected |
|
||||||
|
|
||||||
|
#### Pin Shapes (Graphical)
|
||||||
|
|
||||||
|
| Shape | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| `line` | Standard pin (default) |
|
||||||
|
| `inverted` | Pin with inversion bubble |
|
||||||
|
| `clock` | Clock input (triangle) |
|
||||||
|
| `inverted_clock` | Inverted clock with bubble |
|
||||||
|
| `input_low` | Active-low input |
|
||||||
|
| `clock_low` | Active-low clock |
|
||||||
|
| `output_low` | Active-low output |
|
||||||
|
| `falling_edge_clock` | Falling edge triggered |
|
||||||
|
| `non_logic` | Non-logic pin |
|
||||||
|
|
||||||
|
#### Rectangle Schema
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `x1` | number | Yes | Left X in mm |
|
||||||
|
| `y1` | number | Yes | Top Y in mm |
|
||||||
|
| `x2` | number | Yes | Right X in mm |
|
||||||
|
| `y2` | number | Yes | Bottom Y in mm |
|
||||||
|
| `width` | number | No | Stroke width in mm (default 0.254) |
|
||||||
|
| `fill` | enum | No | Fill type: `none`, `outline`, or `background` (default: background) |
|
||||||
|
|
||||||
|
#### Polyline Schema
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `points` | array | Yes | List of XY points: [{x: number, y: number}, ...] in mm |
|
||||||
|
| `width` | number | No | Stroke width in mm (default 0.254) |
|
||||||
|
| `fill` | enum | No | Fill type: `none`, `outline`, or `background` |
|
||||||
|
|
||||||
|
### delete_symbol
|
||||||
|
|
||||||
|
Remove a symbol from a .kicad_sym library file.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `libraryPath` | string | Yes | Path to the .kicad_sym file |
|
||||||
|
| `name` | string | Yes | Symbol name to delete |
|
||||||
|
|
||||||
|
### list_symbols_in_library
|
||||||
|
|
||||||
|
List all symbol names in a .kicad_sym library file.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `libraryPath` | string | Yes | Path to the .kicad_sym file |
|
||||||
|
|
||||||
|
### register_symbol_library
|
||||||
|
|
||||||
|
Register a .kicad_sym library in KiCAD's sym-lib-table so symbols can be used in schematics. Run this after create_symbol when KiCAD shows 'library not found'.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `libraryPath` | string | Yes | Full path to the .kicad_sym file |
|
||||||
|
| `libraryName` | string | No | Nickname (default: file name without extension) |
|
||||||
|
| `description` | string | No | Optional description |
|
||||||
|
| `scope` | enum | No | `project` = writes sym-lib-table next to .kicad_pro (default); `global` = user config |
|
||||||
|
| `projectPath` | string | No | Path to .kicad_pro or its directory (for scope=project) |
|
||||||
|
|
||||||
|
### Example: Creating a Simple IC Symbol
|
||||||
|
|
||||||
|
This example creates a 4-pin IC symbol (VCC, GND, IN, OUT):
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Step 1: Create the symbol
|
||||||
|
{
|
||||||
|
"libraryPath": "/home/user/myproject/CustomSymbols.kicad_sym",
|
||||||
|
"name": "MyRegulator",
|
||||||
|
"referencePrefix": "U",
|
||||||
|
"description": "Simple voltage regulator",
|
||||||
|
"keywords": "regulator power",
|
||||||
|
"datasheet": "~",
|
||||||
|
"footprint": "Package_TO_SOT_SMD:SOT-23",
|
||||||
|
"pins": [
|
||||||
|
{
|
||||||
|
"name": "VIN",
|
||||||
|
"number": "1",
|
||||||
|
"type": "power_in",
|
||||||
|
"at": {"x": -7.62, "y": 2.54, "angle": 0},
|
||||||
|
"length": 2.54
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "GND",
|
||||||
|
"number": "2",
|
||||||
|
"type": "power_in",
|
||||||
|
"at": {"x": 0, "y": -7.62, "angle": 90},
|
||||||
|
"length": 2.54
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "VOUT",
|
||||||
|
"number": "3",
|
||||||
|
"type": "power_out",
|
||||||
|
"at": {"x": 7.62, "y": 2.54, "angle": 180},
|
||||||
|
"length": 2.54
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"rectangles": [
|
||||||
|
{
|
||||||
|
"x1": -5.08,
|
||||||
|
"y1": -5.08,
|
||||||
|
"x2": 5.08,
|
||||||
|
"y2": 5.08,
|
||||||
|
"width": 0.254,
|
||||||
|
"fill": "background"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
// Step 2: Register the library
|
||||||
|
{
|
||||||
|
"libraryPath": "/home/user/myproject/CustomSymbols.kicad_sym",
|
||||||
|
"scope": "project",
|
||||||
|
"projectPath": "/home/user/myproject/myproject.kicad_pro"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pin positioning explained:**
|
||||||
|
- VIN pin at (-7.62, 2.54, angle=0): Wire extends to the right, so the symbol body should be to the right. Body left edge is at -5.08, and pin length is 2.54, so -7.62 = -5.08 - 2.54
|
||||||
|
- GND pin at (0, -7.62, angle=90): Wire extends upward, body bottom is at -5.08, so -7.62 = -5.08 - 2.54
|
||||||
|
- VOUT pin at (7.62, 2.54, angle=180): Wire extends to the left, body right is at 5.08, so 7.62 = 5.08 + 2.54
|
||||||
|
|
||||||
|
## Coordinate Systems
|
||||||
|
|
||||||
|
### Footprint Coordinates
|
||||||
|
|
||||||
|
- Origin (0, 0) is typically at the component center or pin 1
|
||||||
|
- Positive X extends right, positive Y extends down (PCB view from top)
|
||||||
|
- All dimensions in millimeters
|
||||||
|
- Courtyard should extend 0.25mm beyond pads for IPC-7351 compliance
|
||||||
|
- Silkscreen should not overlap pads (typically 0.1-0.2mm clearance)
|
||||||
|
|
||||||
|
### Symbol Coordinates
|
||||||
|
|
||||||
|
- Origin (0, 0) is typically at the symbol center
|
||||||
|
- Positive X extends right, positive Y extends up (schematic convention)
|
||||||
|
- All dimensions in millimeters
|
||||||
|
- Standard grid is 2.54mm (100 mil) for pin spacing
|
||||||
|
- Pin positions define where wires connect, not where the pin graphic starts
|
||||||
|
- Body graphics are drawn independently of pin positions
|
||||||
|
|
||||||
|
### Key Difference
|
||||||
|
|
||||||
|
Footprints use a "Y-down" coordinate system (like screen coordinates), while symbols use a "Y-up" coordinate system (like mathematical graphs). This is a KiCAD convention that matches industry standards for PCB layout vs schematic capture.
|
||||||
|
|
||||||
|
## Integration with Design Workflow
|
||||||
|
|
||||||
|
### Typical Workflow
|
||||||
|
|
||||||
|
1. **Create the symbol** using `create_symbol` with pin definitions and body graphics
|
||||||
|
2. **Register the symbol library** using `register_symbol_library` so it appears in the schematic editor
|
||||||
|
3. **Create the footprint** using `create_footprint` with pad definitions and courtyard
|
||||||
|
4. **Register the footprint library** using `register_footprint_library` so it appears in the PCB editor
|
||||||
|
5. **Link symbol to footprint** by setting the `footprint` parameter in `create_symbol`, or assign it later in the schematic editor
|
||||||
|
|
||||||
|
### Library Organization
|
||||||
|
|
||||||
|
- **Project-scope libraries**: Store in the project directory, register with `scope: "project"`. Best for project-specific custom parts.
|
||||||
|
- **Global libraries**: Store in a central location, register with `scope: "global"`. Best for reusable parts across multiple projects.
|
||||||
|
- **Naming conventions**: Use descriptive names. For footprints: `PackageType_Variant`, e.g. `SOIC-8_Custom`. For symbols: `PartNumber` or `FunctionDescription`.
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
After creating custom parts:
|
||||||
|
- Open KiCAD schematic editor and verify the symbol appears in the "Add Symbol" dialog
|
||||||
|
- Check pin numbers, names, and electrical types in symbol properties
|
||||||
|
- Open KiCAD PCB editor and verify the footprint appears in the footprint browser
|
||||||
|
- Use the 3D viewer to check pad positions and courtyard clearances
|
||||||
|
- Run Design Rules Check (DRC) to ensure courtyard and clearance compliance
|
||||||
|
|
||||||
|
## Source Files
|
||||||
|
|
||||||
|
- TypeScript tool definitions: `/home/chris/MCP/KiCAD-MCP-Server/src/tools/footprint.ts`
|
||||||
|
- TypeScript symbol definitions: `/home/chris/MCP/KiCAD-MCP-Server/src/tools/symbol-creator.ts`
|
||||||
|
- Python footprint implementation: `/home/chris/MCP/KiCAD-MCP-Server/python/commands/footprint.py`
|
||||||
|
- Python symbol implementation: `/home/chris/MCP/KiCAD-MCP-Server/python/commands/symbol_creator.py`
|
||||||
226
docs/FREEROUTING_GUIDE.md
Normal file
226
docs/FREEROUTING_GUIDE.md
Normal file
@@ -0,0 +1,226 @@
|
|||||||
|
# Freerouting Integration Guide
|
||||||
|
|
||||||
|
**Added in:** v2.2.3 (PR #68, contributor: @jflaflamme)
|
||||||
|
|
||||||
|
Freerouting is an open-source autorouter that can automatically route PCB traces. This integration lets you run Freerouting directly from MCP tools without leaving your AI-assisted design workflow.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How It Works
|
||||||
|
|
||||||
|
The autorouter uses the Specctra DSN/SES interchange format:
|
||||||
|
|
||||||
|
1. Export the current PCB to Specctra DSN format
|
||||||
|
2. Run Freerouting CLI on the DSN file
|
||||||
|
3. Import the routed SES result back into the PCB
|
||||||
|
4. Save the board
|
||||||
|
|
||||||
|
The `autoroute` tool performs all four steps in a single call.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
### Freerouting JAR
|
||||||
|
|
||||||
|
Download the Freerouting executable JAR:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p ~/.kicad-mcp
|
||||||
|
curl -L -o ~/.kicad-mcp/freerouting.jar \
|
||||||
|
https://github.com/freerouting/freerouting/releases/download/v2.0.1/freerouting-2.0.1-executable.jar
|
||||||
|
```
|
||||||
|
|
||||||
|
The default location is `~/.kicad-mcp/freerouting.jar`. You can override this with:
|
||||||
|
- The `freeroutingJar` parameter on any tool call
|
||||||
|
- The `FREEROUTING_JAR` environment variable
|
||||||
|
|
||||||
|
### Java Runtime (Option A -- Direct Execution)
|
||||||
|
|
||||||
|
Freerouting 2.x requires Java 21 or higher.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Ubuntu/Debian
|
||||||
|
sudo apt install openjdk-21-jre
|
||||||
|
|
||||||
|
# Verify
|
||||||
|
java -version
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker or Podman (Option B -- No Java Install Needed)
|
||||||
|
|
||||||
|
If you do not have Java 21+ installed, the integration automatically falls back to Docker or Podman using the `eclipse-temurin:21-jre` image.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Pull the image (one-time)
|
||||||
|
docker pull eclipse-temurin:21-jre
|
||||||
|
|
||||||
|
# Or with Podman
|
||||||
|
podman pull eclipse-temurin:21-jre
|
||||||
|
```
|
||||||
|
|
||||||
|
### Automatic Runtime Detection
|
||||||
|
|
||||||
|
The autorouter checks for runtimes in this order:
|
||||||
|
|
||||||
|
1. Local Java 21+ (direct execution, fastest)
|
||||||
|
2. Docker (container execution)
|
||||||
|
3. Podman (container execution)
|
||||||
|
|
||||||
|
If none are available, an error is returned with installation instructions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tools Reference
|
||||||
|
|
||||||
|
### `check_freerouting`
|
||||||
|
|
||||||
|
Verify that prerequisites are installed before running the autorouter.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `freeroutingJar` | string | No | Path to freerouting.jar to check |
|
||||||
|
|
||||||
|
**Returns:** Java availability, version, Docker status, JAR location
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
Check if Freerouting is ready on my system.
|
||||||
|
```
|
||||||
|
|
||||||
|
### `autoroute`
|
||||||
|
|
||||||
|
Run the full autorouting workflow (export DSN, route, import SES).
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
| Parameter | Type | Required | Default | Description |
|
||||||
|
|-----------|------|----------|---------|-------------|
|
||||||
|
| `boardPath` | string | No | Current board | Path to .kicad_pcb file |
|
||||||
|
| `freeroutingJar` | string | No | ~/.kicad-mcp/freerouting.jar | Path to freerouting.jar |
|
||||||
|
| `maxPasses` | number | No | 20 | Maximum routing passes |
|
||||||
|
| `timeout` | number | No | 300 | Timeout in seconds |
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
Autoroute the current board using Freerouting with a 5-minute timeout.
|
||||||
|
```
|
||||||
|
|
||||||
|
### `export_dsn`
|
||||||
|
|
||||||
|
Export the PCB to Specctra DSN format for manual routing workflows.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `boardPath` | string | No | Path to .kicad_pcb file (default: current board) |
|
||||||
|
| `outputPath` | string | No | Output DSN file path (default: same directory as board) |
|
||||||
|
|
||||||
|
### `import_ses`
|
||||||
|
|
||||||
|
Import a routed Specctra SES file back into the PCB.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| `sesPath` | string | Yes | Path to the .ses file to import |
|
||||||
|
| `boardPath` | string | No | Path to .kicad_pcb file (default: current board) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflows
|
||||||
|
|
||||||
|
### Automated (Recommended)
|
||||||
|
|
||||||
|
A single tool call handles everything:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Open the project
|
||||||
|
2. Check Freerouting dependencies
|
||||||
|
3. Run autoroute with max 10 passes
|
||||||
|
4. Run DRC to verify the result
|
||||||
|
5. Export Gerbers
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual DSN/SES Workflow
|
||||||
|
|
||||||
|
For advanced users or external autorouters:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Export the board to Specctra DSN format
|
||||||
|
2. (Run Freerouting GUI or another autorouter externally)
|
||||||
|
3. Import the routed SES file
|
||||||
|
```
|
||||||
|
|
||||||
|
This is useful when you want to:
|
||||||
|
- Use the Freerouting GUI for interactive routing
|
||||||
|
- Use a different autorouter that supports DSN/SES
|
||||||
|
- Route the board on a different machine
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Environment Variable
|
||||||
|
|
||||||
|
Set `FREEROUTING_JAR` in your MCP client configuration to avoid specifying the path on every call:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"kicad": {
|
||||||
|
"command": "node",
|
||||||
|
"args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
|
||||||
|
"env": {
|
||||||
|
"FREEROUTING_JAR": "/path/to/freerouting.jar"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### "Neither Java 21+ nor Docker found"
|
||||||
|
|
||||||
|
Install either Java 21+ or Docker/Podman. See the Prerequisites section above.
|
||||||
|
|
||||||
|
### "Java found but version < 21"
|
||||||
|
|
||||||
|
Freerouting 2.x requires Java 21+. Either:
|
||||||
|
- Upgrade your Java installation
|
||||||
|
- Install Docker as a fallback
|
||||||
|
|
||||||
|
### Timeout Errors
|
||||||
|
|
||||||
|
For complex boards, increase the timeout:
|
||||||
|
```
|
||||||
|
Autoroute with timeout 600 and max passes 30.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Routing Quality
|
||||||
|
|
||||||
|
If the autorouter does not route all connections:
|
||||||
|
- Increase `maxPasses` (default: 20)
|
||||||
|
- Check that your design rules allow the autorouter enough clearance
|
||||||
|
- Run DRC after autorouting to identify any violations
|
||||||
|
- Consider routing critical traces manually first, then autorouting the rest
|
||||||
|
|
||||||
|
### Docker Permission Errors
|
||||||
|
|
||||||
|
If Docker reports permission errors:
|
||||||
|
```bash
|
||||||
|
# Add your user to the docker group
|
||||||
|
sudo usermod -aG docker $USER
|
||||||
|
# Log out and back in for the change to take effect
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Source Files
|
||||||
|
|
||||||
|
- TypeScript tool definitions: `src/tools/freerouting.ts`
|
||||||
|
- Python implementation: `python/commands/freerouting.py`
|
||||||
|
- Tests: `python/tests/test_freerouting.py`
|
||||||
89
docs/INDEX.md
Normal file
89
docs/INDEX.md
Normal file
@@ -0,0 +1,89 @@
|
|||||||
|
# Documentation Index
|
||||||
|
|
||||||
|
KiCAD MCP Server -- AI-assisted PCB design via Model Context Protocol
|
||||||
|
|
||||||
|
**Version:** 2.2.3 | **Tools:** 122 | **Last Updated:** 2026-03-21
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [README](../README.md) | Project overview, installation, configuration, quick start |
|
||||||
|
| [Client Configuration](CLIENT_CONFIGURATION.md) | MCP client setup (Claude Desktop, Cline, Claude Code) |
|
||||||
|
| [Platform Guide](PLATFORM_GUIDE.md) | Linux vs Windows vs macOS differences |
|
||||||
|
| [PCB Design Workflow](PCB_DESIGN_WORKFLOW.md) | End-to-end design guide from project creation to manufacturing |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tool References
|
||||||
|
|
||||||
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [Tool Inventory](TOOL_INVENTORY.md) | Complete list of all 122 tools with access types |
|
||||||
|
| [Schematic Tools Reference](SCHEMATIC_TOOLS_REFERENCE.md) | 27 schematic tools -- components, wiring, analysis, export |
|
||||||
|
| [Routing Tools Reference](ROUTING_TOOLS_REFERENCE.md) | 13 routing tools -- traces, vias, differential pairs, zones |
|
||||||
|
| [Footprint and Symbol Creator Guide](FOOTPRINT_SYMBOL_CREATOR_GUIDE.md) | 8 tools for creating custom footprints and symbols |
|
||||||
|
| [Freerouting Guide](FREEROUTING_GUIDE.md) | 4 autorouter tools -- setup, usage, Docker support |
|
||||||
|
| [SVG Import Guide](SVG_IMPORT_GUIDE.md) | Import SVG logos onto PCB layers |
|
||||||
|
| [Datasheet Tools Guide](DATASHEET_TOOLS_GUIDE.md) | Datasheet enrichment via LCSC |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Integration Guides
|
||||||
|
|
||||||
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [JLCPCB Integration](JLCPCB_INTEGRATION.md) | JLCPCB parts catalog, pricing, component selection |
|
||||||
|
| [JLCPCB Usage Guide](JLCPCB_USAGE_GUIDE.md) | Detailed JLCPCB setup and usage |
|
||||||
|
| [Library Integration](LIBRARY_INTEGRATION.md) | Footprint and symbol library setup |
|
||||||
|
| [IPC Backend Status](IPC_BACKEND_STATUS.md) | Real-time KiCAD UI synchronization (experimental) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflows
|
||||||
|
|
||||||
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [Realtime Workflow](REALTIME_WORKFLOW.md) | Working with IPC backend for live updates |
|
||||||
|
| [Visual Feedback](VISUAL_FEEDBACK.md) | UI visual feedback guide |
|
||||||
|
| [UI Auto Launch](UI_AUTO_LAUNCH.md) | Automatic KiCAD UI launch feature |
|
||||||
|
| [Router Guide](mcp-router-guide.md) | Tool router pattern usage |
|
||||||
|
| [Router Architecture](ROUTER_ARCHITECTURE.md) | Router pattern design |
|
||||||
|
| [Router Quick Start](ROUTER_QUICK_START.md) | Quick start for the router pattern |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [Known Issues](KNOWN_ISSUES.md) | Current issues and workarounds |
|
||||||
|
| [Windows Troubleshooting](WINDOWS_TROUBLESHOOTING.md) | Windows-specific problems |
|
||||||
|
| [Linux Compatibility Audit](LINUX_COMPATIBILITY_AUDIT.md) | Linux platform details |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project Information
|
||||||
|
|
||||||
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [Status Summary](STATUS_SUMMARY.md) | Current project status and feature matrix |
|
||||||
|
| [Roadmap](ROADMAP.md) | Development roadmap and planned features |
|
||||||
|
| [Changelog](../CHANGELOG.md) | Detailed release notes for all versions |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## For Contributors
|
||||||
|
|
||||||
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [Contributing](../CONTRIBUTING.md) | How to contribute to the project |
|
||||||
|
| [Architecture](ARCHITECTURE.md) | System architecture and adding new tools |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Archive
|
||||||
|
|
||||||
|
Historical planning documents are preserved in [docs/archive/](archive/README.md).
|
||||||
@@ -1,9 +1,9 @@
|
|||||||
# KiCAD IPC Backend Implementation Status
|
# KiCAD IPC Backend Implementation Status
|
||||||
|
|
||||||
**Status:** Under Active Development and Testing
|
**Status:** Under Active Development and Testing
|
||||||
**Date:** 2025-12-02
|
**Date:** 2026-03-21
|
||||||
**KiCAD Version:** 9.0.6
|
**KiCAD Version:** 9.0+
|
||||||
**kicad-python Version:** 0.5.0
|
**kicad-python Version:** 0.5.0+
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -209,4 +209,4 @@ python/
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Last Updated:** 2025-12-02
|
**Last Updated:** 2026-03-21
|
||||||
|
|||||||
@@ -1,5 +1,7 @@
|
|||||||
# JLCPCB Integration Guide
|
# JLCPCB Integration Guide
|
||||||
|
|
||||||
|
> **Note:** This document provides usage examples and workflow guidance. For complete API reference and setup instructions, see [JLCPCB_INTEGRATION.md](JLCPCB_INTEGRATION.md).
|
||||||
|
|
||||||
The KiCAD MCP Server provides **three complementary approaches** for working with JLCPCB parts:
|
The KiCAD MCP Server provides **three complementary approaches** for working with JLCPCB parts:
|
||||||
|
|
||||||
1. **JLCSearch Public API** - No authentication required, 2.5M+ parts with pricing (Recommended)
|
1. **JLCSearch Public API** - No authentication required, 2.5M+ parts with pricing (Recommended)
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
# Known Issues & Workarounds
|
# Known Issues & Workarounds
|
||||||
|
|
||||||
**Last Updated:** 2025-12-02
|
**Last Updated:** 2026-03-21
|
||||||
**Version:** 2.1.0-alpha
|
**Version:** 2.2.3
|
||||||
|
|
||||||
This document tracks known issues and provides workarounds where available.
|
This document tracks known issues and provides workarounds where available.
|
||||||
|
|
||||||
@@ -36,7 +36,8 @@ AttributeError: 'BOARD' object has no attribute 'LT_USER'
|
|||||||
|
|
||||||
**Workaround Options:**
|
**Workaround Options:**
|
||||||
1. Use IPC backend (zones fill correctly via IPC)
|
1. Use IPC backend (zones fill correctly via IPC)
|
||||||
2. Open the board in KiCAD UI - zones fill automatically when opened
|
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
|
**Impact:** Medium - affects copper pour visualization until opened in KiCAD
|
||||||
|
|
||||||
@@ -44,94 +45,75 @@ AttributeError: 'BOARD' object has no attribute 'LT_USER'
|
|||||||
|
|
||||||
### 3. UI Manual Reload Required (SWIG Backend)
|
### 3. UI Manual Reload Required (SWIG Backend)
|
||||||
|
|
||||||
**Status:** BY DESIGN - Fixed by IPC
|
**Status:** BY DESIGN
|
||||||
|
|
||||||
**Symptoms:**
|
**Symptoms:**
|
||||||
- MCP makes changes via SWIG backend
|
- MCP makes changes via SWIG backend
|
||||||
- KiCAD doesn't show changes until file is reloaded
|
- KiCAD does not show changes until file is reloaded
|
||||||
|
|
||||||
**Current Workflow:**
|
**Why:** SWIG-based backend modifies files directly and cannot push changes to a running UI
|
||||||
```
|
|
||||||
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 running with IPC enabled)
|
||||||
|
|
||||||
**Fix:** Use IPC backend for real-time updates (requires KiCAD to be running with IPC enabled)
|
**Workaround:** Click the reload prompt in KiCAD or use File > Revert
|
||||||
|
|
||||||
**Workaround:** Click reload prompt or use File > Revert
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 4. IPC Backend Experimental
|
### 4. IPC Backend Limitations
|
||||||
|
|
||||||
**Status:** UNDER DEVELOPMENT
|
**Status:** EXPERIMENTAL
|
||||||
|
|
||||||
**Description:**
|
**Known Limitations:**
|
||||||
The IPC backend is currently being implemented and tested. Some commands may not work as expected in all scenarios.
|
- KiCAD must be running with IPC enabled (Preferences > Plugins > Enable IPC API Server)
|
||||||
|
|
||||||
**Known IPC Limitations:**
|
|
||||||
- KiCAD must be running with IPC enabled
|
|
||||||
- Some commands fall back to SWIG (e.g., delete_trace)
|
- Some commands fall back to SWIG (e.g., delete_trace)
|
||||||
- Footprint loading uses hybrid approach (SWIG for library, IPC for placement)
|
- 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
|
**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
|
## Recently Fixed (v2.2.0 - v2.2.3)
|
||||||
|
|
||||||
### Schematic Component Corruption (Fixed 2026-02-26)
|
### 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()`
|
||||||
|
|
||||||
**Was:** `add_schematic_component` corrupted .kicad_sch files due to sexpdata formatting issues
|
### B.Cu Placement Hang (Fixed v2.2.3)
|
||||||
**Now:** Rewritten to use text manipulation, preserves KiCAD file formatting perfectly
|
- Placing footprints on B.Cu no longer causes ~30s freeze
|
||||||
**Impact:** Schematic workflow fully functional with all component types
|
- Fix: call `board.Add()` before `Flip()`
|
||||||
**Fixed in:** PR #40, commit a69d288
|
|
||||||
|
|
||||||
### DRC Violations API KiCAD 9.0 (Fixed 2026-02-26)
|
### Board Outline Rounded Corners (Fixed v2.2.3)
|
||||||
|
- `add_board_outline` now correctly applies cornerRadius for rounded_rectangle shape
|
||||||
|
|
||||||
**Was:** `get_drc_violations` failed with `AttributeError: 'BOARD' object has no attribute 'GetDRCMarkers'`
|
### Project-Local Library Resolution (Fixed v2.2.2)
|
||||||
**Now:** Reimplemented to use `run_drc()` internally which calls kicad-cli
|
- `add_schematic_component` and `place_component` now search project-local sym-lib-table and fp-lib-table
|
||||||
**Impact:** Maintains backward compatibility while using stable kicad-cli interface
|
- Previously only global KiCAD library paths were searched
|
||||||
|
|
||||||
### Component Library Integration (Fixed 2025-11-01)
|
### Template File Corruption (Fixed v2.2.2)
|
||||||
|
- Removed invalid `;;` comment lines from template schematics
|
||||||
|
- Restored KiCAD 9 format version (20250114) in templates
|
||||||
|
|
||||||
**Was:** Could not find footprint libraries
|
### copy_routing_pattern Empty Results (Fixed v2.2.2)
|
||||||
**Now:** Auto-discovers 153 KiCAD footprint libraries, search and list working
|
- Added geometric fallback when pads have no net assignments
|
||||||
|
|
||||||
### Routing Operations KiCAD 9.0 (Fixed 2025-11-01)
|
### 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
|
||||||
|
|
||||||
**Was:** Multiple API compatibility issues with KiCAD 9.0
|
### SWIG/UUID Comparison Bugs (Fixed v2.2.0)
|
||||||
**Now:** All routing commands tested and working:
|
- Fixed SwigPyObject UUID comparison
|
||||||
- `netinfo.FindNet()` -> `netinfo.NetsByName()[name]`
|
- Fixed SWIG iterator invalidation after board.Remove()
|
||||||
- `zone.SetPriority()` -> `zone.SetAssignedPriority()`
|
- Added board.SetModified() to prevent dangling pointer crashes
|
||||||
- `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`)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -140,31 +122,20 @@ The IPC backend is currently being implemented and tested. Some commands may not
|
|||||||
If you encounter an issue not listed here:
|
If you encounter an issue not listed here:
|
||||||
|
|
||||||
1. **Check MCP logs:** `~/.kicad-mcp/logs/kicad_interface.log`
|
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+)
|
2. **Enable developer mode:** Set `KICAD_MCP_DEV=1` to capture session logs
|
||||||
3. **Try the operation in KiCAD directly** - is it a KiCAD issue?
|
3. **Check KiCAD version:** `python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"` (must be 9.0+)
|
||||||
4. **Open GitHub issue** with:
|
4. **Try the operation in KiCAD directly** -- is it a KiCAD issue?
|
||||||
- Error message
|
5. **Open a GitHub issue** with:
|
||||||
- Log excerpt
|
- Error message and log excerpt
|
||||||
- Steps to reproduce
|
- Steps to reproduce
|
||||||
- KiCAD version
|
- KiCAD version and OS
|
||||||
- OS and version
|
- MCP session log (from `logs/` folder if dev mode is enabled)
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
## General Workarounds
|
||||||
|
|
||||||
### Server Won't Start
|
### Server Will Not Start
|
||||||
```bash
|
```bash
|
||||||
# Check Python can import pcbnew
|
# Check Python can import pcbnew
|
||||||
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"
|
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"
|
||||||
@@ -179,7 +150,7 @@ python3 python/utils/platform_helper.py
|
|||||||
# Always run open_project after server restart
|
# Always run open_project after server restart
|
||||||
```
|
```
|
||||||
|
|
||||||
### KiCAD UI Doesn't Show Changes (SWIG Mode)
|
### KiCAD UI Does Not Show Changes (SWIG Mode)
|
||||||
```
|
```
|
||||||
# File > Revert (or click reload prompt)
|
# File > Revert (or click reload prompt)
|
||||||
# Or: Close and reopen file in KiCAD
|
# Or: Close and reopen file in KiCAD
|
||||||
@@ -198,6 +169,5 @@ python3 python/utils/platform_helper.py
|
|||||||
|
|
||||||
**Need Help?**
|
**Need Help?**
|
||||||
- Check [IPC_BACKEND_STATUS.md](IPC_BACKEND_STATUS.md) for IPC details
|
- 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`
|
- Check logs: `~/.kicad-mcp/logs/kicad_interface.log`
|
||||||
- Open an issue on GitHub
|
- Open an issue on GitHub
|
||||||
|
|||||||
@@ -1,27 +1,37 @@
|
|||||||
# KiCAD Footprint Library Integration
|
# KiCAD Library Integration
|
||||||
|
|
||||||
**Status:** ✅ COMPLETE (Week 2 - Component Library Integration)
|
**Status:** ✅ COMPLETE
|
||||||
**Date:** 2025-11-01
|
**Date:** 2026-03-21
|
||||||
**Version:** 2.1.0-alpha
|
**Version:** 2.2.3+
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
The KiCAD MCP Server now includes full footprint library integration, enabling:
|
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 all installed KiCAD footprint libraries
|
||||||
- ✅ Search and browse footprints across all libraries
|
- ✅ Automatic discovery of KiCAD symbol libraries (including project-local)
|
||||||
|
- ✅ Search and browse footprints/symbols across all libraries
|
||||||
- ✅ Component placement using library footprints
|
- ✅ 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
|
- ✅ Support for both `Library:Footprint` and `Footprint` formats
|
||||||
|
|
||||||
## How It Works
|
## How It Works
|
||||||
|
|
||||||
### Library Discovery
|
### Library Discovery
|
||||||
|
|
||||||
The `LibraryManager` class automatically discovers footprint libraries by:
|
The library system automatically discovers both footprint and symbol libraries:
|
||||||
|
|
||||||
|
**Footprint Libraries** - `LibraryManager` class:
|
||||||
|
|
||||||
1. **Parsing fp-lib-table files:**
|
1. **Parsing fp-lib-table files:**
|
||||||
- Global: `~/.config/kicad/9.0/fp-lib-table`
|
- Global: `~/.config/kicad/9.0/fp-lib-table`
|
||||||
- Project-specific: `project-dir/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:**
|
2. **Resolving environment variables:**
|
||||||
- `${KICAD9_FOOTPRINT_DIR}` → `/usr/share/kicad/footprints`
|
- `${KICAD9_FOOTPRINT_DIR}` → `/usr/share/kicad/footprints`
|
||||||
- `${K IPRJMOD}` → project directory
|
- `${K IPRJMOD}` → project directory
|
||||||
@@ -337,7 +347,9 @@ rotation = module.GetOrientation().AsDegrees()
|
|||||||
|
|
||||||
## Changelog
|
## Changelog
|
||||||
|
|
||||||
**2025-11-01 - v2.1.0-alpha**
|
**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
|
- ✅ Implemented LibraryManager class
|
||||||
- ✅ Added 4 new MCP library tools
|
- ✅ Added 4 new MCP library tools
|
||||||
- ✅ Updated component placement to use libraries
|
- ✅ Updated component placement to use libraries
|
||||||
|
|||||||
304
docs/PCB_DESIGN_WORKFLOW.md
Normal file
304
docs/PCB_DESIGN_WORKFLOW.md
Normal file
@@ -0,0 +1,304 @@
|
|||||||
|
# End-to-End PCB Design Workflow
|
||||||
|
|
||||||
|
This guide walks through the complete PCB design process using the KiCAD MCP Server, from project creation to manufacturing-ready output.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
A typical PCB design follows this flow:
|
||||||
|
|
||||||
|
```
|
||||||
|
Project Setup -> Schematic Design -> PCB Layout -> Verification -> Manufacturing Output
|
||||||
|
```
|
||||||
|
|
||||||
|
Each stage maps to specific MCP tools. You can ask your AI assistant to perform any of these steps using natural language.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 1: Project Setup
|
||||||
|
|
||||||
|
### Create a New Project
|
||||||
|
|
||||||
|
```
|
||||||
|
Create a new KiCAD project named "LEDBoard" in ~/Projects/
|
||||||
|
```
|
||||||
|
|
||||||
|
This uses `create_project` to generate:
|
||||||
|
- `.kicad_pro` -- project file
|
||||||
|
- `.kicad_pcb` -- PCB layout file
|
||||||
|
- `.kicad_sch` -- schematic file (with template symbols pre-loaded)
|
||||||
|
|
||||||
|
### Set Up the Board
|
||||||
|
|
||||||
|
```
|
||||||
|
Set the board size to 50mm x 50mm.
|
||||||
|
Add a rectangular board outline.
|
||||||
|
Add mounting holes at each corner, 3mm from the edges, 3mm diameter.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools used:** `set_board_size`, `add_board_outline`, `add_mounting_hole`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 2: Schematic Design
|
||||||
|
|
||||||
|
### Place Components
|
||||||
|
|
||||||
|
```
|
||||||
|
Add an LED from the Device library to the schematic at position 100, 50.
|
||||||
|
Add a 1K resistor at position 100, 70.
|
||||||
|
Add a connector from the Connector_Generic library with 2 pins at position 60, 60.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `add_schematic_component`
|
||||||
|
|
||||||
|
The dynamic symbol loader provides access to all ~10,000 KiCad standard symbols. Specify any library and symbol name.
|
||||||
|
|
||||||
|
### Wire Components
|
||||||
|
|
||||||
|
```
|
||||||
|
Connect R1 pin 2 to LED1 pin 1.
|
||||||
|
Add a net label "VCC" at position 60, 50.
|
||||||
|
Connect J1 pin 1 to the VCC net.
|
||||||
|
Connect LED1 pin 2 to GND.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `add_schematic_connection`, `add_schematic_net_label`, `connect_to_net`
|
||||||
|
|
||||||
|
### FFC/Ribbon Cable Passthrough (Special Workflow)
|
||||||
|
|
||||||
|
For passthrough adapter boards (e.g., Raspberry Pi CSI adapters):
|
||||||
|
|
||||||
|
```
|
||||||
|
Connect all pins from J1 to J2 as a passthrough with net prefix "CSI_".
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `connect_passthrough` -- automatically wires matching pins between two connectors
|
||||||
|
|
||||||
|
### Annotate and Validate
|
||||||
|
|
||||||
|
```
|
||||||
|
Annotate the schematic to assign reference designators.
|
||||||
|
Run an electrical rule check.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `annotate_schematic`, `run_erc`
|
||||||
|
|
||||||
|
### Preview the Schematic
|
||||||
|
|
||||||
|
```
|
||||||
|
Show me the schematic as an image.
|
||||||
|
Export the schematic to PDF.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `get_schematic_view`, `export_schematic_pdf`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 3: PCB Layout
|
||||||
|
|
||||||
|
### Synchronize Schematic to PCB
|
||||||
|
|
||||||
|
```
|
||||||
|
Sync the schematic to the board.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `sync_schematic_to_board` -- imports all component footprints and net assignments from the schematic into the PCB (equivalent to pressing F8 in KiCAD)
|
||||||
|
|
||||||
|
### Place Components
|
||||||
|
|
||||||
|
```
|
||||||
|
Move R1 to position x=15, y=25.
|
||||||
|
Move LED1 to position x=25, y=25.
|
||||||
|
Align all resistors horizontally.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `move_component`, `align_components`
|
||||||
|
|
||||||
|
### Route Traces
|
||||||
|
|
||||||
|
**Preferred approach -- pad-to-pad routing:**
|
||||||
|
```
|
||||||
|
Route R1 pad 2 to LED1 pad 1 with 0.3mm trace width.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `route_pad_to_pad` -- auto-detects pad positions, nets, and inserts vias when pads are on different layers
|
||||||
|
|
||||||
|
**Manual approach:**
|
||||||
|
```
|
||||||
|
Route a trace from x=15, y=25 to x=25, y=25 on the front copper layer.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `route_trace`
|
||||||
|
|
||||||
|
### Advanced Routing
|
||||||
|
|
||||||
|
**Differential pairs:**
|
||||||
|
```
|
||||||
|
Route a differential pair for USB_P and USB_N with 0.2mm width and 0.15mm gap.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Copper zones:**
|
||||||
|
```
|
||||||
|
Add a GND copper pour on the bottom layer covering the entire board.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `route_differential_pair`, `add_copper_pour`
|
||||||
|
|
||||||
|
### Autorouting
|
||||||
|
|
||||||
|
For boards with many connections:
|
||||||
|
```
|
||||||
|
Check if Freerouting is available.
|
||||||
|
Autoroute the board using Freerouting.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `check_freerouting`, `autoroute`
|
||||||
|
|
||||||
|
See [Freerouting Guide](FREEROUTING_GUIDE.md) for setup details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 4: Verification
|
||||||
|
|
||||||
|
### Design Rule Check
|
||||||
|
|
||||||
|
```
|
||||||
|
Set design rules with 0.15mm clearance and 0.2mm minimum track width.
|
||||||
|
Run the design rule check.
|
||||||
|
Show me all DRC violations.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `set_design_rules`, `run_drc`, `get_drc_violations`
|
||||||
|
|
||||||
|
### Visual Inspection
|
||||||
|
|
||||||
|
```
|
||||||
|
Show me a 2D view of the board.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `get_board_2d_view`
|
||||||
|
|
||||||
|
### Save a Checkpoint
|
||||||
|
|
||||||
|
```
|
||||||
|
Save a snapshot named "post-routing" with label "All traces routed, DRC clean".
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `snapshot_project`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 5: Manufacturing Output
|
||||||
|
|
||||||
|
### Gerber Files
|
||||||
|
|
||||||
|
```
|
||||||
|
Export Gerber files to the fabrication folder.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `export_gerber`
|
||||||
|
|
||||||
|
### Bill of Materials
|
||||||
|
|
||||||
|
```
|
||||||
|
Export BOM as CSV.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `export_bom` (supports CSV, XML, HTML, JSON)
|
||||||
|
|
||||||
|
### Pick and Place
|
||||||
|
|
||||||
|
```
|
||||||
|
Export the component position file.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `export_position_file`
|
||||||
|
|
||||||
|
### 3D Preview
|
||||||
|
|
||||||
|
```
|
||||||
|
Export a 3D STEP model of the board.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `export_3d` (supports STEP, STL, VRML, OBJ)
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
|
||||||
|
```
|
||||||
|
Export a PDF of the board layout.
|
||||||
|
Export an SVG of the board.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `export_pdf`, `export_svg`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Optional: JLCPCB Component Selection
|
||||||
|
|
||||||
|
Before placing components, you can search JLCPCB's catalog for optimal parts:
|
||||||
|
|
||||||
|
```
|
||||||
|
Search JLCPCB for 10K resistors in 0603 package, Basic parts only.
|
||||||
|
Show me the cheapest option with good stock.
|
||||||
|
Suggest alternatives to part C25804.
|
||||||
|
```
|
||||||
|
|
||||||
|
After selecting parts, enrich datasheets:
|
||||||
|
```
|
||||||
|
Enrich datasheets for all components in the schematic.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `search_jlcpcb_parts`, `get_jlcpcb_part`, `suggest_jlcpcb_alternatives`, `enrich_datasheets`
|
||||||
|
|
||||||
|
See [JLCPCB Integration](JLCPCB_INTEGRATION.md) for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Optional: Custom Components
|
||||||
|
|
||||||
|
When existing libraries do not have the part you need:
|
||||||
|
|
||||||
|
```
|
||||||
|
Create a custom footprint for a 4-pin SOT-23 package.
|
||||||
|
Create a custom symbol for the XYZ IC with 8 pins.
|
||||||
|
Register the custom library so it can be used in the project.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tools:** `create_footprint`, `create_symbol`, `register_footprint_library`, `register_symbol_library`
|
||||||
|
|
||||||
|
See [Footprint and Symbol Creator Guide](FOOTPRINT_SYMBOL_CREATOR_GUIDE.md) for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Optional: Add a Logo
|
||||||
|
|
||||||
|
```
|
||||||
|
Import our company logo from ~/logos/logo.svg onto the front silkscreen at position x=25 y=45 with width 10mm.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool:** `import_svg_logo`
|
||||||
|
|
||||||
|
See [SVG Import Guide](SVG_IMPORT_GUIDE.md) for requirements and tips.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tips
|
||||||
|
|
||||||
|
- **Save frequently** -- use `save_project` after major changes
|
||||||
|
- **Use snapshots** -- `snapshot_project` creates named checkpoints you can return to
|
||||||
|
- **Validate early** -- run ERC after schematic changes and DRC after routing
|
||||||
|
- **Start with schematic** -- always design the schematic first, then sync to PCB
|
||||||
|
- **Use route_pad_to_pad** -- it is faster and more reliable than manual XY coordinate routing
|
||||||
|
- **Check the KiCAD UI** -- use `launch_kicad_ui` to open the design for visual verification
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Documentation
|
||||||
|
|
||||||
|
- [Tool Inventory](TOOL_INVENTORY.md) -- complete list of all 122 tools
|
||||||
|
- [Schematic Tools Reference](SCHEMATIC_TOOLS_REFERENCE.md) -- detailed schematic tool docs
|
||||||
|
- [Routing Tools Reference](ROUTING_TOOLS_REFERENCE.md) -- detailed routing tool docs
|
||||||
|
- [Freerouting Guide](FREEROUTING_GUIDE.md) -- autorouter setup and usage
|
||||||
|
- [JLCPCB Integration](JLCPCB_INTEGRATION.md) -- parts selection and cost optimization
|
||||||
358
docs/ROADMAP.md
358
docs/ROADMAP.md
@@ -2,313 +2,113 @@
|
|||||||
|
|
||||||
**Vision:** Enable anyone to design professional PCBs through natural conversation with AI
|
**Vision:** Enable anyone to design professional PCBs through natural conversation with AI
|
||||||
|
|
||||||
**Current Version:** 2.1.0-alpha
|
**Current Version:** 2.2.3
|
||||||
**Target:** 2.0.0 stable by end of Week 12
|
**Last Updated:** 2026-03-21
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Week 2: Component Integration & Routing
|
## Completed Milestones
|
||||||
|
|
||||||
**Goal:** Make the MCP server useful for real PCB design
|
### v1.0.0 - Core Foundation (October 2025)
|
||||||
**Status:** 80% Complete (2025-11-01)
|
- [x] MCP protocol implementation (JSON-RPC 2.0, MCP 2025-06-18)
|
||||||
|
- [x] Project management (create, open, save)
|
||||||
|
- [x] Board operations (size, outline, layers, mounting holes, text)
|
||||||
|
- [x] Component placement with 153+ footprint libraries
|
||||||
|
- [x] Basic routing (traces, vias, copper pours)
|
||||||
|
- [x] Design rule checking
|
||||||
|
- [x] Export (Gerber, PDF, SVG, 3D, BOM)
|
||||||
|
- [x] Cross-platform support (Linux, Windows, macOS)
|
||||||
|
- [x] UI auto-launch and detection
|
||||||
|
|
||||||
### High Priority
|
### v2.0.0-alpha - Router and IPC (November-December 2025)
|
||||||
|
- [x] Tool router pattern -- 70% AI context reduction
|
||||||
|
- [x] IPC backend for real-time KiCAD UI synchronization (21 commands)
|
||||||
|
- [x] Hybrid SWIG/IPC backend with automatic fallback
|
||||||
|
- [x] Comprehensive Windows support with automated setup
|
||||||
|
|
||||||
**1. Component Library Integration** ✅ **COMPLETE**
|
### v2.1.0-alpha - Schematics and JLCPCB (January 2026)
|
||||||
- [x] Detect KiCAD footprint library paths
|
- [x] Complete schematic workflow fix (Issue #26)
|
||||||
- [x] Add configuration for custom library paths
|
- [x] Dynamic symbol loading -- access to all ~10,000 KiCad symbols
|
||||||
- [x] Create footprint search/autocomplete
|
- [x] Intelligent wiring system with pin discovery and smart routing
|
||||||
- [x] Test component placement end-to-end
|
- [x] Power symbol support (VCC, GND, +3V3, +5V)
|
||||||
- [x] Document supported footprints
|
- [x] Wire graph analysis for net connectivity
|
||||||
|
- [x] JLCPCB parts integration (2.5M+ parts, dual-mode architecture)
|
||||||
|
- [x] Local symbol library search (contributor: @l3wi)
|
||||||
|
|
||||||
**Deliverable:** ✅ Place components with actual footprints from libraries (153 libraries discovered!)
|
### v2.2.0 through v2.2.3 - Routing, Creators, Autorouting (February-March 2026)
|
||||||
|
- [x] 13 new routing/component tools (delete/query/modify traces, arrays, alignment)
|
||||||
**2. Routing Operations** ✅ **COMPLETE**
|
- [x] route_pad_to_pad with auto-via insertion for cross-layer connections
|
||||||
- [x] Test `route_trace` with KiCAD 9.0
|
- [x] copy_routing_pattern for trace replication
|
||||||
- [x] Test `add_via` with KiCAD 9.0
|
- [x] route_differential_pair for matched signals
|
||||||
- [x] Test `add_copper_pour` with KiCAD 9.0
|
- [x] Custom footprint creator (4 tools)
|
||||||
- [x] Fix any API compatibility issues
|
- [x] Custom symbol creator (4 tools)
|
||||||
- [x] Add routing examples to docs
|
- [x] Datasheet enrichment tools (LCSC integration)
|
||||||
|
- [x] 11 schematic inspection/editing tools (contributor: @Mehanik)
|
||||||
**Deliverable:** ✅ Successfully route a simple board (tested with nets, traces, vias, copper pours)
|
- [x] FFC/ribbon cable passthrough workflow (connect_passthrough, sync_schematic_to_board)
|
||||||
|
- [x] SVG logo import for PCB silkscreen
|
||||||
**3. JLCPCB Parts Database** 📋 **PLANNED**
|
- [x] ERC validation
|
||||||
- [x] Research JLCPCB API and data format
|
- [x] Project snapshot system
|
||||||
- [x] Design integration architecture
|
- [x] Freerouting autorouter integration with Docker/Podman (contributor: @jflaflamme)
|
||||||
- [ ] Download/parse JLCPCB parts database (~108k parts)
|
- [x] Project-local library resolution
|
||||||
- [ ] Map parts to KiCAD footprints
|
- [x] Developer mode (KICAD_MCP_DEV=1)
|
||||||
- [ ] Create search by part number
|
|
||||||
- [ ] Add price/stock information
|
|
||||||
- [ ] Integrate with component placement
|
|
||||||
|
|
||||||
**Deliverable:** "Add a 10k resistor (JLCPCB basic part)" - Ready to implement
|
|
||||||
|
|
||||||
### Medium Priority
|
|
||||||
|
|
||||||
**4. Fix get_board_info** 🟡 **DEFERRED**
|
|
||||||
- [ ] Update layer constants for KiCAD 9.0
|
|
||||||
- [ ] Add backward compatibility
|
|
||||||
- [ ] Test with real boards
|
|
||||||
|
|
||||||
**Status:** Low priority, workarounds available
|
|
||||||
|
|
||||||
**5. Example Projects** 🟢
|
|
||||||
- [ ] LED blinker (555 timer)
|
|
||||||
- [ ] Arduino Uno shield template
|
|
||||||
- [ ] Raspberry Pi HAT template
|
|
||||||
- [ ] Video tutorial of complete workflow
|
|
||||||
|
|
||||||
### Bonus Achievements ✨
|
|
||||||
|
|
||||||
**Real-time Collaboration** ✅ **COMPLETE**
|
|
||||||
- [x] Test MCP→UI workflow (AI places, human sees)
|
|
||||||
- [x] Test UI→MCP workflow (human edits, AI reads)
|
|
||||||
- [x] Document best practices and limitations
|
|
||||||
- [x] Verify bidirectional sync works correctly
|
|
||||||
|
|
||||||
**Documentation** ✅ **COMPLETE**
|
|
||||||
- [x] LIBRARY_INTEGRATION.md (comprehensive library guide)
|
|
||||||
- [x] REALTIME_WORKFLOW.md (collaboration workflows)
|
|
||||||
- [x] JLCPCB_INTEGRATION_PLAN.md (implementation plan)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Week 3: IPC Backend & Real-time Updates
|
## Current Focus: v2.3+
|
||||||
|
|
||||||
**Goal:** Eliminate manual reload - see changes instantly
|
### Documentation Overhaul (In Progress)
|
||||||
**Status:** 🟢 **IMPLEMENTED** (2025-11-30)
|
- [ ] Per-feature documentation for all 122 tools
|
||||||
|
- [ ] Architecture guide for contributors
|
||||||
|
- [ ] End-to-end PCB design workflow guide
|
||||||
|
- [ ] Documentation index
|
||||||
|
|
||||||
### High Priority
|
### Quality and Stability
|
||||||
|
- [ ] Expand test coverage across all tool categories
|
||||||
**1. IPC Connection** ✅ **COMPLETE**
|
- [ ] Performance profiling for large boards
|
||||||
- [x] Establish socket connection to KiCAD
|
- [ ] Update package.json version to match CHANGELOG
|
||||||
- [x] Handle connection errors gracefully
|
|
||||||
- [x] Auto-reconnect if KiCAD restarts
|
|
||||||
- [x] Fall back to SWIG if IPC unavailable
|
|
||||||
|
|
||||||
**2. IPC Operations** ✅ **COMPLETE**
|
|
||||||
- [x] Port project operations to IPC
|
|
||||||
- [x] Port board operations to IPC
|
|
||||||
- [x] Port component operations to IPC
|
|
||||||
- [x] Port routing operations to IPC
|
|
||||||
|
|
||||||
**3. Real-time UI Updates** ✅ **COMPLETE**
|
|
||||||
- [x] Changes appear instantly in UI
|
|
||||||
- [x] No reload prompt
|
|
||||||
- [x] Visual feedback within 100ms
|
|
||||||
- [ ] Demo video showing real-time design
|
|
||||||
|
|
||||||
**Deliverable:** ✅ Design a board with live updates as Claude works
|
|
||||||
|
|
||||||
### Medium Priority
|
|
||||||
|
|
||||||
**4. Dual Backend Support** ✅ **COMPLETE**
|
|
||||||
- [x] Auto-detect if IPC is available
|
|
||||||
- [x] Switch between SWIG/IPC seamlessly
|
|
||||||
- [x] Document when to use each
|
|
||||||
- [ ] Performance comparison
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Week 4-5: Smart BOM & Supplier Integration
|
## Planned Features
|
||||||
|
|
||||||
**Goal:** Optimize component selection for cost and availability
|
### Supplier Integration
|
||||||
|
- [ ] Digikey API integration
|
||||||
|
- [ ] Mouser API integration
|
||||||
|
- [ ] Smart BOM management with real-time pricing
|
||||||
|
- [ ] Cost optimization across suppliers
|
||||||
|
|
||||||
**1. Digikey Integration**
|
### Design Patterns and Templates
|
||||||
- [ ] API authentication
|
- [ ] Circuit patterns library (voltage regulators, USB, microcontrollers)
|
||||||
- [ ] Part search by specs
|
- [ ] Board templates (Arduino shields, RPi HATs, Feather wings)
|
||||||
- [ ] Price/stock checking
|
- [ ] Auto-suggest trace widths by current
|
||||||
- [ ] Parametric search (e.g., "10k resistor, 0603, 1%")
|
- [ ] Impedance-controlled trace support
|
||||||
|
|
||||||
**2. Smart BOM Management**
|
### Advanced Capabilities
|
||||||
- [ ] Auto-suggest component substitutions
|
- [ ] Panelization support
|
||||||
- [ ] Calculate total board cost
|
- [ ] Multi-board project management
|
||||||
- [ ] Check component availability
|
- [ ] High-speed design helpers (length matching, via stitching)
|
||||||
- [ ] Generate purchase links
|
- [ ] SPICE simulation integration
|
||||||
|
|
||||||
**3. Cost Optimization**
|
### Community and Education
|
||||||
- [ ] Suggest JLCPCB basic parts (free assembly)
|
- [ ] Example project gallery with tutorials
|
||||||
- [ ] Warn about expensive/obsolete parts
|
- [ ] Video walkthrough series
|
||||||
- [ ] Batch component suggestions
|
- [ ] Interactive beginner tutorials
|
||||||
|
|
||||||
**Deliverable:** "Design a low-cost LED driver under $5 BOM"
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Week 6-7: Design Patterns & Templates
|
|
||||||
|
|
||||||
**Goal:** Accelerate common design tasks
|
|
||||||
|
|
||||||
**1. Circuit Patterns Library**
|
|
||||||
- [ ] Voltage regulators (LDO, switching)
|
|
||||||
- [ ] USB interfaces (USB-C, micro-USB)
|
|
||||||
- [ ] Microcontroller circuits (ESP32, STM32, RP2040)
|
|
||||||
- [ ] Power protection (reverse polarity, ESD)
|
|
||||||
- [ ] Common interfaces (I2C, SPI, UART)
|
|
||||||
|
|
||||||
**2. Board Templates**
|
|
||||||
- [ ] Arduino form factors (Uno, Nano, Mega)
|
|
||||||
- [ ] Raspberry Pi HATs
|
|
||||||
- [ ] Feather wings
|
|
||||||
- [ ] Custom PCB shapes (badges, wearables)
|
|
||||||
|
|
||||||
**3. Auto-routing Helpers**
|
|
||||||
- [ ] Suggest trace widths by current
|
|
||||||
- [ ] Auto-create ground pours
|
|
||||||
- [ ] Match differential pair lengths
|
|
||||||
- [ ] Check impedance requirements
|
|
||||||
|
|
||||||
**Deliverable:** "Create an ESP32 dev board with USB-C"
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Week 8-9: Guided Workflows & Education
|
|
||||||
|
|
||||||
**Goal:** Make PCB design accessible to beginners
|
|
||||||
|
|
||||||
**1. Interactive Tutorials**
|
|
||||||
- [ ] First PCB (LED blinker)
|
|
||||||
- [ ] Understanding layers and vias
|
|
||||||
- [ ] Routing best practices
|
|
||||||
- [ ] Design rule checking
|
|
||||||
|
|
||||||
**2. Design Validation**
|
|
||||||
- [ ] Check for common mistakes
|
|
||||||
- [ ] Suggest improvements
|
|
||||||
- [ ] Explain DRC violations
|
|
||||||
- [ ] Manufacturing feasibility check
|
|
||||||
|
|
||||||
**3. Documentation Generation**
|
|
||||||
- [ ] Auto-generate assembly drawings
|
|
||||||
- [ ] Create BOM spreadsheets
|
|
||||||
- [ ] Export fabrication files
|
|
||||||
- [ ] Generate user manual
|
|
||||||
|
|
||||||
**Deliverable:** Complete beginner-to-fabrication tutorial
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Week 10-11: Advanced Features
|
|
||||||
|
|
||||||
**Goal:** Support complex professional designs
|
|
||||||
|
|
||||||
**1. Multi-board Projects**
|
|
||||||
- [ ] Panel designs for manufacturing
|
|
||||||
- [ ] Shared schematics across boards
|
|
||||||
- [ ] Version management
|
|
||||||
|
|
||||||
**2. High-speed Design**
|
|
||||||
- [ ] Impedance-controlled traces
|
|
||||||
- [ ] Length matching for DDR/PCIe
|
|
||||||
- [ ] Signal integrity analysis
|
|
||||||
- [ ] Via stitching for EMI
|
|
||||||
|
|
||||||
**3. Advanced Components**
|
|
||||||
- [ ] BGAs and fine-pitch packages
|
|
||||||
- [ ] Flex PCB support
|
|
||||||
- [ ] Rigid-flex designs
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Week 12: Polish & Release
|
|
||||||
|
|
||||||
**Goal:** Production-ready v2.0 release
|
|
||||||
|
|
||||||
**1. Performance**
|
|
||||||
- [ ] Optimize large board operations
|
|
||||||
- [ ] Cache library searches
|
|
||||||
- [ ] Parallel operations where possible
|
|
||||||
|
|
||||||
**2. Testing**
|
|
||||||
- [ ] Unit tests for all commands
|
|
||||||
- [ ] Integration tests for workflows
|
|
||||||
- [ ] Test on Windows/macOS/Linux
|
|
||||||
- [ ] Load testing with complex boards
|
|
||||||
|
|
||||||
**3. Documentation**
|
|
||||||
- [ ] Complete API reference
|
|
||||||
- [ ] Video tutorial series
|
|
||||||
- [ ] Blog post/announcement
|
|
||||||
- [ ] Example project gallery
|
|
||||||
|
|
||||||
**4. Community**
|
|
||||||
- [ ] Contribution guidelines
|
|
||||||
- [ ] Plugin system for custom tools
|
- [ ] Plugin system for custom tools
|
||||||
- [ ] Discord/forum for support
|
|
||||||
|
|
||||||
**Deliverable:** KiCAD MCP v2.0 stable release
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Future (Post-v2.0)
|
|
||||||
|
|
||||||
**Big Ideas for v3.0+**
|
|
||||||
|
|
||||||
**1. AI-Powered Design**
|
|
||||||
- Generate circuits from specifications
|
|
||||||
- Optimize layouts for size/cost/performance
|
|
||||||
- Suggest alternative designs
|
|
||||||
- Learn from user preferences
|
|
||||||
|
|
||||||
**2. Collaboration**
|
|
||||||
- Multi-user design sessions
|
|
||||||
- Design reviews and comments
|
|
||||||
- Version control integration (Git)
|
|
||||||
- Share design patterns
|
|
||||||
|
|
||||||
**3. Manufacturing Integration**
|
|
||||||
- Direct order to PCB fabs
|
|
||||||
- Assembly service integration
|
|
||||||
- Track order status
|
|
||||||
- Automated quoting
|
|
||||||
|
|
||||||
**4. Simulation**
|
|
||||||
- SPICE integration for circuit sim
|
|
||||||
- Thermal simulation
|
|
||||||
- Signal integrity
|
|
||||||
- Power integrity
|
|
||||||
|
|
||||||
**5. Extended Platform Support**
|
|
||||||
- Altium import/export
|
|
||||||
- Eagle compatibility
|
|
||||||
- EasyEDA integration
|
|
||||||
- Web-based viewer
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Success Metrics
|
|
||||||
|
|
||||||
**v2.0 Release Criteria:**
|
|
||||||
|
|
||||||
- [ ] 95%+ of commands working reliably
|
|
||||||
- [ ] Component placement with 10,000+ footprints
|
|
||||||
- [ ] IPC backend working on all platforms
|
|
||||||
- [ ] 10+ example projects
|
|
||||||
- [ ] 5+ video tutorials
|
|
||||||
- [ ] 100+ GitHub stars
|
|
||||||
- [ ] 10+ community contributors
|
|
||||||
|
|
||||||
**User Success Stories:**
|
|
||||||
- "Designed my first PCB with Claude Code in 30 minutes"
|
|
||||||
- "Cut PCB design time by 80% using MCP"
|
|
||||||
- "Got my board manufactured - it works!"
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## How to Contribute
|
## How to Contribute
|
||||||
|
|
||||||
See the roadmap and want to help?
|
See the roadmap items above and want to help? High-value contributions:
|
||||||
|
|
||||||
**High-value contributions:**
|
1. Testing on Windows/macOS with KiCAD 9
|
||||||
1. Component library mappings (JLCPCB → KiCAD)
|
2. Example projects and workflow documentation
|
||||||
2. Design pattern library (circuits you use often)
|
3. Bug reports with reproduction steps
|
||||||
3. Testing on Windows/macOS
|
4. New tool implementations (see [ARCHITECTURE.md](ARCHITECTURE.md))
|
||||||
4. Documentation and tutorials
|
5. Design pattern library contributions
|
||||||
5. Bug reports with reproductions
|
|
||||||
|
|
||||||
Check [CONTRIBUTING.md](../CONTRIBUTING.md) for details.
|
Check [CONTRIBUTING.md](../CONTRIBUTING.md) for details.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Last Updated:** 2025-11-30
|
*Maintained by: KiCAD MCP Team and community contributors*
|
||||||
**Maintained by:** KiCAD MCP Team
|
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
This document describes the router pattern implementation for the KiCAD MCP Server. The router reduces context window consumption from ~40K tokens (59 tools) to ~12K tokens (16 visible tools).
|
This document describes the router pattern implementation for the KiCAD MCP Server. The router reduces context window consumption by organizing 122+ tools into 8 discoverable categories, keeping only the most frequently used tools directly visible.
|
||||||
|
|
||||||
## Architecture Layers
|
## Architecture Layers
|
||||||
|
|
||||||
@@ -29,14 +29,14 @@ This document describes the router pattern implementation for the KiCAD MCP Serv
|
|||||||
│ │ │
|
│ │ │
|
||||||
│ ▼ │
|
│ ▼ │
|
||||||
│ ┌─────────────────────────────────────────────────────────┐│
|
│ ┌─────────────────────────────────────────────────────────┐│
|
||||||
│ │ ROUTED TOOLS (Hidden - 47) ││
|
│ │ ROUTED TOOLS (Hidden - 110+) ││
|
||||||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
|
||||||
│ │ │ board │ │component │ │ export │ │ drc │ ││
|
│ │ │ board │ │component │ │ export │ │ drc │ ││
|
||||||
│ │ │(9 tools) │ │(8 tools) │ │(8 tools) │ │(9 tools) │ ││
|
│ │ │ tools │ │ tools │ │ tools │ │ tools │ ││
|
||||||
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││
|
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││
|
||||||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
|
||||||
│ │ │schematic │ │ library │ │ routing │ ┌──────────┐ ││
|
│ │ │schematic │ │ library │ │ routing │ │footprint │ ││
|
||||||
│ │ │(9 tools) │ │(4 tools) │ │(3 tools) │ │ui (1 tool)│ ││
|
│ │ │ tools │ │ tools │ │ tools │ │ tools │ ││
|
||||||
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││
|
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││
|
||||||
│ └─────────────────────────────────────────────────────────┘│
|
│ └─────────────────────────────────────────────────────────┘│
|
||||||
└─────────────────────────────────────────────────────────────┘
|
└─────────────────────────────────────────────────────────────┘
|
||||||
@@ -68,7 +68,7 @@ These cover the primary workflow (80%+ of use cases):
|
|||||||
4. **UI Management** (1):
|
4. **UI Management** (1):
|
||||||
- `check_kicad_ui` - Check if KiCAD UI is running
|
- `check_kicad_ui` - Check if KiCAD UI is running
|
||||||
|
|
||||||
### Routed Categories (7 categories, 47 tools)
|
### Routed Categories (8+ categories, 110+ tools)
|
||||||
|
|
||||||
#### 1. `board` - Board Configuration & Layout (9 tools)
|
#### 1. `board` - Board Configuration & Layout (9 tools)
|
||||||
Setup and configuration operations.
|
Setup and configuration operations.
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
## What is the Router?
|
## What is the Router?
|
||||||
|
|
||||||
The KiCAD MCP Server now includes an intelligent tool router that organizes 59 tools into 7 discoverable categories. This reduces AI context usage by up to 70% while maintaining full access to all functionality.
|
The KiCAD MCP Server includes an intelligent tool router that organizes 122+ tools into 8 discoverable categories. This reduces AI context usage by up to 70% while maintaining full access to all functionality.
|
||||||
|
|
||||||
## How It Works
|
## How It Works
|
||||||
|
|
||||||
@@ -20,7 +20,7 @@ When you ask Claude to do something (like "export gerber files"), it will:
|
|||||||
|
|
||||||
## Tool Categories
|
## Tool Categories
|
||||||
|
|
||||||
The 47 routed tools are organized into these categories:
|
The 110+ routed tools are organized into these categories:
|
||||||
|
|
||||||
### 1. board (9 tools)
|
### 1. board (9 tools)
|
||||||
Board configuration: layers, mounting holes, zones, visualization
|
Board configuration: layers, mounting holes, zones, visualization
|
||||||
@@ -154,15 +154,12 @@ For implementation details, see:
|
|||||||
## Token Savings
|
## Token Savings
|
||||||
|
|
||||||
**Before Router:**
|
**Before Router:**
|
||||||
- 59 tools × ~700 tokens each = ~42K tokens per conversation
|
- 122 tools × ~700 tokens each = ~85K tokens per conversation
|
||||||
|
|
||||||
**After Router (Current - Phase 1):**
|
**After Router (Current):**
|
||||||
- 12 direct tools + 4 router tools = 16 tools visible
|
- 12 direct tools + 4 router tools = 16 tools visible
|
||||||
- Still ~42K tokens (all tools still registered for backwards compatibility)
|
- Routed tools discovered on-demand
|
||||||
|
- ~12-15K tokens per conversation
|
||||||
|
- **~80% reduction** in context usage
|
||||||
|
|
||||||
**After Phase 2 (Optional Optimization):**
|
The router pattern is complete and functional, providing efficient tool discovery while maintaining full access to all 122+ tools.
|
||||||
- Only 16 tools visible to Claude
|
|
||||||
- ~12K tokens per conversation
|
|
||||||
- **70% reduction** in context usage
|
|
||||||
|
|
||||||
Phase 1 is complete and functional. Phase 2 (hiding routed tools) is optional and can be implemented when desired.
|
|
||||||
|
|||||||
530
docs/ROUTING_TOOLS_REFERENCE.md
Normal file
530
docs/ROUTING_TOOLS_REFERENCE.md
Normal file
@@ -0,0 +1,530 @@
|
|||||||
|
# Routing Tools Reference
|
||||||
|
|
||||||
|
Added in: v1.0.0, major expansion in v2.2.0-v2.2.3 (PR #44, @Kletternaut)
|
||||||
|
|
||||||
|
This document provides comprehensive documentation for the 13 routing tools available in the KiCAD MCP Server. These tools cover basic trace routing, advanced operations like differential pairs, net management, trace operations, and copper zone management.
|
||||||
|
|
||||||
|
## Basic Routing (3 tools)
|
||||||
|
|
||||||
|
### add_net
|
||||||
|
|
||||||
|
Create a new net on the PCB.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| name | string | Yes | Net name |
|
||||||
|
| netClass | string | No | Net class name |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- Creates a new net that can be assigned to traces and pads
|
||||||
|
- If the net already exists, it will be reused
|
||||||
|
- Net class assignment is optional; defaults to "Default" if not specified
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "VCC_3V3",
|
||||||
|
"netClass": "Power"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### route_trace
|
||||||
|
|
||||||
|
Route a trace segment between two XY points on a fixed layer.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| start | object | Yes | Start position with x, y, and optional unit |
|
||||||
|
| end | object | Yes | End position with x, y, and optional unit |
|
||||||
|
| layer | string | Yes | PCB layer |
|
||||||
|
| width | number | Yes | Trace width in mm |
|
||||||
|
| net | string | Yes | Net name |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- WARNING: Does NOT handle layer changes
|
||||||
|
- If start and end are on different copper layers, use `route_pad_to_pad` instead, which automatically inserts a via
|
||||||
|
- Coordinates use mm by default unless unit is specified
|
||||||
|
- This is a low-level tool; prefer `route_pad_to_pad` for component-to-component routing
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"start": {"x": 100.0, "y": 50.0, "unit": "mm"},
|
||||||
|
"end": {"x": 120.0, "y": 50.0, "unit": "mm"},
|
||||||
|
"layer": "F.Cu",
|
||||||
|
"width": 0.25,
|
||||||
|
"net": "GND"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### route_pad_to_pad
|
||||||
|
|
||||||
|
PREFERRED tool for pad-to-pad routing. Looks up pad positions automatically, detects the net from the pad, and automatically inserts a via if the two pads are on different copper layers.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| fromRef | string | Yes | Reference of the source component (e.g. 'U2') |
|
||||||
|
| fromPad | string/number | Yes | Pad number on the source component (e.g. '6' or 6) |
|
||||||
|
| toRef | string | Yes | Reference of the target component (e.g. 'U1') |
|
||||||
|
| toPad | string/number | Yes | Pad number on the target component (e.g. '15' or 15) |
|
||||||
|
| layer | string | No | PCB layer (default: F.Cu) |
|
||||||
|
| width | number | No | Trace width in mm (default: board default) |
|
||||||
|
| net | string | No | Net name override (default: auto-detected from pad) |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- This is the PREFERRED tool for routing between component pads
|
||||||
|
- Automatically looks up pad positions - no need to query them separately
|
||||||
|
- Auto-detects the net from the source pad
|
||||||
|
- Critically: if pads are on different copper layers (e.g., one on F.Cu and one on B.Cu), automatically inserts a via at an appropriate position to complete the connection
|
||||||
|
- Always use this instead of `route_trace` when routing between named component pads
|
||||||
|
- Via is placed at the start pad's X coordinate to avoid stacking issues with back-to-back mirrored connectors
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"fromRef": "U2",
|
||||||
|
"fromPad": "6",
|
||||||
|
"toRef": "U1",
|
||||||
|
"toPad": "15",
|
||||||
|
"width": 0.25
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Vias (1 tool)
|
||||||
|
|
||||||
|
### add_via
|
||||||
|
|
||||||
|
Add a via to the PCB.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| position | object | Yes | Via position with x, y, and optional unit |
|
||||||
|
| net | string | Yes | Net name |
|
||||||
|
| viaType | string | No | Via type: "through", "blind", or "buried" |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- Through vias connect all layers (default)
|
||||||
|
- Blind vias connect an outer layer to one or more inner layers
|
||||||
|
- Buried vias connect two or more inner layers without reaching outer layers
|
||||||
|
- Position coordinates use mm by default
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"position": {"x": 110.0, "y": 50.0, "unit": "mm"},
|
||||||
|
"net": "GND",
|
||||||
|
"viaType": "through"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Advanced Routing (2 tools)
|
||||||
|
|
||||||
|
### route_differential_pair
|
||||||
|
|
||||||
|
Route a differential pair between two sets of points.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| positivePad | object | Yes | Positive pad with reference and pad number |
|
||||||
|
| negativePad | object | Yes | Negative pad with reference and pad number |
|
||||||
|
| layer | string | Yes | PCB layer |
|
||||||
|
| width | number | Yes | Trace width in mm |
|
||||||
|
| gap | number | Yes | Gap between traces in mm |
|
||||||
|
| positiveNet | string | Yes | Positive net name |
|
||||||
|
| negativeNet | string | Yes | Negative net name |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- Used for high-speed signals like USB, Ethernet, HDMI, etc.
|
||||||
|
- Maintains controlled impedance through consistent trace width and gap
|
||||||
|
- Both traces are routed in parallel with specified separation
|
||||||
|
- Pad object format: `{"reference": "U1", "pad": "1"}`
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"positivePad": {"reference": "J1", "pad": "2"},
|
||||||
|
"negativePad": {"reference": "J1", "pad": "3"},
|
||||||
|
"layer": "F.Cu",
|
||||||
|
"width": 0.2,
|
||||||
|
"gap": 0.2,
|
||||||
|
"positiveNet": "USB_DP",
|
||||||
|
"negativeNet": "USB_DN"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### copy_routing_pattern
|
||||||
|
|
||||||
|
Copy routing pattern (traces and vias) from a group of source components to a matching group of target components.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| sourceRefs | array[string] | Yes | References of the source components (e.g. ['U1', 'R1', 'C1']) |
|
||||||
|
| targetRefs | array[string] | Yes | References of the target components in same order as sourceRefs (e.g. ['U2', 'R2', 'C2']) |
|
||||||
|
| includeVias | boolean | No | Also copy vias (default: true) |
|
||||||
|
| traceWidth | number | No | Override trace width in mm (default: keep original width) |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- The offset is calculated automatically from the position difference between the first source and first target component
|
||||||
|
- Useful for replicating routing between identical circuit blocks
|
||||||
|
- Component arrays must be in matching order (sourceRefs[0] maps to targetRefs[0], etc.)
|
||||||
|
- Preserves relative routing topology from source to target
|
||||||
|
- Vias are copied by default unless includeVias is set to false
|
||||||
|
- Original trace widths are preserved unless traceWidth override is specified
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"sourceRefs": ["U1", "R1", "C1"],
|
||||||
|
"targetRefs": ["U2", "R2", "C2"],
|
||||||
|
"includeVias": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Net Management (2 tools)
|
||||||
|
|
||||||
|
### get_nets_list
|
||||||
|
|
||||||
|
Get a list of all nets in the PCB with optional statistics.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| includeStats | boolean | No | Include statistics (track count, total length, etc.) |
|
||||||
|
| unit | string | No | Unit for length measurements: "mm" or "inch" |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- Returns all nets present in the board
|
||||||
|
- Statistics include track count, via count, and total trace length
|
||||||
|
- Useful for verifying net connectivity and routing completeness
|
||||||
|
- Length measurements default to mm
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"includeStats": true,
|
||||||
|
"unit": "mm"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### create_netclass
|
||||||
|
|
||||||
|
Create a new net class with custom design rules.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| name | string | Yes | Net class name |
|
||||||
|
| traceWidth | number | No | Default trace width in mm |
|
||||||
|
| clearance | number | No | Clearance in mm |
|
||||||
|
| viaDiameter | number | No | Via diameter in mm |
|
||||||
|
| viaDrill | number | No | Via drill size in mm |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- Net classes define design rules for groups of nets
|
||||||
|
- Common use cases: power nets (wider traces), high-speed signals (controlled impedance)
|
||||||
|
- Once created, assign nets to the class using the netClass parameter in `add_net`
|
||||||
|
- All measurements in mm
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "Power",
|
||||||
|
"traceWidth": 0.5,
|
||||||
|
"clearance": 0.3,
|
||||||
|
"viaDiameter": 0.8,
|
||||||
|
"viaDrill": 0.4
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Trace Operations (3 tools)
|
||||||
|
|
||||||
|
### delete_trace
|
||||||
|
|
||||||
|
Delete traces from the PCB. Can delete by UUID, position, or bulk-delete all traces on a net.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| traceUuid | string | No | UUID of a specific trace to delete |
|
||||||
|
| position | object | No | Delete trace nearest to this position (x, y, optional unit) |
|
||||||
|
| net | string | No | Delete all traces on this net (bulk delete) |
|
||||||
|
| layer | string | No | Filter by layer when using net-based deletion |
|
||||||
|
| includeVias | boolean | No | Include vias in net-based deletion |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- Three deletion modes: by UUID (specific), by position (nearest), or by net (bulk)
|
||||||
|
- Position-based deletion finds the closest trace to the specified coordinates
|
||||||
|
- Net-based deletion can be filtered by layer
|
||||||
|
- Vias are excluded from net-based deletion by default unless includeVias is true
|
||||||
|
|
||||||
|
**Example (bulk delete):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"net": "GND",
|
||||||
|
"layer": "F.Cu",
|
||||||
|
"includeVias": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### query_traces
|
||||||
|
|
||||||
|
Query traces on the board with optional filters by net, layer, or bounding box.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| net | string | No | Filter by net name |
|
||||||
|
| layer | string | No | Filter by layer name |
|
||||||
|
| boundingBox | object | No | Filter by bounding box region (x1, y1, x2, y2, optional unit) |
|
||||||
|
| unit | string | No | Unit for coordinates: "mm" or "inch" |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- Returns trace information including UUID, position, width, layer, and net
|
||||||
|
- Filters can be combined (e.g., specific net on specific layer)
|
||||||
|
- Bounding box uses rectangular region defined by opposite corners
|
||||||
|
- Useful for analyzing routing in specific board regions or on specific nets
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"net": "VCC_3V3",
|
||||||
|
"layer": "F.Cu"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### modify_trace
|
||||||
|
|
||||||
|
Modify an existing trace (change width, layer, or net).
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| traceUuid | string | Yes | UUID of the trace to modify |
|
||||||
|
| width | number | No | New trace width in mm |
|
||||||
|
| layer | string | No | New layer name |
|
||||||
|
| net | string | No | New net name |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- Requires the trace UUID, which can be obtained from `query_traces`
|
||||||
|
- At least one modification parameter (width, layer, or net) must be provided
|
||||||
|
- Use with caution when changing nets - ensure electrical correctness
|
||||||
|
- Width changes are useful for adjusting impedance or current capacity
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"traceUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
|
||||||
|
"width": 0.5
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Copper Zones (2 tools)
|
||||||
|
|
||||||
|
### add_copper_pour
|
||||||
|
|
||||||
|
Add a copper pour (ground/power plane) to the PCB.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| layer | string | Yes | PCB layer |
|
||||||
|
| net | string | Yes | Net name |
|
||||||
|
| clearance | number | No | Clearance in mm |
|
||||||
|
| outline | array[object] | No | Array of {x, y} points defining the pour boundary. If omitted, the board outline is used. |
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- Copper pours are typically used for ground and power planes
|
||||||
|
- If no outline is specified, the pour fills the entire board area
|
||||||
|
- Custom outlines are defined as arrays of coordinate points
|
||||||
|
- Clearance defines the minimum distance from other copper features
|
||||||
|
- After adding a pour, use `refill_zones` to fill it
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"layer": "B.Cu",
|
||||||
|
"net": "GND",
|
||||||
|
"clearance": 0.2,
|
||||||
|
"outline": [
|
||||||
|
{"x": 10.0, "y": 10.0},
|
||||||
|
{"x": 90.0, "y": 10.0},
|
||||||
|
{"x": 90.0, "y": 60.0},
|
||||||
|
{"x": 10.0, "y": 60.0}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### refill_zones
|
||||||
|
|
||||||
|
Refill all copper zones on the board.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
**Usage Notes:**
|
||||||
|
- WARNING: SWIG path has known segfault risk (see KNOWN_ISSUES.md)
|
||||||
|
- Prefer using IPC backend (KiCAD open) or triggering zone fill via KiCAD UI instead
|
||||||
|
- Required after adding or modifying copper pours to calculate the filled areas
|
||||||
|
- Recalculates all zone fills based on current board state
|
||||||
|
- May take several seconds on complex boards with many zones
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example Workflows
|
||||||
|
|
||||||
|
### Point-to-Point Routing with route_pad_to_pad
|
||||||
|
|
||||||
|
The simplest and most robust approach for connecting component pads:
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Connect pin 1 of U1 to pin 5 of R1
|
||||||
|
{
|
||||||
|
"tool": "route_pad_to_pad",
|
||||||
|
"params": {
|
||||||
|
"fromRef": "U1",
|
||||||
|
"fromPad": "1",
|
||||||
|
"toRef": "R1",
|
||||||
|
"toPad": "5",
|
||||||
|
"width": 0.25
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This automatically:
|
||||||
|
- Looks up the exact pad positions
|
||||||
|
- Detects the net from the pads
|
||||||
|
- Creates the trace on the appropriate layer
|
||||||
|
- Inserts a via if the pads are on different copper layers
|
||||||
|
|
||||||
|
### Differential Pair Routing (USB, Ethernet)
|
||||||
|
|
||||||
|
For high-speed differential signals like USB D+ and D-:
|
||||||
|
|
||||||
|
```json
|
||||||
|
// 1. Create nets if needed
|
||||||
|
{
|
||||||
|
"tool": "add_net",
|
||||||
|
"params": {"name": "USB_DP"}
|
||||||
|
}
|
||||||
|
{
|
||||||
|
"tool": "add_net",
|
||||||
|
"params": {"name": "USB_DN"}
|
||||||
|
}
|
||||||
|
|
||||||
|
// 2. Route the differential pair
|
||||||
|
{
|
||||||
|
"tool": "route_differential_pair",
|
||||||
|
"params": {
|
||||||
|
"positivePad": {"reference": "U1", "pad": "14"},
|
||||||
|
"negativePad": {"reference": "U1", "pad": "15"},
|
||||||
|
"layer": "F.Cu",
|
||||||
|
"width": 0.2,
|
||||||
|
"gap": 0.2,
|
||||||
|
"positiveNet": "USB_DP",
|
||||||
|
"negativeNet": "USB_DN"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Replicating Routing Patterns
|
||||||
|
|
||||||
|
For repeated circuit blocks (e.g., multiple identical LED drivers):
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Route the first instance (U1, R1, C1) manually, then copy to others
|
||||||
|
{
|
||||||
|
"tool": "copy_routing_pattern",
|
||||||
|
"params": {
|
||||||
|
"sourceRefs": ["U1", "R1", "C1"],
|
||||||
|
"targetRefs": ["U2", "R2", "C2"],
|
||||||
|
"includeVias": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Copy the same pattern to a third instance
|
||||||
|
{
|
||||||
|
"tool": "copy_routing_pattern",
|
||||||
|
"params": {
|
||||||
|
"sourceRefs": ["U1", "R1", "C1"],
|
||||||
|
"targetRefs": ["U3", "R3", "C3"],
|
||||||
|
"includeVias": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Adding a Ground Plane
|
||||||
|
|
||||||
|
```json
|
||||||
|
// 1. Create the copper pour on bottom layer
|
||||||
|
{
|
||||||
|
"tool": "add_copper_pour",
|
||||||
|
"params": {
|
||||||
|
"layer": "B.Cu",
|
||||||
|
"net": "GND",
|
||||||
|
"clearance": 0.2
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// 2. Fill the zones
|
||||||
|
{
|
||||||
|
"tool": "refill_zones",
|
||||||
|
"params": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Note: Use the IPC backend (keep KiCAD open) when using refill_zones to avoid potential segfaults with the SWIG backend.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Source Files
|
||||||
|
|
||||||
|
- **TypeScript Tool Definitions**: `/home/chris/MCP/KiCAD-MCP-Server/src/tools/routing.ts`
|
||||||
|
- **Python Implementation**: `/home/chris/MCP/KiCAD-MCP-Server/python/commands/routing.py`
|
||||||
303
docs/SCHEMATIC_TOOLS_REFERENCE.md
Normal file
303
docs/SCHEMATIC_TOOLS_REFERENCE.md
Normal file
@@ -0,0 +1,303 @@
|
|||||||
|
# Schematic Tools Reference
|
||||||
|
|
||||||
|
Added in: v2.1.0, expanded in v2.2.0-v2.2.3
|
||||||
|
Contributors: @Mehanik (PRs #60, #66), @Kletternaut (PR #57)
|
||||||
|
|
||||||
|
This document provides a complete reference for the 27 schematic tools in the KiCAD MCP Server. These tools enable a complete schematic design workflow, from creating projects and adding components to wiring, validation, and synchronization with PCB boards. The dynamic symbol loading feature provides access to approximately 10,000 standard KiCad symbols.
|
||||||
|
|
||||||
|
## Component Operations (8 tools)
|
||||||
|
|
||||||
|
### add_schematic_component
|
||||||
|
Add a component to the schematic. Symbol format is 'Library:SymbolName' (e.g., 'Device:R', 'EDA-MCP:ESP32-C3').
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the schematic file |
|
||||||
|
| symbol | string | Yes | Symbol library:name reference (e.g., Device:R, EDA-MCP:ESP32-C3) |
|
||||||
|
| reference | string | Yes | Component reference (e.g., R1, U1) |
|
||||||
|
| value | string | No | Component value |
|
||||||
|
| footprint | string | No | KiCAD footprint (e.g. Resistor_SMD:R_0603_1608Metric) |
|
||||||
|
| position | object | No | Position on schematic with x and y coordinates |
|
||||||
|
|
||||||
|
**Usage Notes:** The dynamic symbol loader provides access to ~10,000 KiCad standard symbols. If a symbol is not in the static template map, it will be loaded dynamically from the specified library.
|
||||||
|
|
||||||
|
### delete_schematic_component
|
||||||
|
Remove a placed symbol from a KiCAD schematic (.kicad_sch). This removes the symbol instance (the placed component) from the schematic. It does NOT remove the symbol definition from lib_symbols. Note: This tool operates on schematic files (.kicad_sch). To remove a footprint from a PCB, use delete_component instead.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| reference | string | Yes | Reference designator of the component to remove (e.g. R1, U3) |
|
||||||
|
|
||||||
|
### edit_schematic_component
|
||||||
|
Update properties of a placed symbol in a KiCAD schematic (.kicad_sch) in-place. Use this tool to assign or update a footprint, change the value, or rename the reference of an already-placed component. This is more efficient than delete + re-add because it preserves the component's position and UUID. Note: operates on .kicad_sch files only. To modify a PCB footprint use edit_component.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| reference | string | Yes | Current reference designator of the component (e.g. R1, U3) |
|
||||||
|
| footprint | string | No | New KiCAD footprint string (e.g. Resistor_SMD:R_0603_1608Metric) |
|
||||||
|
| value | string | No | New value string (e.g. 10k, 100nF) |
|
||||||
|
| newReference | string | No | Rename the reference designator (e.g. R1 → R10) |
|
||||||
|
| fieldPositions | object | No | Reposition field labels: map of field name to {x, y, angle} (e.g. {"Reference": {"x": 12.5, "y": 17.0}}) |
|
||||||
|
|
||||||
|
### get_schematic_component
|
||||||
|
Get full component info from a schematic: position, field values, and each field's label position (at x/y/angle). Use this to inspect or prepare repositioning of Reference/Value labels.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| reference | string | Yes | Component reference designator (e.g. R1, U1) |
|
||||||
|
|
||||||
|
### list_schematic_components
|
||||||
|
List all components in a schematic with their references, values, positions, and pins. Essential for inspecting what's on the schematic before making edits.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| filter | object | No | Optional filters with libId and/or referencePrefix fields |
|
||||||
|
| filter.libId | string | No | Filter by library ID (e.g., 'Device:R') |
|
||||||
|
| filter.referencePrefix | string | No | Filter by reference prefix (e.g., 'R', 'C', 'U') |
|
||||||
|
|
||||||
|
### move_schematic_component
|
||||||
|
Move a placed symbol to a new position in the schematic.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| reference | string | Yes | Reference designator (e.g., R1, U1) |
|
||||||
|
| position | object | Yes | New position with x and y coordinates |
|
||||||
|
|
||||||
|
### rotate_schematic_component
|
||||||
|
Rotate a placed symbol in the schematic.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| reference | string | Yes | Reference designator (e.g., R1, U1) |
|
||||||
|
| angle | number | Yes | Rotation angle in degrees (0, 90, 180, 270) |
|
||||||
|
| mirror | enum | No | Optional mirror axis ("x" or "y") |
|
||||||
|
|
||||||
|
### annotate_schematic
|
||||||
|
Assign reference designators to unannotated components (R? → R1, R2, ...). Must be called before tools that require known references.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
|
||||||
|
## Wiring and Connections (8 tools)
|
||||||
|
|
||||||
|
### add_wire
|
||||||
|
Add a wire connection in the schematic.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| start | object | Yes | Start position with x and y coordinates |
|
||||||
|
| end | object | Yes | End position with x and y coordinates |
|
||||||
|
|
||||||
|
### add_schematic_connection
|
||||||
|
Connect two component pins with a wire. Use this for individual connections between components with different pin roles (e.g. U1.SDA → J3.2). WARNING: Do NOT use this in a loop to wire N passthrough pins — use connect_passthrough instead (single call, cleaner layout, far fewer tokens).
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the schematic file |
|
||||||
|
| sourceRef | string | Yes | Source component reference (e.g., R1) |
|
||||||
|
| sourcePin | string | Yes | Source pin name/number (e.g., 1, 2, GND) |
|
||||||
|
| targetRef | string | Yes | Target component reference (e.g., C1) |
|
||||||
|
| targetPin | string | Yes | Target pin name/number (e.g., 1, 2, VCC) |
|
||||||
|
|
||||||
|
### add_schematic_net_label
|
||||||
|
Add a net label to the schematic.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the schematic file |
|
||||||
|
| netName | string | Yes | Name of the net (e.g., VCC, GND, SIGNAL_1) |
|
||||||
|
| position | array | Yes | Position [x, y] for the label |
|
||||||
|
|
||||||
|
### connect_to_net
|
||||||
|
Connect a component pin to a named net.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the schematic file |
|
||||||
|
| componentRef | string | Yes | Component reference (e.g., U1, R1) |
|
||||||
|
| pinName | string | Yes | Pin name/number to connect |
|
||||||
|
| netName | string | Yes | Name of the net to connect to |
|
||||||
|
|
||||||
|
**Usage Notes:** Creates a wire stub from the pin and places a net label at the stub endpoint. The stub direction follows the pin's outward angle. Default stub length is 2.54mm (0.1 inch, standard grid spacing).
|
||||||
|
|
||||||
|
### connect_passthrough
|
||||||
|
Connects all pins of a source connector (e.g. J1) to matching pins of a target connector (e.g. J2) via shared net labels — pin N gets net '{netPrefix}_{N}'. Use this for FFC/ribbon cable passthrough adapters instead of calling connect_to_net for every pin.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the schematic file |
|
||||||
|
| sourceRef | string | Yes | Source connector reference (e.g. J1) |
|
||||||
|
| targetRef | string | Yes | Target connector reference (e.g. J2) |
|
||||||
|
| netPrefix | string | No | Net name prefix, e.g. 'CSI' → CSI_1, CSI_2 (default: PIN) |
|
||||||
|
| pinOffset | number | No | Add to pin number when building net name (default: 0) |
|
||||||
|
|
||||||
|
**Usage Notes:** This is the most efficient way to wire passthrough adapters. For an N-pin connector, this replaces N individual connect_to_net calls with a single operation.
|
||||||
|
|
||||||
|
### get_schematic_pin_locations
|
||||||
|
Returns the exact x/y coordinates of every pin on a schematic component. Use this before add_schematic_net_label to place labels correctly on pin endpoints.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the schematic file |
|
||||||
|
| reference | string | Yes | Component reference designator (e.g. U1, R1, J2) |
|
||||||
|
|
||||||
|
### delete_schematic_wire
|
||||||
|
Remove a wire from the schematic by start and end coordinates.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| start | object | Yes | Wire start position with x and y coordinates |
|
||||||
|
| end | object | Yes | Wire end position with x and y coordinates |
|
||||||
|
|
||||||
|
### delete_schematic_net_label
|
||||||
|
Remove a net label from the schematic.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| netName | string | Yes | Name of the net label to remove |
|
||||||
|
| position | object | No | Position to disambiguate if multiple labels with same name (x and y coordinates) |
|
||||||
|
|
||||||
|
## Net Analysis (4 tools)
|
||||||
|
|
||||||
|
### get_net_connections
|
||||||
|
Get all connections for a named net.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the schematic file |
|
||||||
|
| netName | string | Yes | Name of the net to query |
|
||||||
|
|
||||||
|
**Usage Notes:** Uses wire graph analysis to find all component pins connected to the specified net. Returns a list of {component, pin} pairs.
|
||||||
|
|
||||||
|
### list_schematic_nets
|
||||||
|
List all nets in the schematic with their connections.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
|
||||||
|
### list_schematic_wires
|
||||||
|
List all wires in the schematic with start/end coordinates.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
|
||||||
|
### list_schematic_labels
|
||||||
|
List all net labels, global labels, and power flags in the schematic.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
|
||||||
|
## Schematic Creation and Export (5 tools)
|
||||||
|
|
||||||
|
### create_schematic
|
||||||
|
Create a new schematic.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| name | string | Yes | Schematic name |
|
||||||
|
| path | string | No | Optional path |
|
||||||
|
|
||||||
|
### export_schematic_svg
|
||||||
|
Export schematic to SVG format using kicad-cli.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| outputPath | string | Yes | Output SVG file path |
|
||||||
|
| blackAndWhite | boolean | No | Export in black and white |
|
||||||
|
|
||||||
|
### export_schematic_pdf
|
||||||
|
Export schematic to PDF format using kicad-cli.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| outputPath | string | Yes | Output PDF file path |
|
||||||
|
| blackAndWhite | boolean | No | Export in black and white |
|
||||||
|
|
||||||
|
### get_schematic_view
|
||||||
|
Return a rasterized image of the schematic (PNG by default, or SVG). Uses kicad-cli to export SVG, then converts to PNG via cairosvg. Use this for visual feedback after placing or wiring components.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch file |
|
||||||
|
| format | enum | No | Output format ("png" or "svg", default: png) |
|
||||||
|
| width | number | No | Image width in pixels (default: 1200) |
|
||||||
|
| height | number | No | Image height in pixels (default: 900) |
|
||||||
|
|
||||||
|
### generate_netlist
|
||||||
|
Generate a netlist from the schematic.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the schematic file |
|
||||||
|
|
||||||
|
**Usage Notes:** Returns a complete netlist with component information (reference, value, footprint) and net connections (net name with all connected component/pin pairs).
|
||||||
|
|
||||||
|
## Validation and Synchronization (3 tools)
|
||||||
|
|
||||||
|
### run_erc
|
||||||
|
Runs the KiCAD Electrical Rules Check (ERC) on a schematic and returns all violations. Use after wiring to verify the schematic before generating a netlist.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Path to the .kicad_sch schematic file |
|
||||||
|
|
||||||
|
**Usage Notes:** Returns violations categorized by severity (error, warning, info) with location coordinates. Essential for catching design errors before PCB layout.
|
||||||
|
|
||||||
|
### sync_schematic_to_board
|
||||||
|
Import the schematic netlist into the PCB board — equivalent to pressing F8 in KiCAD (Tools → Update PCB from Schematic). MUST be called after the schematic is complete and before placing or routing components on the PCB. Without this step, the board has no footprints and no net assignments — place_component and route_pad_to_pad will produce an empty, unroutable board.
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Description |
|
||||||
|
|-----------|------|----------|-------------|
|
||||||
|
| schematicPath | string | Yes | Absolute path to the .kicad_sch schematic file |
|
||||||
|
| boardPath | string | Yes | Absolute path to the .kicad_pcb board file |
|
||||||
|
|
||||||
|
**Usage Notes:** This is the F8 equivalent. It synchronizes the schematic design to the PCB, creating footprints on the board and assigning nets. This step is critical in the workflow: design in schematic → sync_schematic_to_board → place and route on PCB.
|
||||||
|
|
||||||
|
## Example Workflows
|
||||||
|
|
||||||
|
### Basic Circuit Design
|
||||||
|
1. **Create project:** Use `create_schematic` to initialize a new schematic file
|
||||||
|
2. **Add components:** Use `add_schematic_component` to place resistors, capacitors, ICs, etc.
|
||||||
|
- Example: Add a resistor with `symbol: "Device:R"`, `reference: "R1"`, `value: "10k"`
|
||||||
|
3. **Wire components:** Use `add_schematic_connection` to connect component pins
|
||||||
|
- Or use `connect_to_net` to connect pins to named nets (VCC, GND, etc.)
|
||||||
|
4. **Add net labels:** Use `add_schematic_net_label` to label important signals
|
||||||
|
5. **Validate:** Run `run_erc` to check for electrical rule violations
|
||||||
|
6. **Review:** Use `list_schematic_components` and `get_schematic_view` to verify the design
|
||||||
|
7. **Sync to PCB:** Use `sync_schematic_to_board` to transfer the design to the PCB layout
|
||||||
|
|
||||||
|
### FFC Passthrough Adapter
|
||||||
|
1. **Add connectors:** Place two FFC connectors using `add_schematic_component`
|
||||||
|
- Example: J1 and J2, both 20-pin FFC connectors
|
||||||
|
2. **Connect passthrough:** Use `connect_passthrough` with `sourceRef: "J1"`, `targetRef: "J2"`, `netPrefix: "CSI"`
|
||||||
|
- This single call connects all 20 pins (J1.1 ↔ J2.1 via CSI_1, J1.2 ↔ J2.2 via CSI_2, etc.)
|
||||||
|
3. **Sync to board:** Use `sync_schematic_to_board` to create the PCB layout
|
||||||
|
4. **Verify:** Use `list_schematic_nets` to confirm all connections are correct
|
||||||
|
|
||||||
|
## Source Files
|
||||||
|
|
||||||
|
The schematic tools are implemented across the following source files:
|
||||||
|
|
||||||
|
- **TypeScript (Tool Definitions):**
|
||||||
|
- `/home/chris/MCP/KiCAD-MCP-Server/src/tools/schematic.ts` - All 27 schematic tool definitions with parameter schemas and handlers
|
||||||
|
|
||||||
|
- **Python (Backend Implementation):**
|
||||||
|
- `/home/chris/MCP/KiCAD-MCP-Server/python/commands/component_schematic.py` - ComponentManager class (add, delete, edit, list components with dynamic symbol loading)
|
||||||
|
- `/home/chris/MCP/KiCAD-MCP-Server/python/commands/connection_schematic.py` - ConnectionManager class (wiring, net labels, passthrough, netlist generation)
|
||||||
|
- `/home/chris/MCP/KiCAD-MCP-Server/python/commands/wire_manager.py` - WireManager class (low-level wire manipulation)
|
||||||
|
- `/home/chris/MCP/KiCAD-MCP-Server/python/commands/pin_locator.py` - PinLocator class (pin location lookup and angle calculation)
|
||||||
|
- `/home/chris/MCP/KiCAD-MCP-Server/python/commands/dynamic_symbol_loader.py` - DynamicSymbolLoader class (runtime symbol loading from KiCad libraries)
|
||||||
@@ -1,223 +1,88 @@
|
|||||||
# KiCAD MCP - Current Status Summary
|
# KiCAD MCP - Current Status Summary
|
||||||
|
|
||||||
**Date:** 2025-12-02
|
**Date:** 2026-03-21
|
||||||
**Version:** 2.1.0-alpha
|
**Version:** 2.2.3 (package.json shows 2.1.0-alpha -- CHANGELOG is authoritative)
|
||||||
**Phase:** IPC Backend Implementation and Testing
|
**Phase:** Active development with community contributions
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Quick Stats
|
## Quick Stats
|
||||||
|
|
||||||
| Metric | Value | Status |
|
| Metric | Value |
|
||||||
|--------|-------|--------|
|
|--------|-------|
|
||||||
| Core Features Working | 18/20 | 90% |
|
| Total MCP Tools | 122 |
|
||||||
| KiCAD 9.0 Compatible | Yes | Verified |
|
| Tool Categories | 16 |
|
||||||
| UI Auto-launch | Working | Verified |
|
| KiCAD 9.0 Compatible | Yes (verified) |
|
||||||
| Component Placement | Working | Verified |
|
| Platforms | Linux, Windows, macOS |
|
||||||
| Component Libraries | 153 libraries | Verified |
|
| JLCPCB Parts Catalog | 2.5M+ components |
|
||||||
| Routing Operations | Working | Verified |
|
| Symbol Access | ~10,000 via dynamic loading |
|
||||||
| IPC Backend | Under Testing | Experimental |
|
| Footprint Libraries | 153+ auto-discovered |
|
||||||
| Tests Passing | 18/20 | 90% |
|
| Contributors | 10+ |
|
||||||
|
| MCP Protocol Version | 2025-06-18 |
|
||||||
---
|
|
||||||
|
|
||||||
## What's Working (Verified 2025-12-02)
|
|
||||||
|
|
||||||
### Project Management
|
|
||||||
- `create_project` - Create new KiCAD projects
|
|
||||||
- `open_project` - Load existing PCB files
|
|
||||||
- `save_project` - Save changes to disk
|
|
||||||
- `get_project_info` - Retrieve project metadata
|
|
||||||
|
|
||||||
### Board Design
|
|
||||||
- `set_board_size` - Set dimensions (KiCAD 9.0 fixed)
|
|
||||||
- `add_board_outline` - Rectangle, circle, polygon outlines
|
|
||||||
- `add_mounting_hole` - Mounting holes with pads
|
|
||||||
- `add_board_text` - Text annotations (KiCAD 9.0 fixed)
|
|
||||||
- `add_layer` - Custom layer creation
|
|
||||||
- `set_active_layer` - Layer switching
|
|
||||||
- `get_layer_list` - List all layers
|
|
||||||
|
|
||||||
### Component Operations
|
|
||||||
- `place_component` - Place components with library footprints (KiCAD 9.0 fixed)
|
|
||||||
- `move_component` - Move components
|
|
||||||
- `rotate_component` - Rotate components (EDA_ANGLE fixed)
|
|
||||||
- `delete_component` - Remove components
|
|
||||||
- `list_components` - Get all components on board
|
|
||||||
|
|
||||||
**Footprint Library Integration:**
|
|
||||||
- Auto-discovered 153 KiCAD footprint libraries
|
|
||||||
- Search footprints by pattern (`search_footprints`)
|
|
||||||
- List library contents (`list_library_footprints`)
|
|
||||||
- Get footprint info (`get_footprint_info`)
|
|
||||||
- Support for both `Library:Footprint` and `Footprint` formats
|
|
||||||
|
|
||||||
**KiCAD 9.0 API Fixes:**
|
|
||||||
- `SetOrientation()` uses `EDA_ANGLE(degrees, DEGREES_T)`
|
|
||||||
- `GetOrientation()` returns `EDA_ANGLE`, call `.AsDegrees()`
|
|
||||||
- `GetFootprintName()` now `GetFPIDAsString()`
|
|
||||||
|
|
||||||
### 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)
|
|
||||||
- `add_copper_pour` - Add copper zones/pours (KiCAD 9.0 fixed)
|
|
||||||
- `route_differential_pair` - Differential pair routing
|
|
||||||
|
|
||||||
**KiCAD 9.0 API Fixes:**
|
|
||||||
- `netinfo.FindNet()` now `netinfo.NetsByName()[name]`
|
|
||||||
- `zone.SetPriority()` now `zone.SetAssignedPriority()`
|
|
||||||
- `ZONE_FILL_MODE_POLYGON` now `ZONE_FILL_MODE_POLYGONS`
|
|
||||||
- Zone outline requires `outline.NewOutline()` first
|
|
||||||
|
|
||||||
### UI Management
|
|
||||||
- `check_kicad_ui` - Detect running KiCAD
|
|
||||||
- `launch_kicad_ui` - Auto-launch with project
|
|
||||||
|
|
||||||
### Export
|
|
||||||
- `export_gerber` - Manufacturing files
|
|
||||||
- `export_pdf` - Documentation
|
|
||||||
- `export_svg` - Vector graphics
|
|
||||||
- `export_3d` - STEP/VRML models
|
|
||||||
- `export_bom` - Bill of materials
|
|
||||||
|
|
||||||
### Design Rules
|
|
||||||
- `set_design_rules` - DRC configuration
|
|
||||||
- `get_design_rules` - Rule inspection
|
|
||||||
- `run_drc` - Design rule check
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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)
|
|
||||||
|
|
||||||
**1. get_board_info layer constants**
|
|
||||||
- Error: `AttributeError: 'BOARD' object has no attribute 'LT_USER'`
|
|
||||||
- Impact: Low (informational command only)
|
|
||||||
- Workaround: Use `get_project_info` or read components directly
|
|
||||||
|
|
||||||
**2. Zone filling via SWIG**
|
|
||||||
- Copper pours created but not filled automatically via SWIG
|
|
||||||
- Cause: SWIG API segfault when calling `ZONE_FILLER`
|
|
||||||
- Workaround: Use IPC backend or zones are filled when opened in KiCAD UI
|
|
||||||
|
|
||||||
**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 (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
|
|
||||||
- **Use Case:** Offline work, automated pipelines, batch operations
|
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Feature Completion Matrix
|
## Feature Completion Matrix
|
||||||
|
|
||||||
| Feature Category | Status | Details |
|
| Feature Category | Status | Tool Count | Details |
|
||||||
|-----------------|--------|---------|
|
|-----------------|--------|------------|---------|
|
||||||
| Project Management | 100% | Create, open, save, info |
|
| Project Management | Complete | 5 | Create, open, save, info, snapshot |
|
||||||
| Board Setup | 100% | Size, outline, mounting holes |
|
| Board Setup | Complete | 12 | Size, outline, layers, mounting holes, zones, text, 2D view, SVG import |
|
||||||
| Component Placement | 100% | Place, move, rotate, delete + 153 libraries |
|
| Component Placement | Complete | 16 | Place, move, rotate, delete, edit, find, pads, arrays, align, duplicate |
|
||||||
| Routing | 90% | Traces, vias, copper (zone filling via IPC) |
|
| Routing | Complete | 13 | Traces, vias, pad-to-pad, differential pairs, netclasses, copy pattern |
|
||||||
| Design Rules | 100% | Set, get, run DRC |
|
| Design Rules / DRC | Complete | 8 | Set/get rules, DRC, net classes, clearance checks |
|
||||||
| Export | 100% | Gerber, PDF, SVG, 3D, BOM |
|
| Export | Complete | 8 | Gerber, PDF, SVG, 3D, BOM, netlist, position file, VRML |
|
||||||
| UI Integration | 85% | Launch, check, IPC auto-updates |
|
| Schematic | Complete | 27 | Components, wiring, net labels, connections, ERC, export, sync to board |
|
||||||
| IPC Backend | 60% | Under testing, 21 commands implemented |
|
| Footprint Libraries | Complete | 4 | List, search, browse, info |
|
||||||
| JLCPCB Integration | 0% | Planned |
|
| Symbol Libraries | Complete | 4 | List, search, browse, info |
|
||||||
|
| Footprint Creator | Complete | 4 | Create custom footprints, edit pads, register libraries |
|
||||||
|
| Symbol Creator | Complete | 4 | Create custom symbols, register libraries |
|
||||||
|
| Datasheet Tools | Complete | 2 | LCSC datasheet enrichment |
|
||||||
|
| JLCPCB Integration | Complete | 5 | Local DB, search, part details, stats, alternatives |
|
||||||
|
| Freerouting | Complete | 4 | Autoroute, DSN export, SES import, availability check |
|
||||||
|
| UI Management | Complete | 2 | Check/launch KiCAD |
|
||||||
|
| Router Tools | Complete | 4 | Category browsing, tool search, execute |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Developer Setup Status
|
## Architecture
|
||||||
|
|
||||||
### Linux - Primary Platform
|
### SWIG Backend (File-based) -- Default
|
||||||
|
- **Status:** Stable
|
||||||
|
- Direct pcbnew API access via KiCAD's Python bindings
|
||||||
|
- Requires manual KiCAD UI reload to see changes
|
||||||
|
- Works without KiCAD running
|
||||||
|
- Auto-saves after every board-modifying command
|
||||||
|
|
||||||
|
### IPC Backend (Real-time) -- Experimental
|
||||||
|
- **Status:** Functional, 21 commands implemented
|
||||||
|
- Real-time UI synchronization with KiCAD 9+
|
||||||
|
- Requires KiCAD running with IPC API enabled
|
||||||
|
- Automatic fallback to SWIG when unavailable
|
||||||
|
|
||||||
|
### Hybrid Approach
|
||||||
|
The server automatically selects the best backend:
|
||||||
|
- IPC when KiCAD is running with IPC enabled
|
||||||
|
- SWIG fallback when IPC is unavailable
|
||||||
|
- Some operations use both (e.g., footprint placement)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Platform Support
|
||||||
|
|
||||||
|
### Linux -- Primary Platform
|
||||||
- KiCAD 9.0 detection: Working
|
- KiCAD 9.0 detection: Working
|
||||||
- Process management: Working
|
- Process management: Working
|
||||||
- venv support: Working
|
- Library discovery: Working (153+ libraries)
|
||||||
- Library discovery: Working (153 libraries)
|
- IPC backend: Working
|
||||||
- Testing: Working
|
|
||||||
- IPC backend: Under testing
|
|
||||||
|
|
||||||
### Windows - Supported
|
### Windows -- Fully Supported
|
||||||
- Automated setup script (`setup-windows.ps1`)
|
- Automated setup script (setup-windows.ps1)
|
||||||
- Process detection implemented
|
- Process detection via Toolhelp32 API
|
||||||
- Library paths auto-detected
|
- Library paths auto-detected
|
||||||
- Comprehensive error diagnostics
|
- Troubleshooting guide available (WINDOWS_TROUBLESHOOTING.md)
|
||||||
- Startup validation with helpful errors
|
|
||||||
- Troubleshooting guide (WINDOWS_TROUBLESHOOTING.md)
|
|
||||||
|
|
||||||
### macOS - Untested
|
### macOS -- Community Supported
|
||||||
- Configuration provided
|
- Configuration provided
|
||||||
- Process detection implemented
|
- Process detection implemented
|
||||||
- Library paths configured
|
- Library paths configured
|
||||||
@@ -225,44 +90,51 @@ The server automatically selects the best backend:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Documentation Status
|
## Recent Development Highlights
|
||||||
|
|
||||||
### Complete
|
### v2.2.3 (2026-03-11)
|
||||||
- [x] README.md
|
- FFC/ribbon cable passthrough workflow (connect_passthrough, sync_schematic_to_board)
|
||||||
- [x] ROADMAP.md
|
- Project snapshot system
|
||||||
- [x] IPC_BACKEND_STATUS.md
|
- SVG logo import
|
||||||
- [x] IPC_API_MIGRATION_PLAN.md
|
- ERC validation
|
||||||
- [x] REALTIME_WORKFLOW.md
|
- Developer mode (KICAD_MCP_DEV=1)
|
||||||
- [x] LIBRARY_INTEGRATION.md
|
- Critical B.Cu routing fixes
|
||||||
- [x] KNOWN_ISSUES.md
|
|
||||||
- [x] UI_AUTO_LAUNCH.md
|
|
||||||
- [x] VISUAL_FEEDBACK.md
|
|
||||||
- [x] CLIENT_CONFIGURATION.md
|
|
||||||
- [x] BUILD_AND_TEST_SESSION.md
|
|
||||||
- [x] STATUS_SUMMARY.md (this document)
|
|
||||||
- [x] WINDOWS_SETUP.md
|
|
||||||
- [x] WINDOWS_TROUBLESHOOTING.md
|
|
||||||
|
|
||||||
### Needed
|
### v2.2.2-alpha (2026-03-01)
|
||||||
- [ ] EXAMPLE_PROJECTS.md
|
- route_pad_to_pad with auto-via insertion
|
||||||
- [ ] CONTRIBUTING.md
|
- copy_routing_pattern for trace replication
|
||||||
- [ ] API_REFERENCE.md
|
- Project-local library resolution
|
||||||
|
|
||||||
|
### v2.2.1-alpha (2026-02-28)
|
||||||
|
- edit_schematic_component with field position support
|
||||||
|
- Footprint and symbol creator tools
|
||||||
|
|
||||||
|
### v2.2.0-alpha (2026-02-27)
|
||||||
|
- 13 new routing/component tools
|
||||||
|
- Datasheet enrichment tools
|
||||||
|
- SWIG/UUID bug fixes
|
||||||
|
|
||||||
|
### v2.1.0-alpha (2026-01-10)
|
||||||
|
- Complete schematic wiring system
|
||||||
|
- Dynamic symbol loading (~10,000 symbols)
|
||||||
|
- JLCPCB parts integration
|
||||||
|
- Router pattern (70% context reduction)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## What's Next?
|
## Community Contributors
|
||||||
|
|
||||||
### Immediate Priorities
|
| Contributor | Key Contributions |
|
||||||
1. **Complete IPC Testing** - Verify all 21 IPC handlers work correctly
|
|------------|-------------------|
|
||||||
2. **Fix Edge Cases** - Address any issues found during testing
|
| Kletternaut | Routing tools, footprint/symbol creators, passthrough workflow, template fixes |
|
||||||
3. **Improve Error Handling** - Better fallback behavior
|
| Mehanik | Schematic inspection/editing tools, component field positions |
|
||||||
|
| jflaflamme | Freerouting autorouter integration with Docker/Podman |
|
||||||
### Planned Features
|
| l3wi | Local symbol library search, JLCPCB third-party library support |
|
||||||
- JLCPCB parts integration
|
| gwall-ceres | MCP protocol compliance, Windows compatibility |
|
||||||
- Digikey API integration
|
| fariouche | Bug fixes |
|
||||||
- Advanced routing algorithms
|
| shuofengzhang | XDG relative path handling |
|
||||||
- Smart BOM management
|
| sid115 | Windows setup script improvements |
|
||||||
- Design pattern library (Arduino shields, RPi HATs)
|
| pasrom | MCP server bug fixes |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -273,15 +145,14 @@ The server automatically selects the best backend:
|
|||||||
2. Review [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for common problems
|
2. Review [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for common problems
|
||||||
3. Check logs: `~/.kicad-mcp/logs/kicad_interface.log`
|
3. Check logs: `~/.kicad-mcp/logs/kicad_interface.log`
|
||||||
|
|
||||||
**For Developers:**
|
**For Contributors:**
|
||||||
1. Read [BUILD_AND_TEST_SESSION.md](BUILD_AND_TEST_SESSION.md)
|
1. Read [CONTRIBUTING.md](../CONTRIBUTING.md) for development setup
|
||||||
2. Check [ROADMAP.md](ROADMAP.md) for priorities
|
2. Check [ARCHITECTURE.md](ARCHITECTURE.md) for system design
|
||||||
3. Review [IPC_BACKEND_STATUS.md](IPC_BACKEND_STATUS.md) for IPC details
|
3. Review the [Documentation Index](INDEX.md) for all available docs
|
||||||
|
|
||||||
**Issues:**
|
**Issues:**
|
||||||
- Open an issue on GitHub with OS, KiCAD version, and error details
|
- Open an issue on GitHub with OS, KiCAD version, and error details
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Last Updated: 2025-12-02*
|
*Last Updated: 2026-03-21*
|
||||||
*Maintained by: KiCAD MCP Team*
|
|
||||||
|
|||||||
113
docs/SVG_IMPORT_GUIDE.md
Normal file
113
docs/SVG_IMPORT_GUIDE.md
Normal file
@@ -0,0 +1,113 @@
|
|||||||
|
# SVG Logo Import Guide
|
||||||
|
|
||||||
|
**Added in:** v2.2.3
|
||||||
|
|
||||||
|
The `import_svg_logo` tool converts SVG vector graphics into filled polygons on a KiCAD PCB layer. This is useful for placing company logos, project branding, or custom artwork on your board's silkscreen or copper layers.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tool Reference
|
||||||
|
|
||||||
|
### `import_svg_logo`
|
||||||
|
|
||||||
|
Imports an SVG file as filled graphic polygons onto a PCB layer. Curves are linearized automatically.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Parameter | Type | Required | Default | Description |
|
||||||
|
|-----------|------|----------|---------|-------------|
|
||||||
|
| `pcbPath` | string | Yes | -- | Path to the .kicad_pcb file |
|
||||||
|
| `svgPath` | string | Yes | -- | Path to the SVG logo file |
|
||||||
|
| `x` | number | Yes | -- | X position of the logo top-left corner in mm |
|
||||||
|
| `y` | number | Yes | -- | Y position of the logo top-left corner in mm |
|
||||||
|
| `width` | number | Yes | -- | Target width of the logo in mm (height scales to preserve aspect ratio) |
|
||||||
|
| `layer` | string | No | F.SilkS | PCB layer name (e.g., F.SilkS, B.SilkS, F.Cu, B.Cu) |
|
||||||
|
| `strokeWidth` | number | No | 0 | Outline stroke width in mm (0 = no outline) |
|
||||||
|
| `filled` | boolean | No | true | Fill polygons with solid color |
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
- Polygon count
|
||||||
|
- Final dimensions (width x height in mm)
|
||||||
|
- Layer used
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## SVG Requirements
|
||||||
|
|
||||||
|
### Supported Features
|
||||||
|
- Path elements with M, L, H, V, C, S, Q, T, A, Z commands
|
||||||
|
- Filled shapes (polygons, rectangles, circles, ellipses)
|
||||||
|
- Nested groups and transforms
|
||||||
|
- Cubic and quadratic Bezier curves (linearized automatically)
|
||||||
|
|
||||||
|
### Recommendations
|
||||||
|
- Use simple, solid shapes -- avoid complex gradients or filters
|
||||||
|
- Convert text to paths/outlines before importing
|
||||||
|
- Ensure shapes are filled (not just stroked) for best results
|
||||||
|
- Keep the SVG clean -- remove unnecessary metadata and layers
|
||||||
|
|
||||||
|
### What Will Not Work
|
||||||
|
- Raster images embedded in SVG
|
||||||
|
- CSS-based styling (inline style attributes are preferred)
|
||||||
|
- Complex SVG filters or effects
|
||||||
|
- Transparency (PCB layers are binary -- copper or no copper)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
### 1. Prepare Your SVG
|
||||||
|
|
||||||
|
If starting from a raster image (PNG, JPG):
|
||||||
|
- Use a vector graphics editor (Inkscape, Illustrator, Figma) to trace the image
|
||||||
|
- In Inkscape: Path > Trace Bitmap to convert
|
||||||
|
- Export as plain SVG
|
||||||
|
|
||||||
|
If starting from a vector logo:
|
||||||
|
- Open in a vector editor
|
||||||
|
- Convert all text to paths (Object to Path / Create Outlines)
|
||||||
|
- Remove unnecessary layers and hidden elements
|
||||||
|
- Save as plain SVG
|
||||||
|
|
||||||
|
### 2. Import the Logo
|
||||||
|
|
||||||
|
```
|
||||||
|
Import my company logo from ~/logos/logo.svg onto the board at position x=25 y=40 with width 15mm on the front silkscreen.
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Verify Placement
|
||||||
|
|
||||||
|
Use `get_board_2d_view` to preview the board with the logo, or open in KiCAD to check placement.
|
||||||
|
|
||||||
|
### 4. Adjust if Needed
|
||||||
|
|
||||||
|
Re-run `import_svg_logo` with different position, width, or layer parameters.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Layer Options
|
||||||
|
|
||||||
|
| Layer | Use Case |
|
||||||
|
|-------|----------|
|
||||||
|
| `F.SilkS` | Front silkscreen (most common for logos) |
|
||||||
|
| `B.SilkS` | Back silkscreen |
|
||||||
|
| `F.Cu` | Front copper (logo as exposed copper) |
|
||||||
|
| `B.Cu` | Back copper |
|
||||||
|
| `F.Mask` | Front solder mask opening (exposes copper underneath) |
|
||||||
|
| `B.Mask` | Back solder mask opening |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Manufacturing Considerations
|
||||||
|
|
||||||
|
- **Silkscreen logos** are the safest choice -- no impact on electrical design
|
||||||
|
- **Copper logos** will be part of the copper layer and may affect DRC. Ensure adequate clearance from traces and pads
|
||||||
|
- **Minimum feature size** depends on your PCB fabricator. Most support 0.15mm (6mil) minimum line width for silkscreen
|
||||||
|
- **Logo size** should account for manufacturing tolerances -- very small details may not reproduce well
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Source Files
|
||||||
|
|
||||||
|
- TypeScript tool definition: `src/tools/board.ts` (import_svg_logo)
|
||||||
|
- Python implementation: `python/commands/svg_import.py`
|
||||||
@@ -1,115 +1,343 @@
|
|||||||
# KiCAD MCP Server - Tool Inventory
|
# KiCAD MCP Server - Complete Tool Inventory
|
||||||
|
|
||||||
**Total Tools: 59**
|
**Version:** 2.2.3
|
||||||
**Token Impact: ~40K+ tokens before any user interaction**
|
**Total Tools:** 122 (18 direct + 65 routed + 4 router + 35 additional)
|
||||||
|
**Last Updated:** 2026-03-21
|
||||||
|
|
||||||
## Current Tool Categories
|
## How Tools Are Organized
|
||||||
|
|
||||||
### Project Management (4 tools)
|
The server uses a **router pattern** to reduce AI context usage. Tools fall into three groups:
|
||||||
- `create_project` - Create a new KiCAD project
|
|
||||||
- `open_project` - Open an existing KiCAD project
|
|
||||||
- `save_project` - Save the current KiCAD project
|
|
||||||
- `get_project_info` - Get information about the current project
|
|
||||||
|
|
||||||
### Board Management (12 tools)
|
- **Direct tools** - Always visible to the AI. High-frequency operations used in most sessions.
|
||||||
- `set_board_size` - Set the board dimensions
|
- **Routed tools** - Organized into categories. Discovered via the router tools (`list_tool_categories`, `get_category_tools`, `search_tools`) and invoked via `execute_tool`.
|
||||||
- `add_layer` - Add a new layer to the board
|
- **Additional tools** - Registered directly (always visible) but not part of the router categories.
|
||||||
- `set_active_layer` - Set the active working layer
|
|
||||||
- `get_board_info` - Get board information
|
|
||||||
- `get_layer_list` - Get list of all layers
|
|
||||||
- `add_board_outline` - Add board outline shape (rectangle/circle/polygon)
|
|
||||||
- `add_mounting_hole` - Add mounting hole to the board
|
|
||||||
- `add_board_text` - Add text to the board
|
|
||||||
- `add_zone` - Add copper zone/pour
|
|
||||||
- `get_board_extents` - Get board bounding box
|
|
||||||
- `get_board_2d_view` - Get 2D visualization of board
|
|
||||||
|
|
||||||
### Component Management (10 tools)
|
---
|
||||||
- `place_component` - Place a component on the board
|
|
||||||
- `move_component` - Move a component to new position
|
|
||||||
- `rotate_component` - Rotate a component
|
|
||||||
- `delete_component` - Delete a component
|
|
||||||
- `edit_component` - Edit component properties
|
|
||||||
- `find_component` - Find component by reference or value
|
|
||||||
- `get_component_properties` - Get component properties
|
|
||||||
- `add_component_annotation` - Add annotation to component
|
|
||||||
- `group_components` - Group multiple components
|
|
||||||
- `replace_component` - Replace component with another
|
|
||||||
|
|
||||||
### Routing (4 tools)
|
## Project Management (5 tools)
|
||||||
- `add_net` - Create a new net
|
|
||||||
- `route_trace` - Route a trace between two points
|
|
||||||
- `add_via` - Add a via
|
|
||||||
- `add_copper_pour` - Add copper pour (ground/power plane)
|
|
||||||
|
|
||||||
### Design Rules & DRC (9 tools)
|
*Source: `src/tools/project.ts`*
|
||||||
- `set_design_rules` - Configure design rules
|
|
||||||
- `get_design_rules` - Get current design rules
|
|
||||||
- `run_drc` - Run design rule check
|
|
||||||
- `add_net_class` - Add a net class with specific rules
|
|
||||||
- `assign_net_to_class` - Assign net to a net class
|
|
||||||
- `set_layer_constraints` - Set layer-specific constraints
|
|
||||||
- `check_clearance` - Check clearance between items
|
|
||||||
- `get_drc_violations` - Get DRC violation list
|
|
||||||
|
|
||||||
### Export (8 tools)
|
| Tool | Description | Access |
|
||||||
- `export_gerber` - Export Gerber files for fabrication
|
|------|-------------|--------|
|
||||||
- `export_pdf` - Export PDF documentation
|
| `create_project` | Create a new KiCAD project (.kicad_pro, .kicad_pcb, .kicad_sch) | Direct |
|
||||||
- `export_svg` - Export SVG graphics
|
| `open_project` | Open an existing KiCAD project | Direct |
|
||||||
- `export_3d` - Export 3D model (STEP/STL/VRML/OBJ)
|
| `save_project` | Save the current project | Direct |
|
||||||
- `export_bom` - Export bill of materials
|
| `get_project_info` | Get project metadata and information | Direct |
|
||||||
- `export_netlist` - Export netlist
|
| `snapshot_project` | Save a named checkpoint snapshot (renders PDF, saves step label) | Direct |
|
||||||
- `export_position_file` - Export component position file
|
|
||||||
- `export_vrml` - Export VRML 3D model
|
|
||||||
|
|
||||||
### Library (4 tools)
|
---
|
||||||
- `list_libraries` - List available footprint libraries
|
|
||||||
- `search_footprints` - Search for footprints across libraries
|
|
||||||
- `list_library_footprints` - List footprints in specific library
|
|
||||||
- `get_footprint_info` - Get detailed footprint information
|
|
||||||
|
|
||||||
### Schematic (9 tools)
|
## Board Management (12 tools)
|
||||||
- `create_schematic` - Create a new schematic
|
|
||||||
- `add_schematic_component` - Add component to schematic
|
|
||||||
- `add_wire` - Add wire connection in schematic
|
|
||||||
- `add_schematic_connection` - Connect component pins
|
|
||||||
- `add_schematic_net_label` - Add net label
|
|
||||||
- `connect_to_net` - Connect pin to named net
|
|
||||||
- `get_net_connections` - Get all connections for a net
|
|
||||||
- `generate_netlist` - Generate netlist from schematic
|
|
||||||
|
|
||||||
### UI Management (2 tools)
|
*Source: `src/tools/board.ts`*
|
||||||
- `check_kicad_ui` - Check if KiCAD UI is running
|
|
||||||
- `launch_kicad_ui` - Launch KiCAD UI
|
|
||||||
|
|
||||||
## Router Implementation Plan
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `set_board_size` | Set PCB dimensions (width, height, unit) | Direct |
|
||||||
|
| `add_board_outline` | Add board outline (rectangle, circle, polygon, rounded_rectangle) | Direct |
|
||||||
|
| `get_board_info` | Get board metadata and properties | Direct |
|
||||||
|
| `add_layer` | Add copper/technical/signal layer | Routed (board) |
|
||||||
|
| `set_active_layer` | Change the active working layer | Routed (board) |
|
||||||
|
| `get_layer_list` | List all layers on the board | Routed (board) |
|
||||||
|
| `add_mounting_hole` | Add mounting hole with optional pad | Routed (board) |
|
||||||
|
| `add_board_text` | Add text annotation to board | Routed (board) |
|
||||||
|
| `add_zone` | Add copper zone/pour with clearance settings | Routed (board) |
|
||||||
|
| `get_board_extents` | Get bounding box of board | Routed (board) |
|
||||||
|
| `get_board_2d_view` | Render 2D board view (PNG/JPG/SVG) | Routed (board) |
|
||||||
|
| `import_svg_logo` | Import SVG file as polygons on silkscreen layer | Additional |
|
||||||
|
|
||||||
### Direct Tools (Always Visible) - 12 tools
|
---
|
||||||
High-frequency operations used in 80%+ of sessions:
|
|
||||||
- `create_project`
|
|
||||||
- `open_project`
|
|
||||||
- `save_project`
|
|
||||||
- `get_project_info`
|
|
||||||
- `place_component`
|
|
||||||
- `move_component`
|
|
||||||
- `add_net`
|
|
||||||
- `route_trace`
|
|
||||||
- `get_board_info`
|
|
||||||
- `set_board_size`
|
|
||||||
- `add_board_outline`
|
|
||||||
- `check_kicad_ui`
|
|
||||||
|
|
||||||
### Router Tools - 4 tools
|
## Component Management (16 tools)
|
||||||
Discovery and execution:
|
|
||||||
- `list_tool_categories`
|
|
||||||
- `get_category_tools`
|
|
||||||
- `execute_tool`
|
|
||||||
- `search_tools`
|
|
||||||
|
|
||||||
### Routed Tools (Hidden) - 47 tools
|
*Source: `src/tools/component.ts`*
|
||||||
Organized into categories for discovery.
|
|
||||||
|
|
||||||
## Expected Impact
|
| Tool | Description | Access |
|
||||||
**Before Router**: 59 tools = ~40K+ tokens
|
|------|-------------|--------|
|
||||||
**After Router**: 16 tools (12 direct + 4 router) = ~12K tokens
|
| `place_component` | Place footprint on PCB (position, rotation, reference, value) | Direct |
|
||||||
**Savings**: ~28K tokens (70% reduction)
|
| `move_component` | Move component to new position | Direct |
|
||||||
|
| `rotate_component` | Rotate component (absolute angle) | Routed (component) |
|
||||||
|
| `delete_component` | Remove component from board | Routed (component) |
|
||||||
|
| `edit_component` | Edit component properties (reference, value, footprint) | Routed (component) |
|
||||||
|
| `find_component` | Search components by reference or value | Routed (component) |
|
||||||
|
| `get_component_properties` | Get all properties of a component | Routed (component) |
|
||||||
|
| `add_component_annotation` | Add annotation/comment to component | Routed (component) |
|
||||||
|
| `group_components` | Group multiple components together | Routed (component) |
|
||||||
|
| `replace_component` | Replace component with different footprint | Routed (component) |
|
||||||
|
| `get_component_pads` | Get all pad information for a component | Additional |
|
||||||
|
| `get_component_list` | List all components with optional filters | Additional |
|
||||||
|
| `get_pad_position` | Get precise position of a specific pad | Additional |
|
||||||
|
| `place_component_array` | Place array of components (rows x columns) | Additional |
|
||||||
|
| `align_components` | Align components (horizontal, vertical, grid) | Additional |
|
||||||
|
| `duplicate_component` | Duplicate component with offset | Additional |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Routing (13 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/routing.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `add_net` | Create a new net on the PCB | Direct |
|
||||||
|
| `route_trace` | Route trace segment between XY points (single layer) | Direct |
|
||||||
|
| `add_via` | Add via (through/blind/buried) | Routed (routing) |
|
||||||
|
| `add_copper_pour` | Add copper pour / ground plane | Routed (routing) |
|
||||||
|
| `delete_trace` | Delete traces by UUID, position, or bulk by net | Additional |
|
||||||
|
| `query_traces` | Query/filter traces by net, layer, or bounding box | Additional |
|
||||||
|
| `get_nets_list` | List all nets with statistics | Additional |
|
||||||
|
| `modify_trace` | Modify existing trace (width, layer, net) | Additional |
|
||||||
|
| `create_netclass` | Create net class with design rules | Additional |
|
||||||
|
| `route_differential_pair` | Route differential pair traces | Additional |
|
||||||
|
| `refill_zones` | Refill all copper zones | Additional |
|
||||||
|
| `route_pad_to_pad` | Route trace between two pads with auto-via insertion | Additional |
|
||||||
|
| `copy_routing_pattern` | Copy routing from source to target component groups | Additional |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Design Rules and DRC (8 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/design-rules.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `set_design_rules` | Set global design rules (clearance, track width, via sizes) | Routed (drc) |
|
||||||
|
| `get_design_rules` | Get current design rules | Routed (drc) |
|
||||||
|
| `run_drc` | Run design rule check | Routed (drc) |
|
||||||
|
| `add_net_class` | Add net class with custom rules | Routed (drc) |
|
||||||
|
| `assign_net_to_class` | Assign net to a net class | Routed (drc) |
|
||||||
|
| `set_layer_constraints` | Set layer-specific constraints | Routed (drc) |
|
||||||
|
| `check_clearance` | Check clearance between two items | Routed (drc) |
|
||||||
|
| `get_drc_violations` | Get DRC violation list (filter by severity) | Routed (drc) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Export (8 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/export.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `export_gerber` | Export Gerber files for fabrication | Routed (export) |
|
||||||
|
| `export_pdf` | Export PDF with layer selection and page size | Routed (export) |
|
||||||
|
| `export_svg` | Export SVG vector graphics | Routed (export) |
|
||||||
|
| `export_3d` | Export 3D model (STEP, STL, VRML, OBJ) | Routed (export) |
|
||||||
|
| `export_bom` | Export Bill of Materials (CSV, XML, HTML, JSON) | Routed (export) |
|
||||||
|
| `export_netlist` | Export netlist (KiCad, Spice, Cadstar, OrcadPCB2) | Routed (export) |
|
||||||
|
| `export_position_file` | Export component position file for pick and place | Routed (export) |
|
||||||
|
| `export_vrml` | Export VRML 3D model | Routed (export) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Schematic (27 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/schematic.ts`*
|
||||||
|
|
||||||
|
### Component Operations
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `add_schematic_component` | Add component to schematic (symbol from library) | Direct |
|
||||||
|
| `delete_schematic_component` | Remove component from schematic | Additional |
|
||||||
|
| `edit_schematic_component` | Edit component properties (footprint, value, reference) | Additional |
|
||||||
|
| `get_schematic_component` | Get component info with field positions | Additional |
|
||||||
|
| `list_schematic_components` | List all components in schematic | Direct |
|
||||||
|
| `move_schematic_component` | Move component to new position | Routed (schematic) |
|
||||||
|
| `rotate_schematic_component` | Rotate component | Routed (schematic) |
|
||||||
|
| `annotate_schematic` | Auto-annotate reference designators | Direct |
|
||||||
|
|
||||||
|
### Wiring and Connections
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `add_wire` | Add wire connection between two points | Routed (schematic) |
|
||||||
|
| `delete_schematic_wire` | Delete wire segment | Routed (schematic) |
|
||||||
|
| `add_schematic_connection` | Connect two component pins with wire | Routed (schematic) |
|
||||||
|
| `add_schematic_net_label` | Add net label to schematic | Direct |
|
||||||
|
| `delete_schematic_net_label` | Delete net label | Routed (schematic) |
|
||||||
|
| `connect_to_net` | Connect component pin to named net | Direct |
|
||||||
|
| `connect_passthrough` | Connect all matching pins between two connectors | Direct |
|
||||||
|
| `get_schematic_pin_locations` | Get pin locations for a component | Additional |
|
||||||
|
|
||||||
|
### Net Analysis
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `get_net_connections` | Get all connections for a net | Routed (schematic) |
|
||||||
|
| `list_schematic_nets` | List all nets in schematic | Routed (schematic) |
|
||||||
|
| `list_schematic_wires` | List all wires in schematic | Routed (schematic) |
|
||||||
|
| `list_schematic_labels` | List all net labels | Routed (schematic) |
|
||||||
|
|
||||||
|
### Schematic Creation and Export
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `create_schematic` | Create a new schematic file | Routed (schematic) |
|
||||||
|
| `get_schematic_view` | Get schematic as image (PNG/SVG) | Routed (schematic) |
|
||||||
|
| `export_schematic_svg` | Export schematic to SVG | Routed (schematic) |
|
||||||
|
| `export_schematic_pdf` | Export schematic to PDF | Routed (schematic) |
|
||||||
|
|
||||||
|
### Validation and Synchronization
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `run_erc` | Run electrical rule check | Additional |
|
||||||
|
| `generate_netlist` | Generate netlist from schematic | Routed (schematic) |
|
||||||
|
| `sync_schematic_to_board` | Sync schematic components/nets to PCB (F8 equivalent) | Direct |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Footprint Libraries (4 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/library.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `list_libraries` | List all footprint libraries | Routed (library) |
|
||||||
|
| `search_footprints` | Search footprints across libraries | Routed (library) |
|
||||||
|
| `list_library_footprints` | List footprints in a specific library | Routed (library) |
|
||||||
|
| `get_footprint_info` | Get detailed footprint information | Routed (library) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Symbol Libraries (4 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/library-symbol.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `list_symbol_libraries` | List all symbol libraries from sym-lib-table | Additional |
|
||||||
|
| `search_symbols` | Search symbols by name, LCSC ID, or description | Additional |
|
||||||
|
| `list_library_symbols` | List symbols in a specific library | Additional |
|
||||||
|
| `get_symbol_info` | Get detailed symbol information | Additional |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Footprint Creator (4 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/footprint.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `create_footprint` | Create custom .kicad_mod footprint (SMD/THT pads, courtyard, silkscreen) | Additional |
|
||||||
|
| `edit_footprint_pad` | Edit pad in existing footprint (size, position, drill, shape) | Additional |
|
||||||
|
| `register_footprint_library` | Register .pretty library in fp-lib-table | Additional |
|
||||||
|
| `list_footprint_libraries` | List available .pretty libraries | Additional |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Symbol Creator (4 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/symbol-creator.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `create_symbol` | Create custom .kicad_sym symbol (pins, rectangles, polylines) | Additional |
|
||||||
|
| `delete_symbol` | Remove symbol from library | Additional |
|
||||||
|
| `list_symbols_in_library` | List all symbols in a .kicad_sym file | Additional |
|
||||||
|
| `register_symbol_library` | Register library in sym-lib-table | Additional |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Datasheet Tools (2 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/datasheet.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `enrich_datasheets` | Fill missing datasheet URLs using LCSC part numbers | Additional |
|
||||||
|
| `get_datasheet_url` | Get LCSC datasheet URL for a component | Additional |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## JLCPCB Integration (5 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/jlcpcb-api.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `download_jlcpcb_database` | Download 2.5M+ parts catalog to local SQLite database | Additional |
|
||||||
|
| `search_jlcpcb_parts` | Search parts by specs (category, package, library type) | Additional |
|
||||||
|
| `get_jlcpcb_part` | Get detailed part info with pricing | Additional |
|
||||||
|
| `get_jlcpcb_database_stats` | Get database statistics | Additional |
|
||||||
|
| `suggest_jlcpcb_alternatives` | Find cheaper or in-stock alternatives | Additional |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Freerouting Autorouter (4 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/freerouting.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `autoroute` | Run Freerouting autorouter (export DSN, route, import SES) | Routed (autoroute) |
|
||||||
|
| `export_dsn` | Export Specctra DSN file for manual routing | Routed (autoroute) |
|
||||||
|
| `import_ses` | Import routed SES file back into PCB | Routed (autoroute) |
|
||||||
|
| `check_freerouting` | Check Java and Freerouting JAR availability | Routed (autoroute) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## UI Management (2 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/ui.ts`*
|
||||||
|
|
||||||
|
| Tool | Description | Access |
|
||||||
|
|------|-------------|--------|
|
||||||
|
| `check_kicad_ui` | Check if KiCAD UI is running | Direct |
|
||||||
|
| `launch_kicad_ui` | Launch KiCAD UI (optionally with project) | Routed (board) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Router Tools (4 tools)
|
||||||
|
|
||||||
|
*Source: `src/tools/router.ts`*
|
||||||
|
|
||||||
|
These meta-tools provide discovery and execution of routed tools:
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `list_tool_categories` | Browse all available tool categories |
|
||||||
|
| `get_category_tools` | View tools in a specific category |
|
||||||
|
| `search_tools` | Find tools by keyword |
|
||||||
|
| `execute_tool` | Run any routed tool with parameters |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary by Access Type
|
||||||
|
|
||||||
|
| Access Type | Count | Description |
|
||||||
|
|-------------|-------|-------------|
|
||||||
|
| Direct | 18 | Always visible, no router needed |
|
||||||
|
| Routed | 65 | Discovered via router, invoked via `execute_tool` |
|
||||||
|
| Router | 4 | Meta-tools for discovering and running routed tools |
|
||||||
|
| Additional | 35 | Always visible, registered directly |
|
||||||
|
| **Total** | **122** | |
|
||||||
|
|
||||||
|
## Summary by Category
|
||||||
|
|
||||||
|
| Category | Tool Count |
|
||||||
|
|----------|------------|
|
||||||
|
| Project Management | 5 |
|
||||||
|
| Board Management | 12 |
|
||||||
|
| Component Management | 16 |
|
||||||
|
| Routing | 13 |
|
||||||
|
| Design Rules / DRC | 8 |
|
||||||
|
| Export | 8 |
|
||||||
|
| Schematic | 27 |
|
||||||
|
| Footprint Libraries | 4 |
|
||||||
|
| Symbol Libraries | 4 |
|
||||||
|
| Footprint Creator | 4 |
|
||||||
|
| Symbol Creator | 4 |
|
||||||
|
| Datasheet | 2 |
|
||||||
|
| JLCPCB Integration | 5 |
|
||||||
|
| Freerouting | 4 |
|
||||||
|
| UI Management | 2 |
|
||||||
|
| Router | 4 |
|
||||||
|
| **Total** | **122** |
|
||||||
|
|
||||||
|
## Token Impact
|
||||||
|
|
||||||
|
**Before Router Pattern:** All 122 tools in context = ~80K+ tokens
|
||||||
|
**With Router Pattern:** 18 direct + 35 additional + 4 router = 57 always-visible tools
|
||||||
|
**On-Demand:** 65 routed tools loaded only when their category is requested
|
||||||
|
|||||||
18
docs/archive/README.md
Normal file
18
docs/archive/README.md
Normal file
@@ -0,0 +1,18 @@
|
|||||||
|
# Archived Documentation
|
||||||
|
|
||||||
|
This directory contains historical planning and session documents from the KiCAD MCP Server development. These documents record the design decisions and implementation progress for features that are now complete.
|
||||||
|
|
||||||
|
They are preserved for historical reference but are no longer maintained. For current documentation, see the [Documentation Index](../INDEX.md).
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- **SCHEMATIC_WIRING_PLAN.md** - Original plan for the intelligent wiring system (completed v2.1.0)
|
||||||
|
- **SCHEMATIC_WORKFLOW_FIX.md** - Fix for broken schematic workflow, Issue #26 (completed v2.1.0)
|
||||||
|
- **DYNAMIC_LIBRARY_LOADING_PLAN.md** - Plan for dynamic symbol loading (completed v2.1.0)
|
||||||
|
- **DYNAMIC_LOADING_STATUS.md** - Status tracking for dynamic symbol loader (completed v2.1.0)
|
||||||
|
- **JLCPCB_INTEGRATION_PLAN.md** - Original JLCPCB integration plan (completed v2.1.0)
|
||||||
|
- **ROUTER_IMPLEMENTATION_STATUS.md** - Router pattern implementation progress (completed v2.0.0)
|
||||||
|
- **IPC_API_MIGRATION_PLAN.md** - IPC backend migration plan (completed v2.0.0)
|
||||||
|
- **BUILD_AND_TEST_SESSION.md** - Early build and test session notes
|
||||||
|
- **WEEK1_SESSION1_SUMMARY.md** - Week 1 development session 1 notes
|
||||||
|
- **WEEK1_SESSION2_SUMMARY.md** - Week 1 development session 2 notes
|
||||||
Reference in New Issue
Block a user