Metadata-Version: 2.5
Name: kcaa
Version: 0.2.11
Summary: Model Context Protocol (MCP) server for KiCad electronic design automation (EDA) files
Project-URL: Homepage, https://github.com/paul356/KiCad-AI-Assistant
Project-URL: Bug Tracker, https://github.com/paul356/KiCad-AI-Assistant/issues
Project-URL: Documentation, https://github.com/paul356/KiCad-AI-Assistant#readme
Author: KiCad MCP Contributors
Maintainer: KiCad MCP Contributors
License: MIT
License-File: LICENSE
Keywords: ai,assistant,eda,electronics,kicad,mcp,model-context-protocol,pcb,schematic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: certifi>=2026.2.25
Requires-Dist: defusedxml>=0.7.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: kicad-python>=0.7.1
Requires-Dist: kicad-skip>=0.2.5
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rtree>=1.3.0
Requires-Dist: shapely>=2.0.0
Requires-Dist: sqlalchemy>=2.0.0
Description-Content-Type: text/markdown

# KiCad AI Assistant

KiCad AI Assistant is a KiCad action plugin that embeds an LLM-powered chat panel directly inside KiCad. It runs a built-in [MCP](https://modelcontextprotocol.io/) server and exposes a rich set of tools so the LLM can read and edit your schematics and PCB layouts through natural-language conversation.

Tested on **KiCad 10.0 / Linux & Windows**.

[![CI](https://github.com/paul356/KiCad-AI-Assistant/actions/workflows/ci.yml/badge.svg)](https://github.com/paul356/KiCad-AI-Assistant/actions/workflows/ci.yml)

**Contributions welcome!** Bug reports, feature ideas, and pull requests are all appreciated — see [Contributing](#contributing) for how to get started.

## Table of Contents

- [KiCad AI Assistant](#kicad-ai-assistant)
  - [Table of Contents](#table-of-contents)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
    - [1. Clone the repository (optional)](#1-clone-the-repository-optional)
    - [2. Install the plugin](#2-install-the-plugin)
    - [3. Create the plugin virtual environment](#3-create-the-plugin-virtual-environment)
    - [4. Load the plugin in KiCad](#4-load-the-plugin-in-kicad)
  - [Configuration](#configuration)
  - [Standalone MCP Server](#standalone-mcp-server)
  - [Feature Highlights](#feature-highlights)
  - [Available Tools](#available-tools)
    - [Project Tools](#project-tools)
    - [Symbol Library](#symbol-library)
    - [Schematic Editing](#schematic-editing)
    - [Schematic Groups](#schematic-groups)
    - [Schematic Analysis](#schematic-analysis)
    - [Hierarchical Sheets](#hierarchical-sheets)
    - [PCB Library](#pcb-library)
    - [PCB Query](#pcb-query)
    - [PCB Editing](#pcb-editing)
    - [PCB Routing](#pcb-routing)
    - [PCB Placement](#pcb-placement)
    - [PCB Groups](#pcb-groups)
    - [PCB Zones](#pcb-zones)
    - [DRC \& Design Rules](#drc--design-rules)
    - [Versioning \& Export](#versioning--export)
    - [Skill System](#skill-system)
    - [KiCad IPC](#kicad-ipc)
  - [Project Structure](#project-structure)
  - [Troubleshooting](#troubleshooting)
  - [Contributing](#contributing)
  - [License](#license)

## Prerequisites

- KiCad 10.0 or higher
- [`uv`](https://github.com/astral-sh/uv) — manages the Python virtual environment and installs the correct Python version automatically
  - Linux/macOS: `curl -Lsf https://astral.sh/uv/install.sh | sh`
  - Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
- An API key for OpenAI, Anthropic, Amazon Bedrock, or a compatible LLM provider (Ollama needs none)

## Installation

### 1. Clone the repository (optional)

Only needed if you want to build the plugin from source or contribute to the project. Skip this step if you're downloading the pre-built plugin from the Releases page.

```bash
git clone https://github.com/paul356/KiCad-AI-Assistant.git
cd KiCad-AI-Assistant
```

### 2. Install the plugin

Two release archives are published:

- `kicad_ai_assistant.zip` — manual installation and the in-panel updater.
- `kicad_ai_assistant_pcm.zip` — installation through KiCad's Plugin and Content Manager ("Install from File…").

Both install the same plugin contents; the installed folder names differ (`kicad_ai_assistant/` for manual installs, `com_github_paul356_kicad-ai-assistant/` for PCM). `10.0` below is your KiCad `<major>.<minor>` version. `KICAD_DOCUMENTS_HOME` overrides the documents directory on every OS.

| OS | Manual install: `scripting/plugins` | PCM install: `3rdparty/plugins` |
|----|-------------------------------------|---------------------------------|
| Linux | `~/.local/share/kicad/10.0/scripting/plugins` | `~/.local/share/kicad/10.0/3rdparty/plugins` |
| macOS | `~/Documents/KiCad/10.0/scripting/plugins` | `~/Documents/KiCad/10.0/3rdparty/plugins` |
| Windows | `%USERPROFILE%\Documents\KiCad\10.0\scripting\plugins` | `%USERPROFILE%\Documents\KiCad\10.0\3rdparty\plugins` |

Download `kicad_ai_assistant.zip` from the [Releases page](https://github.com/paul356/KiCad-AI-Assistant/releases) and unzip it into the manual directory:

**Linux:**
```bash
KICAD_PLUGIN_DIR=~/.local/share/kicad/10.0/scripting/plugins
mkdir -p "$KICAD_PLUGIN_DIR"
unzip kicad_ai_assistant.zip -d "$KICAD_PLUGIN_DIR"
```

**macOS:**
```bash
KICAD_PLUGIN_DIR=~/Documents/KiCad/10.0/scripting/plugins
mkdir -p "$KICAD_PLUGIN_DIR"
unzip kicad_ai_assistant.zip -d "$KICAD_PLUGIN_DIR"
```

**Windows (PowerShell):**
```powershell
$KICAD_PLUGIN_DIR = "$env:USERPROFILE\Documents\KiCad\10.0\scripting\plugins"
New-Item -ItemType Directory -Force -Path $KICAD_PLUGIN_DIR
Expand-Archive -Path kicad_ai_assistant.zip -DestinationPath $KICAD_PLUGIN_DIR
```

The archive already contains the `kicad_ai_assistant/` root directory. Keep that name so the documented `cd`/setup commands and the manual-install convention match; renaming the installed folder is unsupported. Do not hand-unzip this archive into `3rdparty/plugins` — that directory belongs to the Plugin and Content Manager, and a manually copied folder there is not a PCM install.

**Plugin and Content Manager:** open **Preferences → Plugin and Content Manager → Install from File…** and select `kicad_ai_assistant_pcm.zip`. KiCad extracts the package to `<3rdparty>/plugins/com_github_paul356_kicad-ai-assistant/`; that package directory is the plugin directory (its `__init__.py` sits directly inside it). Do not unzip this archive yourself. PCM updates keep `.venv` and the freerouting JAR (`keep_on_update`); rerun the setup script after an update so the venv gets the matching `kcaa` version.

Or build from source:

```bash
# In the repo root:
make dist-plugin          # dist/kicad_ai_assistant.zip (manual install + updater)
make dist-pcm             # dist/kicad_ai_assistant_pcm.zip (PCM install)

# Linux:
KICAD_PLUGIN_DIR=~/.local/share/kicad/10.0/scripting/plugins
mkdir -p "$KICAD_PLUGIN_DIR"
unzip dist/kicad_ai_assistant.zip -d "$KICAD_PLUGIN_DIR"

# macOS:
KICAD_PLUGIN_DIR=~/Documents/KiCad/10.0/scripting/plugins
mkdir -p "$KICAD_PLUGIN_DIR"
unzip dist/kicad_ai_assistant.zip -d "$KICAD_PLUGIN_DIR"
```

### 3. Create the plugin virtual environment

Run the setup script from inside the installed plugin directory to create a `.venv`, install `kcaa` from PyPI, install **PyMuPDF** (imported as `fitz`, used for PDF import), and download the freerouting JAR. This requires `uv`; when it is missing the script prints an error and exits non-zero — install it from <https://docs.astral.sh/uv/getting-started/installation/> or with the command in [Prerequisites](#prerequisites). `uv` will automatically install the required Python version.

**Linux:**
```bash
cd ~/.local/share/kicad/10.0/scripting/plugins/kicad_ai_assistant
./setup_plugin.sh
```

**macOS:**
```bash
cd ~/Documents/KiCad/10.0/scripting/plugins/kicad_ai_assistant
./setup_plugin.sh
```

**Windows (PowerShell):**
```powershell
cd "$env:USERPROFILE\Documents\KiCad\10.0\scripting\plugins\kicad_ai_assistant"
.\setup_plugin.ps1
```

**Windows (Command Prompt):**
```cmd
cd /d "%USERPROFILE%\Documents\KiCad\10.0\scripting\plugins\kicad_ai_assistant"
setup_plugin.bat
```

For a PCM install, run the same script from `...\3rdparty\plugins\com_github_paul356_kicad-ai-assistant`. The script detects your KiCad version from the plugin directory path. KiCad already provides all necessary environment variables (`KICAD_VERSION`, `KICAD*_DIR`, etc.), so no `.env` file is needed.

The short version of these instructions also ships inside the plugin zip (`kicad_plugin/README.md`).

### 4. Load the plugin in KiCad

1. Open KiCad and load your project.
2. Open the **PCB Editor**.
3. Go to **Preferences → Plugins** and enable **Enable KiCad API**. The panel needs this IPC socket for **Reload PCB** and the `update_pcb_from_schematic` tool; without it those two fail, while file-based editing keeps working. This package does not declare the IPC runtime, so KiCad does not prompt for the toggle — enable it manually.
4. Go to **Tools → External Plugins → Refresh Plugins**.
5. Click **KiCad AI Assistant** in the plugin list to open the chat panel.
6. Go to **Options → Settings** and enter your LLM API key.

## Configuration

Plugin settings are stored in the KiCad user config directory:

Settings file: `~/.config/kicad/10.0/kcaa/kicad_ai_assistant.json`

All settings can be changed through **Options → Settings** in the plugin panel:

| Setting | Description | Default |
|---------|-------------|---------|
| `llm_provider` | LLM provider: `openai`, `anthropic`, `ollama`, or `bedrock` | `openai` |
| `llm_api_key` | Your LLM API key (stored with owner-only permissions). For `bedrock`, a Bedrock API key used as a bearer token | *(empty)* |
| `llm_model` | Model name. For `bedrock`, a Bedrock model or inference-profile id — newer Claude models need the cross-region profile form, e.g. `us.anthropic.claude-opus-5-5` (swap `us.` for your region) | `gpt-4o` |
| `llm_base_url` | Custom endpoint URL (overrides the provider default) | *(provider default)* |
| `llm_aws_region` | AWS region for the Bedrock endpoint (also used for SigV4 signing) | `us-east-1` |
| `llm_aws_access_key_id` | AWS access key id — set this (plus the secret) to use SigV4 instead of a Bedrock API key | *(empty)* |
| `llm_aws_secret_access_key` | AWS secret access key for SigV4 auth | *(empty)* |
| `llm_aws_session_token` | Optional STS session token for temporary AWS credentials | *(empty)* |
| `server_port` | Fixed port for the built-in MCP server (`0` = auto) | `0` |
| `mcp_tool_timeout_seconds` | Per-call deadline (s) for MCP tool calls (e.g. PCB routing); longer calls end the turn with an explicit timeout error. Takes effect after the plugin restarts | `300` |
| `show_tool_log` | Show tool-call log panel by default | `true` |
| `llm_context_tokens` | Total context window size in tokens | `128000` |
| `llm_compact_threshold` | Trigger context compaction at this usage fraction | `0.70` |

### Amazon Bedrock

Bedrock requests go to the native Bedrock Runtime `InvokeModel` API (not the OpenAI-compatible endpoint, which only serves non-Claude models), using the Anthropic Messages format. Authentication is chosen automatically:

- **Bedrock API key** — leave the AWS credential fields blank and put the key in `llm_api_key`; it is sent as a bearer token.
- **AWS SigV4** — set `llm_aws_access_key_id` + `llm_aws_secret_access_key` (and optionally `llm_aws_session_token`); requests are signed with SigV4 for the configured `llm_aws_region`.

Use a model id enabled in your account/region — the cross-region inference-profile ids work well, e.g. `us.anthropic.claude-opus-5-5` or a versioned id like `us.anthropic.claude-sonnet-4-5-20250929-v1:0`. List yours with `aws bedrock list-inference-profiles --region <region>`. Responses are streamed to the chat panel in a single block, since Bedrock's streaming uses a binary framing the plugin's transport does not decode.

## Standalone MCP Server

You can also run `kcaa` as a standalone MCP server without the KiCad plugin. This is useful for integrating with other MCP clients (e.g., Claude Desktop, Cursor).

Create a `.env` file in your working directory:

```dotenv
KICAD_SEARCH_PATHS=/home/user/pcb
KICAD_APP_PATH=/usr/share/kicad
KICAD_VERSION=10.0
KICAD_CONFIG_DIR=~/.config/kicad/10.0
KICAD_3RD_PARTY=~/.local/share/kicad/10.0/3rdparty
MCP_TRANSPORT=streamable-http
```

Then start the server:

```bash
kcaa
```

## Feature Highlights

- **Schematic editing** — Add/remove symbols, set/rename properties, draw and delete wires, connect pins automatically
- **Hierarchical sheets** — Create, read, update, and delete hierarchical sheet symbols and sheet pins
- **PCB footprint library** — Search the system footprint library index by name, description, or tag; set footprints on schematic symbols
- **PCB synchronisation** — Trigger *Update PCB from Schematic* via KiCad's IPC API
- **PCB placement** — Query, move, rotate, flip, align, and distribute footprints; define or clear the board outline
- **Design rules** — View and modify board-level design rules, net classes, and custom DRC rules
- **DRC** — Run design-rule checks directly from the plugin
- **Context management** — Automatic compaction of the LLM context window when it approaches the limit
- **Session management** — Save, restore, and reset the current conversation; save design snapshots for rollback
- **Skill system** — On-demand workflow guidance for the LLM via user-definable Markdown skill files

## Available Tools

**Naming convention** — a `library_` prefix means a **definition inside a library**; no prefix means an **object placed on a board or in a schematic**. A `library_` tool never returns placement.

- `get_library_footprint` — footprint **definition** in a library; key `library_name` + `footprint_name`. Returns pads/courtyard/attributes; pad coordinates are footprint-local, with no board-level placement anchor.
- `get_footprint` — footprint **placed on a PCB**; key `pcb_path` + `references[]` (world position, rotation, layer, properties, pads).
- `list_symbol_properties` — symbol **placed in a schematic**; key `schematic_path` + `references[]` (properties only, no geometry, position, or nets).
- `extract_schematic_netlist` — returns the **whole netlist**, including the placement of **every** placed symbol (`components[ref].units[n].position`, `rotation`, per-unit `body_bbox`, world-coordinate `pins`); not a cheap single-coordinate lookup.
- `find_component_connections` — placement and connections for a **single reference** (`project_path` + `component_ref`); returns only that reference's `component_info` (also with `units[n].position`), not the whole netlist.

### Project Tools

| Tool | Description |
|------|-------------|
| `list_projects` | Find and list all KiCad projects |
| `get_project_structure` | Get the structure and files of a KiCad project |
| `open_project` | Open a KiCad project in KiCad |

### Symbol Library

| Tool | Description |
|------|-------------|
| `sync_symbol_index` | Build or refresh the symbol library index |
| `get_symbol_sync_status` | Query symbol index build progress |
| `get_symbol_index_stats` | Get statistics about the symbol index |
| `list_symbol_libraries` | List all symbol libraries; `list_library_symbols` lists the symbols inside one library (keyed by `library_name`) |
| `search_library_symbols` | Full-text search across indexed symbols |
| `get_library_symbol` | Look up a symbol by library and name |
| `list_library_symbols` | List the symbols inside one library, keyed by `library_name`; `list_symbol_libraries` lists all libraries |
| `get_library_symbol_pins` | Get pin definitions for a symbol |
| `create_symbol_library` | Create a new `.kicad_sym` library (global 3rd-party or project-local) and register it in the library table |
| `delete_symbol_library` | Delete an empty symbol library (file, library-table entry, and index) |
| `add_symbols_to_library` | Copy symbols from a schematic's cached `lib_symbols` into an existing library |
| `remove_symbols_from_library` | Remove named symbol definitions from a library and re-index it |
| `update_library_symbol_pin` | Rename a pin number and/or pin name in a library symbol definition (format-preserving) |
| `find_symbols_not_in_libraries` | List schematic symbols that resolve to no available library (read-only) |

### Schematic Editing

| Tool | Description |
|------|-------------|
| `add_symbol_to_schematic` | Place a symbol on the schematic |
| `create_symbol` | Define a new symbol into a symbol library (definition only — no schematic placement) |
| `place_symbol_relative` | Place a symbol relative to an existing component |
| `remove_symbol_from_schematic` | Remove placed symbol by reference |
| `move_component` | Move and/or rotate a placed component |
| `set_symbol_property` | Set a property field on a placed symbol |
| `update_schematic_symbol_pin` | Rename a pin number and/or pin name in a schematic's cached `lib_symbols` copy |
| `update_schematic_symbol_from_library` | Refresh a schematic's cached `lib_symbols` definition from the library (graphics, pins, unit sub-symbols and definition properties; placements keep their fields) |
| `rename_symbol` | Rename a placed symbol's reference designator |
| `list_symbol_properties` | List properties (name → value) of placed schematic symbols — no geometry, position, or nets |
| `delete_symbol_property` | Delete a property from a placed symbol |
| `check_reference_conflicts` | Check for duplicate reference designators |
| `connect_points_with_wire` | Route a smart orthogonal wire between two points |
| `connect_pins_with_wire` | Connect two symbol pins with a wire |
| `delete_wire_from_schematic` | Remove wire segments by endpoints |
| `add_label_to_schematic` | Add a local net label |
| `list_labels_in_schematic` | List all local net labels |
| `delete_label_from_schematic` | Delete net labels |
| `add_no_connect` | Add a no-connect flag at a pin coordinate |
| `list_no_connects` | List all no-connect flags |
| `remove_no_connect` | Remove no-connect flag(s) by coordinate |
| `get_schematic_sheet_info` | Get drawing area, paper size, and grid |
| `find_free_area` | Find candidate areas for placing a block |

### Schematic Groups

| Tool | Description |
|------|-------------|
| `assign_symbols_to_group` | Assign symbols to a named placement group (stored as the `placement_group` property) |
| `list_symbol_groups` | List all symbol placement groups with member counts and bounding boxes |
| `get_symbol_group` | Get a group's members, positions, anchor and bounding box |
| `score_symbol_group` | Score intra-group spacing (mean nearest-neighbour distance and spread) |
| `place_symbol_group` | Arrange a group in a grid around its anchor and drop it in a free sheet area |
| `move_symbol_group` | Translate a whole group to a new anchor position, keeping its internal layout |
| `rotate_symbol_group` | Rotate a whole group rigidly around its anchor (counter-clockwise positive) |

### Schematic Analysis

| Tool | Description |
|------|-------------|
| `extract_schematic_netlist` | Extract netlist from a schematic |
| `find_component_connections` | Find all connections for a component |
| `run_erc` | Run Electrical Rules Check (headless `kicad-cli`) and return violations |
| `identify_circuit_patterns` | Identify common circuit patterns |
| `validate_project` | Basic validation of a KiCad project |

### Hierarchical Sheets

| Tool | Description |
|------|-------------|
| `list_sheet_symbols` | List all hierarchical sheet symbols in a schematic |
| `get_sheet_hierarchy` | Get the full sheet hierarchy tree |
| `add_sheet_symbol` | Add a new hierarchical sheet symbol |
| `remove_sheet_symbol` | Remove a sheet symbol (with optional child file deletion) |
| `update_sheet_symbol` | Update a sheet symbol's properties and geometry |
| `add_sheet_pin` | Add a hierarchical pin to a sheet symbol |
| `remove_sheet_pin` | Remove a hierarchical pin from a sheet symbol |

### PCB Library

| Tool | Description |
|------|-------------|
| `sync_footprint_index` | Build or refresh the footprint library index |
| `get_footprint_sync_status` | Query footprint index build progress |
| `list_footprint_libraries` | List all available footprint libraries |
| `search_library_footprints` | Search footprints by name, description, or tag |
| `get_library_footprint` | Get a footprint **library definition** (pads, bounding box, etc.) by library name + footprint name — not a board placement |
| `list_library_footprints` | List every footprint in one library (names and light metadata) (offset paging) |
| `find_footprints_not_in_libraries` | List board footprints missing from every indexed library |
| `create_footprint_library` | Create a global 3rdparty or project-local footprint library |
| `add_footprints_to_library` | Export explicitly named board footprints into a library |
| `delete_footprint_library` | Delete an empty footprint library (directory, library-table entry, and index) |
| `remove_footprints_from_library` | Remove named footprints from a footprint library and re-index it |

### PCB Query

| Tool | Description |
|------|-------------|
| `get_board_info` | Get basic PCB board information |
| `list_footprints` | List all footprints placed on the board |
| `get_footprint` | Get details of footprints **placed on the PCB**, one payload per reference in `references` (pads, properties, Edge.Cuts geometry) |
| `get_footprint_bbox` | Get the courtyard bounding box of a footprint |
| `get_board_bounding_box` | Get the union bounding box of all footprints |
| `list_nets` | List all nets on the board |
| `list_tracks` | List track segments and arcs grouped into traces, optionally filtered by net and layer |
| `list_vias` | List through-hole vias with position, size, drill, layers and net, optionally filtered by net |
| `get_ratsnest` | Get unrouted ratsnest connections |
| `score_placement` | Score the current PCB placement quality |
| `suggest_placement_order` | Get recommended footprint placement order |

### PCB Editing

| Tool | Description |
|------|-------------|
| `get_board_outline` | Read Edge.Cuts board outline elements |
| `clear_board_outline` | Clear the board outline |
| `add_board_outline_segment` | Add a line segment to the board outline |
| `add_board_outline_arc` | Add an arc to the board outline |
| `set_board_outline_rect` | Set a rectangular board outline (with optional rounded corners) |
| `set_footprint_property` | Set a property field on a footprint |
| `add_footprints_to_pcb` | Import footprints from footprint libraries onto the board at given positions, assigning every pad's net |
| `remove_footprints_from_pcb` | Remove footprints from the board by reference designator (batch) |
| `update_pcb_from_schematic` | Trigger *Update PCB from Schematic* via KiCad IPC |

### PCB Routing

| Tool | Description |
|------|-------------|
| `pcb_route_pad_to_pad` | Route a single track between two pads with the obstacle-avoiding router (PNS shove or grid A*), optionally across layers via through-vias |
| `pcb_add_vias` | Add one or more through-hole vias in a single write, pre-checked against netclass and clearance rules |
| `pcb_delete_tracks` | Delete track segments and arcs matched by their endpoint coordinates |
| `pcb_delete_vias` | Delete vias matched by their (x, y) position |

### PCB Placement

| Tool | Description |
|------|-------------|
| `set_footprint_position` | Move and/or rotate one or more footprints (via `items`) |
| `flip_footprint` | Flip a footprint between top and bottom layer |
| `align_footprints` | Align footprints to the same axis |
| `distribute_footprints` | Distribute footprints evenly along an axis |
| `move_footprints_by_delta` | Translate footprints by (dx, dy) |
| `find_free_pcb_area` | Find an area free of existing footprints |

### PCB Groups

| Tool | Description |
|------|-------------|
| `assign_footprints_to_group` | Assign footprints to a placement group |
| `list_footprint_groups` | List all placement groups on the board |
| `get_footprint_group` | Get details of a placement group |
| `score_footprint_group` | Score intra-group placement quality |
| `place_footprint_group` | Place all members of a group |
| `move_footprint_group` | Translate a placed group |
| `rotate_footprint_group` | Rotate a placed group around its anchor |

### PCB Zones

| Tool | Description |
|------|-------------|
| `list_zones` | List all copper-pour and keepout zones |
| `add_zone` | Add a copper-pour or keepout zone |
| `delete_zone` | Delete a zone by UUID |
| `refill_zones` | Refill all zones on the PCB |

### DRC & Design Rules

| Tool | Description |
|------|-------------|
| `get_effective_design_rules` | Get all design constraints (board rules, net classes, custom rules) |
| `set_design_rules` | Update board-level design rule minimums |
| `set_net_class_rules` | Create or update a net class's design parameters |
| `assign_nets_to_class` | Assign nets to a net class |
| `remove_nets_from_class` | Remove nets from a net class (revert to Default) |
| `delete_net_class` | Delete a net class |
| `add_custom_rule` | Add a custom DRC rule to the project |
| `del_custom_rule` | Delete a custom DRC rule by name |
| `run_drc_check` | Open the KiCad DRC dialog |
| `analyze_bom` | Analyze the bill of materials |
| `export_bom_csv` | Export the BOM to CSV |

### Versioning & Export

| Tool | Description |
|------|-------------|
| `save_project_version` | Save a project version archive (schematic+PCB+project file) |
| `list_project_versions` | List saved project version archives |
| `restore_project_version` | Restore project files together to a saved archive |
| `generate_pcb_thumbnail` | Render a PCB thumbnail image |
| `export_pcb_layer_image` | Render the board — or a single copper layer — as an image returned to the model; writes a PNG file only when `output_dir` is given |

### Skill System

| Tool | Description |
|------|-------------|
| `list_skills` | List all available skill documents |
| `get_skill` | Get the full content of a skill document |
| `add_skill` | Create a new skill document |
| `append_to_skill` | Append content to an existing skill |
| `delete_skill` | Soft-delete a skill document |

### KiCad IPC

| Tool | Description |
|------|-------------|
| `check_kicad_ipc_connection` | Check if the KiCad IPC socket is responsive |
| `save_document` | Save the active document in KiCad |
| `reload_kicad` | Reload documents in the running KiCad editor |

## Project Structure

```
kcaa/
├── main.py                  # MCP server entry point
├── pyproject.toml           # Package metadata and dependencies
├── run_tests.py             # Test runner script
├── kcaa/                    # MCP server package
│   ├── server.py            # Server setup and tool registration
│   ├── config.py            # Configuration and KiCad path detection
│   ├── context.py           # Request context management
│   ├── tools/               # All MCP tool implementations
│   ├── resources/           # MCP resource handlers
│   ├── prompts/             # MCP prompt templates
│   └── utils/               # Utility functions
├── kicad_plugin/            # KiCad action plugin
│   ├── __init__.py          # Plugin entry point (KiCadAIPlugin)
│   ├── server_manager.py    # Start/stop the kcaa subprocess
│   ├── llm_client.py        # Agentic tool-call loop (OpenAI / Anthropic)
│   ├── context_bridge.py    # Collect active project paths from KiCad
│   ├── settings.py          # Load/save plugin settings
│   ├── autorouter.py        # FreeRouting integration
│   ├── tool_registry.py     # Tool metadata and categorization
│   ├── setup_plugin.sh      # Linux/macOS setup script
│   ├── setup_plugin.ps1     # Windows PowerShell setup script
│   ├── setup_plugin.bat     # Windows batch setup script
│   └── ui/                  # wxPython chat panel and settings dialog
├── docs/                    # Feature documentation
└── tests/                   # Unit tests
```

## Troubleshooting

**Plugin does not appear in KiCad:**
- Manual install: confirm you used the documented folder name `<documents>/kicad/<ver>/scripting/plugins/kicad_ai_assistant` (the old instructions used `kicad_ai_plugin`) so the commands below work.
- PCM install: confirm `<documents>/kicad/<ver>/3rdparty/plugins/com_github_paul356_kicad-ai-assistant` exists and came from `kicad_ai_assistant_pcm.zip`.
- Run **Tools → External Plugins → Refresh Plugins** after installing.
- Linux: Check that `setup_plugin.sh` completed without errors and that `.venv/bin/python` exists inside the plugin directory.
- Windows: Check that `setup_plugin.bat` (or `setup_plugin.ps1`) completed without errors and that `.venv/Scripts/python.exe` exists inside the plugin directory.
- If the setup script failed, see [the setup troubleshooting entry](docs/troubleshooting.md#setup-script-fails-and-the-window-closes).

**MCP server fails to start:**
- Linux: Check the plugin log in `~/.config/kicad/` for Python tracebacks.
- Windows: Check the plugin log in `%APPDATA%/kicad/` for Python tracebacks.

**Schematic editor does not refresh after edits:**
- This is a current KiCad IPC limitation. Use **File → Reload** or press **Ctrl+Z / Ctrl+Y** to trigger a refresh in the schematic editor.

**LLM API errors:**
- Confirm the API key is correct in **Options → Settings**.
- Check that `llm_model` is a valid model name for your chosen provider.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add your changes with tests
4. Submit a pull request **against the `develop` branch**

> **PR requirements:**
> - One pull request should contain **only one** fix, enhancement, or
>   feature. If you have multiple independent changes, please submit them
>   as separate pull requests.
> - Include tests for your changes.

> **Branch policy:**
> - The `develop` branch is where new features are stabilized — please
>   submit your changes there first so they can be tested and reviewed.
> - The `main` branch is reserved for releasing versions. Changes are
>   merged from `develop` into `main` once they have passed testing.

## License

This project is open source under the MIT license.
