refactor readme and add more docs
This commit is contained in:
Lama
parent
6953e5dc9a
commit
f8bafe8beb
373
README.md
373
README.md
@ -1,6 +1,6 @@
|
|||||||
# KiCad MCP Server
|
# KiCad MCP Server
|
||||||
|
|
||||||
> ⚠️ **WARNING**: This project is a work in progress. The basic functionality of finding KiCad projects has been tested on macOS, but more advanced features (like running DRC checks, generating thumbnails) have not been thoroughly tested yet. If you encounter bugs, please open an issue or submit a pull request to fix them (see Contributing section below).
|
> ⚠️ **WARNING**: This project was quickly hacked together and is largely untested. Expect things to break. Use at your own risk. I plan on improving it over time, but if you find bugs, please open an issue or submit a pull request to fix them (see Contributing section below).
|
||||||
|
|
||||||
> ⚠️ **WARNING**: This project is optimized for Mac. While there exists some basic support for Windows and Linux, not all functionality is guaranteed to work.
|
> ⚠️ **WARNING**: This project is optimized for Mac. While there exists some basic support for Windows and Linux, not all functionality is guaranteed to work.
|
||||||
|
|
||||||
@ -9,31 +9,12 @@ This guide will help you set up a Model Context Protocol (MCP) server for KiCad.
|
|||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
- [Prerequisites](#prerequisites)
|
- [Prerequisites](#prerequisites)
|
||||||
- [Project Structure](#project-structure)
|
|
||||||
- [Installation Steps](#installation-steps)
|
- [Installation Steps](#installation-steps)
|
||||||
- [1. Set Up Your Python Environment](#1-set-up-your-python-environment)
|
|
||||||
- [2. Configure Your Environment](#2-configure-your-environment)
|
|
||||||
- [3. Run the Server](#3-run-the-server)
|
|
||||||
- [4. Configure an MCP Client](#4-configure-an-mcp-client)
|
|
||||||
- [5. Restart Your MCP Client](#5-restart-your-mcp-client)
|
|
||||||
- [Understanding MCP Components](#understanding-mcp-components)
|
- [Understanding MCP Components](#understanding-mcp-components)
|
||||||
- [Resources vs Tools vs Prompts](#resources-vs-tools-vs-prompts)
|
- [Feature Highlights](#feature-highlights)
|
||||||
- [Features and Usage Guide](#features-and-usage-guide)
|
- [Documentation](#documentation)
|
||||||
- [Project Management](#project-management)
|
- [Configuration](#configuration)
|
||||||
- [PCB Design Analysis](#pcb-design-analysis)
|
|
||||||
- [Design Rule Checking (DRC)](#design-rule-checking-drc)
|
|
||||||
- [PCB Visualization](#pcb-visualization)
|
|
||||||
- [Templates and Prompts](#templates-and-prompts)
|
|
||||||
- [Usage Examples](#usage-examples)
|
|
||||||
- [Example 1: Basic Project Workflow](#example-1-basic-project-workflow)
|
|
||||||
- [Example 2: Getting PCB Design Help](#example-2-getting-pcb-design-help)
|
|
||||||
- [Configuration Options](#configuration-options)
|
|
||||||
- [Key Configuration Options](#key-configuration-options)
|
|
||||||
- [Using Environment Variables Directly](#using-environment-variables-directly)
|
|
||||||
- [Using a .env File (Recommended)](#using-a-env-file-recommended)
|
|
||||||
- [Development Guide](#development-guide)
|
- [Development Guide](#development-guide)
|
||||||
- [Adding New Features](#adding-new-features)
|
|
||||||
- [Running Tests](#running-tests)
|
|
||||||
- [Troubleshooting](#troubleshooting)
|
- [Troubleshooting](#troubleshooting)
|
||||||
- [Contributing](#contributing)
|
- [Contributing](#contributing)
|
||||||
- [Future Development Ideas](#future-development-ideas)
|
- [Future Development Ideas](#future-development-ideas)
|
||||||
@ -46,31 +27,6 @@ This guide will help you set up a Model Context Protocol (MCP) server for KiCad.
|
|||||||
- Claude Desktop (or another MCP client)
|
- Claude Desktop (or another MCP client)
|
||||||
- Basic familiarity with the terminal
|
- Basic familiarity with the terminal
|
||||||
|
|
||||||
## Project Structure
|
|
||||||
|
|
||||||
The KiCad MCP Server is organized into a modular structure for better maintainability:
|
|
||||||
|
|
||||||
```
|
|
||||||
kicad-mcp/
|
|
||||||
├── README.md # Project documentation
|
|
||||||
├── main.py # Entry point that runs the server
|
|
||||||
├── requirements.txt # Python dependencies
|
|
||||||
├── .env.example # Example environment configuration
|
|
||||||
├── kicad_mcp/ # Main package directory
|
|
||||||
│ ├── __init__.py # Package initialization
|
|
||||||
│ ├── server.py # MCP server setup
|
|
||||||
│ ├── config.py # Configuration constants and settings
|
|
||||||
│ ├── context.py # Lifespan management and shared context
|
|
||||||
│ ├── resources/ # Resource handlers
|
|
||||||
│ ├── tools/ # Tool handlers
|
|
||||||
│ ├── prompts/ # Prompt templates
|
|
||||||
│ └── utils/ # Utility functions
|
|
||||||
├── docs/ # Documentation
|
|
||||||
│ ├── drc_guide.md # Design Rule Check guide
|
|
||||||
│ └── thumbnail_guide.md # PCB Thumbnail feature guide
|
|
||||||
└── tests/ # Unit tests
|
|
||||||
```
|
|
||||||
|
|
||||||
## Installation Steps
|
## Installation Steps
|
||||||
|
|
||||||
### 1. Set Up Your Python Environment
|
### 1. Set Up Your Python Environment
|
||||||
@ -108,8 +64,6 @@ In the `.env` file, add your custom project directories:
|
|||||||
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad
|
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad
|
||||||
```
|
```
|
||||||
|
|
||||||
This will tell the server to look for KiCad projects in your custom directories in addition to the standard KiCad user directory.
|
|
||||||
|
|
||||||
### 3. Run the Server
|
### 3. Run the Server
|
||||||
|
|
||||||
Once the environment is set up, you can run the server:
|
Once the environment is set up, you can run the server:
|
||||||
@ -122,12 +76,6 @@ python -m mcp.dev main.py
|
|||||||
python main.py
|
python main.py
|
||||||
```
|
```
|
||||||
|
|
||||||
The server will automatically detect KiCad projects in:
|
|
||||||
|
|
||||||
- The standard KiCad user directory (e.g., ~/Documents/KiCad)
|
|
||||||
- Any custom directories specified in your .env file
|
|
||||||
- Common project directories (automatically detected)
|
|
||||||
|
|
||||||
### 4. Configure an MCP Client
|
### 4. Configure an MCP Client
|
||||||
|
|
||||||
Now, let's configure Claude Desktop to use our MCP server:
|
Now, let's configure Claude Desktop to use our MCP server:
|
||||||
@ -138,7 +86,7 @@ Now, let's configure Claude Desktop to use our MCP server:
|
|||||||
# Create the directory if it doesn't exist
|
# Create the directory if it doesn't exist
|
||||||
mkdir -p ~/Library/Application\ Support/Claude
|
mkdir -p ~/Library/Application\ Support/Claude
|
||||||
|
|
||||||
# Edit the configuration file (or create it if it doesn't exist)
|
# Edit the configuration file
|
||||||
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -157,30 +105,11 @@ vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Replace `/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp` with the actual path to your project directory (e.g., `/Users/yourusername/Projects/kicad-mcp`).
|
Replace `/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp` with the actual path to your project directory.
|
||||||
|
|
||||||
#### Windows Configuration
|
|
||||||
|
|
||||||
On Windows, the configuration would look like:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"mcpServers": {
|
|
||||||
"kicad": {
|
|
||||||
"command": "C:\\Path\\To\\Your\\Project\\kicad-mcp\\venv\\Scripts\\python.exe",
|
|
||||||
"args": [
|
|
||||||
"C:\\Path\\To\\Your\\Project\\kicad-mcp\\main.py"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
The configuration should be stored in `%APPDATA%\Claude\claude_desktop_config.json`.
|
|
||||||
|
|
||||||
### 5. Restart Your MCP Client
|
### 5. Restart Your MCP Client
|
||||||
|
|
||||||
Close and reopen your MCP client (e.g., Claude Desktop) to load the new configuration. The KiCad server should appear in the tools dropdown menu or equivalent interface in your client.
|
Close and reopen your MCP client to load the new configuration.
|
||||||
|
|
||||||
## Understanding MCP Components
|
## Understanding MCP Components
|
||||||
|
|
||||||
@ -208,163 +137,30 @@ The Model Context Protocol (MCP) defines three primary ways to provide capabilit
|
|||||||
- Invoked by user choice (typically from a menu)
|
- Invoked by user choice (typically from a menu)
|
||||||
- Example: The `debug_pcb_issues` prompt helps users troubleshoot PCB problems
|
- Example: The `debug_pcb_issues` prompt helps users troubleshoot PCB problems
|
||||||
|
|
||||||
## Features and Usage Guide
|
## Feature Highlights
|
||||||
|
|
||||||
Here's how to use each of the key features of the KiCad MCP Server through any MCP-compatible client (examples show prompts for Claude Desktop, but the concepts apply to any MCP client):
|
The KiCad MCP Server provides several key features:
|
||||||
|
|
||||||
### Project Management
|
- **Project Management**: List, examine, and open KiCad projects
|
||||||
|
- **PCB Design Analysis**: Get insights about your PCB designs and schematics
|
||||||
|
- **BOM Management**: Analyze and export Bills of Materials
|
||||||
|
- **Design Rule Checking**: Run DRC checks and track your progress over time
|
||||||
|
- **PCB Visualization**: Generate visual representations of your PCB layouts
|
||||||
|
|
||||||
#### Listing Projects
|
For detailed usage guides, see the [documentation](#documentation).
|
||||||
|
|
||||||
To see all KiCad projects available on your system:
|
## Documentation
|
||||||
|
|
||||||
```
|
Detailed documentation for each feature is available in the `docs/` directory:
|
||||||
Could you list all my KiCad projects?
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will use the `kicad://projects` resource to display a formatted list of your KiCad projects, including their paths and last modified dates.
|
- [Project Management](docs/project_guide.md)
|
||||||
|
- [PCB Design Analysis](docs/analysis_guide.md)
|
||||||
|
- [Bill of Materials (BOM)](docs/bom_guide.md)
|
||||||
|
- [Design Rule Checking (DRC)](docs/drc_guide.md)
|
||||||
|
- [PCB Visualization](docs/thumbnail_guide.md)
|
||||||
|
- [Prompt Templates](docs/prompt_guide.md)
|
||||||
|
|
||||||
#### Project Details
|
## Configuration
|
||||||
|
|
||||||
To get details about a specific project:
|
|
||||||
|
|
||||||
```
|
|
||||||
Show me details about my KiCad project at /path/to/your/project.kicad_pro
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will display project information including available files, settings, and metadata.
|
|
||||||
|
|
||||||
#### Opening Projects
|
|
||||||
|
|
||||||
To open a KiCad project:
|
|
||||||
|
|
||||||
```
|
|
||||||
Can you open my KiCad project at /path/to/your/project.kicad_pro?
|
|
||||||
```
|
|
||||||
|
|
||||||
This will launch KiCad with the specified project open. Note that this requires KiCad to be properly installed.
|
|
||||||
|
|
||||||
### PCB Design Analysis
|
|
||||||
|
|
||||||
#### Validating Projects
|
|
||||||
|
|
||||||
To validate a KiCad project for issues:
|
|
||||||
|
|
||||||
```
|
|
||||||
Validate my KiCad project at /path/to/your/project.kicad_pro
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will check for missing files, incorrect formats, and other common issues.
|
|
||||||
|
|
||||||
#### Schematic Information
|
|
||||||
|
|
||||||
To extract information from a schematic:
|
|
||||||
|
|
||||||
```
|
|
||||||
What components are in my schematic at /path/to/your/project.kicad_sch?
|
|
||||||
```
|
|
||||||
|
|
||||||
This will display component information extracted from the schematic file.
|
|
||||||
|
|
||||||
### Design Rule Checking (DRC)
|
|
||||||
|
|
||||||
#### Running DRC Checks
|
|
||||||
|
|
||||||
To check your PCB layout for design rule violations:
|
|
||||||
|
|
||||||
```
|
|
||||||
Run a DRC check on my KiCad project at /path/to/your/project.kicad_pro
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will analyze your PCB layout for violations of design rules and provide a detailed report.
|
|
||||||
|
|
||||||
#### Viewing DRC History
|
|
||||||
|
|
||||||
To see how DRC violations have changed over time:
|
|
||||||
|
|
||||||
```
|
|
||||||
Show me the DRC history for my KiCad project at /path/to/your/project.kicad_pro
|
|
||||||
```
|
|
||||||
|
|
||||||
This displays a trend of violations over time, helping you track your progress as you fix issues.
|
|
||||||
|
|
||||||
DRC history is persistently stored on your filesystem at `~/.kicad_mcp/drc_history/` and is preserved across sessions. Each project's history is saved in a JSON file with a format like `projectname_[hash]_drc_history.json`. The system keeps track of up to 10 most recent DRC checks per project, allowing you to monitor your progress in fixing design rule violations over time.
|
|
||||||
|
|
||||||
#### Getting Help with DRC Violations
|
|
||||||
|
|
||||||
For help with fixing DRC issues, use the Fix DRC Violations prompt:
|
|
||||||
|
|
||||||
```
|
|
||||||
I need help fixing DRC violations in my KiCad project at /path/to/your/project.kicad_pro
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will guide you through understanding and resolving each type of violation.
|
|
||||||
|
|
||||||
### PCB Visualization
|
|
||||||
|
|
||||||
#### Generating PCB Thumbnails
|
|
||||||
|
|
||||||
To visualize your PCB layout:
|
|
||||||
|
|
||||||
```
|
|
||||||
Generate a thumbnail for my KiCad PCB at /path/to/your/project.kicad_pro
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will create a visual representation of your PCB board, showing layers, traces, and components.
|
|
||||||
|
|
||||||
### Templates and Prompts
|
|
||||||
|
|
||||||
#### Using Prompt Templates
|
|
||||||
|
|
||||||
Claude Desktop provides several specialized prompts for common KiCad workflows. Access these by clicking the "Prompt Templates" button in Claude Desktop, then selecting one of the KiCad templates:
|
|
||||||
|
|
||||||
- **Create New Component** - Guides you through creating a new KiCad component
|
|
||||||
- **Debug PCB Issues** - Helps troubleshoot common PCB design problems
|
|
||||||
- **PCB Manufacturing Checklist** - Prepares your design for manufacturing
|
|
||||||
- **Fix DRC Violations** - Assists with resolving design rule violations
|
|
||||||
- **Custom Design Rules** - Helps create specialized design rules for your project
|
|
||||||
|
|
||||||
## Usage Examples
|
|
||||||
|
|
||||||
Here are some complete examples of how to interact with the KiCad MCP Server through Claude Desktop:
|
|
||||||
|
|
||||||
### Example 1: Basic Project Workflow
|
|
||||||
|
|
||||||
```
|
|
||||||
Claude, I've just started a new KiCad project but I need some guidance. Can you list my existing KiCad projects first so I can see what I've already worked on?
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will list your KiCad projects. Then you might ask:
|
|
||||||
|
|
||||||
```
|
|
||||||
Great, can you show me details about the project at /Users/me/Documents/KiCad/amplifier/amplifier.kicad_pro?
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will display information about that specific project. Then you could continue:
|
|
||||||
|
|
||||||
```
|
|
||||||
I need to check if there are any design rule violations. Can you run a DRC check on that project?
|
|
||||||
```
|
|
||||||
|
|
||||||
### Example 2: Getting PCB Design Help
|
|
||||||
|
|
||||||
```
|
|
||||||
I'm having trouble with my PCB design in KiCad. I keep getting clearance errors between traces. Can you help me understand how to fix this?
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will explain clearance errors and suggest solutions. You could continue:
|
|
||||||
|
|
||||||
```
|
|
||||||
Can you show me a thumbnail of my PCB layout at /Users/me/Documents/KiCad/amplifier/amplifier.kicad_pro so I can see the problematic areas?
|
|
||||||
```
|
|
||||||
|
|
||||||
Claude will generate and display a thumbnail of your PCB. Then you might ask:
|
|
||||||
|
|
||||||
```
|
|
||||||
Let's run a full DRC check on this project to identify all the issues I need to fix.
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration Options
|
|
||||||
|
|
||||||
The KiCad MCP Server can be configured using environment variables or a `.env` file:
|
The KiCad MCP Server can be configured using environment variables or a `.env` file:
|
||||||
|
|
||||||
@ -374,36 +170,34 @@ The KiCad MCP Server can be configured using environment variables or a `.env` f
|
|||||||
| `KICAD_SEARCH_PATHS` | Comma-separated list of directories to search for KiCad projects | `~/pcb,~/Electronics,~/Projects` |
|
| `KICAD_SEARCH_PATHS` | Comma-separated list of directories to search for KiCad projects | `~/pcb,~/Electronics,~/Projects` |
|
||||||
| `KICAD_USER_DIR` | Override the default KiCad user directory | `~/Documents/KiCadProjects` |
|
| `KICAD_USER_DIR` | Override the default KiCad user directory | `~/Documents/KiCadProjects` |
|
||||||
| `KICAD_APP_PATH` | Override the default KiCad application path | `/Applications/KiCad7/KiCad.app` |
|
| `KICAD_APP_PATH` | Override the default KiCad application path | `/Applications/KiCad7/KiCad.app` |
|
||||||
| `LOG_LEVEL` | Set logging verbosity | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
|
|
||||||
| `LOG_DIR` | Directory for log files | `logs` or `~/.kicad_mcp/logs` |
|
|
||||||
|
|
||||||
### Using Environment Variables Directly
|
See [Configuration Guide](docs/configuration.md) for more details.
|
||||||
|
|
||||||
You can set environment variables when launching the server:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
KICAD_SEARCH_PATHS=~/pcb,~/Electronics LOG_LEVEL=DEBUG python main.py
|
|
||||||
```
|
|
||||||
|
|
||||||
### Using a .env File (Recommended)
|
|
||||||
|
|
||||||
Create a `.env` file in the project root with your configuration by copying and renaming `.env.example`:
|
|
||||||
|
|
||||||
```
|
|
||||||
# KiCad MCP Server Configuration
|
|
||||||
|
|
||||||
# Directories to search for KiCad projects (comma-separated)
|
|
||||||
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad
|
|
||||||
|
|
||||||
# Logging configuration
|
|
||||||
LOG_LEVEL=INFO
|
|
||||||
LOG_DIR=logs
|
|
||||||
```
|
|
||||||
|
|
||||||
The server automatically detects and loads this configuration on startup.
|
|
||||||
|
|
||||||
## Development Guide
|
## Development Guide
|
||||||
|
|
||||||
|
### Project Structure
|
||||||
|
|
||||||
|
The KiCad MCP Server is organized into a modular structure:
|
||||||
|
|
||||||
|
```
|
||||||
|
kicad-mcp/
|
||||||
|
├── README.md # Project documentation
|
||||||
|
├── main.py # Entry point that runs the server
|
||||||
|
├── requirements.txt # Python dependencies
|
||||||
|
├── .env.example # Example environment configuration
|
||||||
|
├── kicad_mcp/ # Main package directory
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ ├── server.py # MCP server setup
|
||||||
|
│ ├── config.py # Configuration constants and settings
|
||||||
|
│ ├── context.py # Lifespan management and shared context
|
||||||
|
│ ├── resources/ # Resource handlers
|
||||||
|
│ ├── tools/ # Tool handlers
|
||||||
|
│ ├── prompts/ # Prompt templates
|
||||||
|
│ └── utils/ # Utility functions
|
||||||
|
├── docs/ # Documentation
|
||||||
|
└── tests/ # Unit tests
|
||||||
|
```
|
||||||
|
|
||||||
### Adding New Features
|
### Adding New Features
|
||||||
|
|
||||||
To add new features to the KiCad MCP Server, follow these steps:
|
To add new features to the KiCad MCP Server, follow these steps:
|
||||||
@ -413,36 +207,14 @@ To add new features to the KiCad MCP Server, follow these steps:
|
|||||||
3. Register your feature in the corresponding register function
|
3. Register your feature in the corresponding register function
|
||||||
4. Test your changes with the development tools
|
4. Test your changes with the development tools
|
||||||
|
|
||||||
Example for adding a new tool:
|
See [Development Guide](docs/development.md) for more details.
|
||||||
|
|
||||||
```python
|
|
||||||
# kicad_mcp/tools/analysis_tools.py
|
|
||||||
|
|
||||||
@mcp.tool()
|
|
||||||
def new_analysis_tool(project_path: str) -> Dict[str, Any]:
|
|
||||||
"""Description of your new tool."""
|
|
||||||
# Implementation goes here
|
|
||||||
return {"result": "success"}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Running Tests
|
|
||||||
|
|
||||||
This project uses pytest for testing:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Install development dependencies
|
|
||||||
pip install pytest
|
|
||||||
|
|
||||||
# Run tests
|
|
||||||
pytest
|
|
||||||
```
|
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
If you encounter issues:
|
If you encounter issues:
|
||||||
|
|
||||||
1. **Server Not Appearing in MCP Client:**
|
1. **Server Not Appearing in MCP Client:**
|
||||||
- Check your client's configuration file for errors (e.g., `claude_desktop_config.json` for Claude Desktop)
|
- Check your client's configuration file for errors
|
||||||
- Make sure the path to your project and Python interpreter is correct
|
- Make sure the path to your project and Python interpreter is correct
|
||||||
- Ensure Python can access the `mcp` package
|
- Ensure Python can access the `mcp` package
|
||||||
- Check if your KiCad installation is detected
|
- Check if your KiCad installation is detected
|
||||||
@ -452,24 +224,13 @@ If you encounter issues:
|
|||||||
- Check Claude logs at:
|
- Check Claude logs at:
|
||||||
- `~/Library/Logs/Claude/mcp-server-kicad.log` (server-specific logs)
|
- `~/Library/Logs/Claude/mcp-server-kicad.log` (server-specific logs)
|
||||||
- `~/Library/Logs/Claude/mcp.log` (general MCP logs)
|
- `~/Library/Logs/Claude/mcp.log` (general MCP logs)
|
||||||
- Make sure all required Python packages are installed
|
|
||||||
- Verify that your KiCad installation is in the standard location
|
|
||||||
|
|
||||||
3. **KiCad Python Modules Not Found:**
|
3. **Working Directory Issues:**
|
||||||
- This is a common issue. The server will still work but with limited functionality
|
- The working directory for servers launched via client configs may be undefined
|
||||||
- Ensure KiCad is installed properly
|
- Always use absolute paths in your configuration and .env files
|
||||||
- Check if the right paths are set in `kicad_mcp/config.py`
|
- For testing servers via command line, the working directory will be where you run the command
|
||||||
|
|
||||||
4. **Projects Not Found:**
|
|
||||||
- Check your `.env` file to ensure your project directories are correctly specified
|
|
||||||
- Verify the paths exist and have KiCad project files (.kicad_pro)
|
|
||||||
- Use absolute paths instead of `~` if there are issues with path expansion
|
|
||||||
- Check the Claude logs mentioned above to see if there are errors when searching for projects
|
|
||||||
|
|
||||||
5. **DRC History Not Saving:**
|
See [Troubleshooting Guide](docs/troubleshooting.md) for more details.
|
||||||
- Check if the `~/.kicad_mcp/drc_history/` directory exists and is writable
|
|
||||||
- Verify that the project path used is consistent between runs
|
|
||||||
- Check for errors in the logs related to DRC history saving
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
@ -480,25 +241,21 @@ Want to contribute to the KiCad MCP Server? Here's how you can help improve this
|
|||||||
3. Add your changes
|
3. Add your changes
|
||||||
4. Submit a pull request
|
4. Submit a pull request
|
||||||
|
|
||||||
Key areas that need work:
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
|
||||||
- Improving cross-platform compatibility
|
|
||||||
- Adding more comprehensive tests
|
|
||||||
- Enhancing error handling
|
|
||||||
- Adding support for more KiCad features
|
|
||||||
|
|
||||||
## Future Development Ideas
|
## Future Development Ideas
|
||||||
|
|
||||||
Interested in contributing? Here are some ideas for future development:
|
Interested in contributing? Here are some ideas for future development:
|
||||||
|
|
||||||
1. Implement 3D model visualization tools
|
1. **3D Model Visualization** - Implement tools to visualize 3D models of PCBs
|
||||||
2. Create PCB review tools with annotations
|
2. **PCB Review Tools** - Create annotation features for design reviews
|
||||||
3. Add support for generating manufacturing files
|
3. **Manufacturing File Generation** - Add support for generating Gerber files and other manufacturing outputs
|
||||||
4. Implement component search tools
|
4. **Component Search** - Implement search functionality for components across KiCad libraries
|
||||||
5. Enhance BOM capabilities with supplier integration
|
5. **BOM Enhancement** - Add supplier integration for component sourcing and pricing
|
||||||
6. Add support for interactive design checks
|
6. **Interactive Design Checks** - Develop interactive tools for checking design quality
|
||||||
7. Implement a simple web UI for configuration and monitoring
|
7. **Web UI** - Create a simple web interface for configuration and monitoring
|
||||||
8. Add automated circuit analysis features
|
8. **Circuit Analysis** - Add automated circuit analysis features
|
||||||
9. Add tests!
|
9. **Test Coverage** - Improve test coverage across the codebase
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|||||||
188
docs/analysis_guide.md
Normal file
188
docs/analysis_guide.md
Normal file
@ -0,0 +1,188 @@
|
|||||||
|
# KiCad PCB Design Analysis Guide
|
||||||
|
|
||||||
|
This guide explains how to use the PCB design analysis features in the KiCad MCP Server.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The PCB design analysis functionality allows you to:
|
||||||
|
|
||||||
|
1. Extract and analyze information from schematics
|
||||||
|
2. Validate projects for completeness and correctness
|
||||||
|
3. Get insights about components and connections
|
||||||
|
4. Understand PCB layout characteristics
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Task | Example Prompt |
|
||||||
|
|------|---------------|
|
||||||
|
| Get schematic info | `What components are in my schematic at /path/to/project.kicad_sch?` |
|
||||||
|
| Validate project | `Validate my KiCad project at /path/to/project.kicad_pro` |
|
||||||
|
| Analyze PCB | `Analyze the PCB layout at /path/to/project.kicad_pcb` |
|
||||||
|
|
||||||
|
## Using PCB Analysis Features
|
||||||
|
|
||||||
|
### Schematic Information
|
||||||
|
|
||||||
|
To extract information from a schematic:
|
||||||
|
|
||||||
|
```
|
||||||
|
What components are in my schematic at /path/to/project.kicad_sch?
|
||||||
|
```
|
||||||
|
|
||||||
|
This will provide:
|
||||||
|
- A list of all components in the schematic
|
||||||
|
- Component values and footprints
|
||||||
|
- Connection information
|
||||||
|
- Basic schematic structure
|
||||||
|
|
||||||
|
Example output:
|
||||||
|
```
|
||||||
|
# Schematic: my_project.kicad_sch
|
||||||
|
|
||||||
|
## Components (Estimated Count: 42)
|
||||||
|
|
||||||
|
(symbol (lib_id "Device:R") (at 127 87.63 0) (unit 1)
|
||||||
|
(symbol (lib_id "Device:C") (at 142.24 90.17 0) (unit 1)
|
||||||
|
(symbol (lib_id "MCU_Microchip_ATmega:ATmega328P-PU") (at 170.18 88.9 0) (unit 1)
|
||||||
|
|
||||||
|
... and 39 more components
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Validation
|
||||||
|
|
||||||
|
To check a project for issues:
|
||||||
|
|
||||||
|
```
|
||||||
|
Validate my KiCad project at /path/to/project.kicad_pro
|
||||||
|
```
|
||||||
|
|
||||||
|
The validation checks for:
|
||||||
|
- Missing project files
|
||||||
|
- Required components (schematic, PCB)
|
||||||
|
- Valid file formats
|
||||||
|
- Common structural issues
|
||||||
|
|
||||||
|
This is useful for identifying problems before opening files in KiCad.
|
||||||
|
|
||||||
|
### PCB Layout Analysis
|
||||||
|
|
||||||
|
To analyze a PCB layout:
|
||||||
|
|
||||||
|
```
|
||||||
|
Analyze the PCB layout at /path/to/project.kicad_pcb
|
||||||
|
```
|
||||||
|
|
||||||
|
This will provide information about:
|
||||||
|
- Board dimensions
|
||||||
|
- Layer structure
|
||||||
|
- Component placement
|
||||||
|
- Trace characteristics
|
||||||
|
- Via usage
|
||||||
|
|
||||||
|
## Available Resources
|
||||||
|
|
||||||
|
The server provides several resources for accessing design information:
|
||||||
|
|
||||||
|
- `kicad://schematic/{schematic_path}` - Information from a schematic file
|
||||||
|
- `kicad://pcb/{pcb_path}` - Information from a PCB file
|
||||||
|
|
||||||
|
These resources can be accessed programmatically by other MCP clients or directly referenced in conversations.
|
||||||
|
|
||||||
|
## Tips for Better Analysis
|
||||||
|
|
||||||
|
### Focus on Specific Elements
|
||||||
|
|
||||||
|
You can ask for analysis of specific aspects of your design:
|
||||||
|
|
||||||
|
```
|
||||||
|
What are all the resistor values in my schematic at /path/to/project.kicad_sch?
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
Show me all the power connections in my schematic at /path/to/project.kicad_sch
|
||||||
|
```
|
||||||
|
|
||||||
|
### Integration with Other Features
|
||||||
|
|
||||||
|
Combine analysis with other features for better insights:
|
||||||
|
|
||||||
|
1. Analyze a schematic first to understand component selection
|
||||||
|
2. Check the BOM for component availability and cost
|
||||||
|
3. Run DRC checks to find design rule violations
|
||||||
|
4. View the PCB thumbnail for a visual overview
|
||||||
|
|
||||||
|
## Common Analysis Tasks
|
||||||
|
|
||||||
|
### Finding Specific Components
|
||||||
|
|
||||||
|
To locate components in your schematic:
|
||||||
|
|
||||||
|
```
|
||||||
|
Find all decoupling capacitors in my schematic at /path/to/project.kicad_sch
|
||||||
|
```
|
||||||
|
|
||||||
|
This helps with understanding component usage and ensuring proper design practices.
|
||||||
|
|
||||||
|
### Identifying Signal Paths
|
||||||
|
|
||||||
|
To trace signals through your design:
|
||||||
|
|
||||||
|
```
|
||||||
|
Trace the clock signal path in my schematic at /path/to/project.kicad_sch
|
||||||
|
```
|
||||||
|
|
||||||
|
This helps with understanding signal flow and potential issues.
|
||||||
|
|
||||||
|
### Board Metrics
|
||||||
|
|
||||||
|
To get metrics about your PCB:
|
||||||
|
|
||||||
|
```
|
||||||
|
What are the dimensions of my PCB at /path/to/project.kicad_pcb?
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
How many vias are in my PCB at /path/to/project.kicad_pcb?
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Schematic Reading Errors
|
||||||
|
|
||||||
|
If the server can't read your schematic:
|
||||||
|
|
||||||
|
1. Verify the file exists and has the correct extension (.kicad_sch)
|
||||||
|
2. Check if the file is a valid KiCad schematic
|
||||||
|
3. Ensure you have read permissions for the file
|
||||||
|
4. Try the analysis on a simpler schematic to isolate the issue
|
||||||
|
|
||||||
|
### PCB Analysis Issues
|
||||||
|
|
||||||
|
If PCB analysis fails:
|
||||||
|
|
||||||
|
1. Check if the PCB file exists and has the correct extension (.kicad_pcb)
|
||||||
|
2. Ensure the PCB file is not corrupted
|
||||||
|
3. Check for complex features that might cause parsing issues
|
||||||
|
4. Try a simplified PCB to isolate the problem
|
||||||
|
|
||||||
|
## Advanced Usage
|
||||||
|
|
||||||
|
### Design Reviews
|
||||||
|
|
||||||
|
Use the analysis features for comprehensive design reviews:
|
||||||
|
|
||||||
|
```
|
||||||
|
Review the power distribution network in my schematic at /path/to/project.kicad_sch
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
Check my PCB at /path/to/project.kicad_pcb for potential EMI issues
|
||||||
|
```
|
||||||
|
|
||||||
|
### Custom Analysis Scripts
|
||||||
|
|
||||||
|
For advanced users:
|
||||||
|
|
||||||
|
1. Use the schematic and PCB analysis tools to extract data
|
||||||
|
2. Ask for specific analytical insights on that data
|
||||||
|
3. Request recommendations based on the analysis
|
||||||
207
docs/analysis_guide.me
Normal file
207
docs/analysis_guide.me
Normal file
@ -0,0 +1,207 @@
|
|||||||
|
# KiCad PCB Design Analysis Guide
|
||||||
|
|
||||||
|
This guide explains how to use the PCB design analysis features in the KiCad MCP Server.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The PCB design analysis functionality allows you to:
|
||||||
|
|
||||||
|
1. Extract and analyze information from schematics
|
||||||
|
2. Validate projects for completeness and correctness
|
||||||
|
3. Get insights about components and connections
|
||||||
|
4. Understand PCB layout characteristics
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Task | Example Prompt |
|
||||||
|
|------|---------------|
|
||||||
|
| Get schematic info | `What components are in my schematic at /path/to/project.kicad_sch?` |
|
||||||
|
| Validate project | `Validate my KiCad project at /path/to/project.kicad_pro` |
|
||||||
|
| Analyze PCB | `Analyze the PCB layout at /path/to/project.kicad_pcb` |
|
||||||
|
|
||||||
|
## Using PCB Analysis Features
|
||||||
|
|
||||||
|
### Schematic Information
|
||||||
|
|
||||||
|
To extract information from a schematic:
|
||||||
|
|
||||||
|
```
|
||||||
|
What components are in my schematic at /path/to/project.kicad_sch?
|
||||||
|
```
|
||||||
|
|
||||||
|
This will provide:
|
||||||
|
- A list of all components in the schematic
|
||||||
|
- Component values and footprints
|
||||||
|
- Connection information
|
||||||
|
- Basic schematic structure
|
||||||
|
|
||||||
|
Example output:
|
||||||
|
```
|
||||||
|
# Schematic: my_project.kicad_sch
|
||||||
|
|
||||||
|
## Components (Estimated Count: 42)
|
||||||
|
|
||||||
|
(symbol (lib_id "Device:R") (at 127 87.63 0) (unit 1)
|
||||||
|
(symbol (lib_id "Device:C") (at 142.24 90.17 0) (unit 1)
|
||||||
|
(symbol (lib_id "MCU_Microchip_ATmega:ATmega328P-PU") (at 170.18 88.9 0) (unit 1)
|
||||||
|
|
||||||
|
... and 39 more components
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Validation
|
||||||
|
|
||||||
|
To check a project for issues:
|
||||||
|
|
||||||
|
```
|
||||||
|
Validate my KiCad project at /path/to/project.kicad_pro
|
||||||
|
```
|
||||||
|
|
||||||
|
The validation checks for:
|
||||||
|
- Missing project files
|
||||||
|
- Required components (schematic, PCB)
|
||||||
|
- Valid file formats
|
||||||
|
- Common structural issues
|
||||||
|
|
||||||
|
This is useful for identifying problems before opening files in KiCad.
|
||||||
|
|
||||||
|
### PCB Layout Analysis
|
||||||
|
|
||||||
|
To analyze a PCB layout:
|
||||||
|
|
||||||
|
```
|
||||||
|
Analyze the PCB layout at /path/to/project.kicad_pcb
|
||||||
|
```
|
||||||
|
|
||||||
|
This will provide information about:
|
||||||
|
- Board dimensions
|
||||||
|
- Layer structure
|
||||||
|
- Component placement
|
||||||
|
- Trace characteristics
|
||||||
|
- Via usage
|
||||||
|
|
||||||
|
## Available Resources
|
||||||
|
|
||||||
|
The server provides several resources for accessing design information:
|
||||||
|
|
||||||
|
- `kicad://schematic/{schematic_path}` - Information from a schematic file
|
||||||
|
- `kicad://pcb/{pcb_path}` - Information from a PCB file
|
||||||
|
|
||||||
|
These resources can be accessed programmatically by other MCP clients or directly referenced in conversations.
|
||||||
|
|
||||||
|
## Tips for Better Analysis
|
||||||
|
|
||||||
|
### Focus on Specific Elements
|
||||||
|
|
||||||
|
You can ask for analysis of specific aspects of your design:
|
||||||
|
|
||||||
|
```
|
||||||
|
What are all the resistor values in my schematic at /path/to/project.kicad_sch?
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
Show me all the power connections in my schematic at /path/to/project.kicad_sch
|
||||||
|
```
|
||||||
|
|
||||||
|
### Integration with Other Features
|
||||||
|
|
||||||
|
Combine analysis with other features for better insights:
|
||||||
|
|
||||||
|
1. Analyze a schematic first to understand component selection
|
||||||
|
2. Check the BOM for component availability and cost
|
||||||
|
3. Run DRC checks to find design rule violations
|
||||||
|
4. View the PCB thumbnail for a visual overview
|
||||||
|
|
||||||
|
## Common Analysis Tasks
|
||||||
|
|
||||||
|
### Finding Specific Components
|
||||||
|
|
||||||
|
To locate components in your schematic:
|
||||||
|
|
||||||
|
```
|
||||||
|
Find all decoupling capacitors in my schematic at /path/to/project.kicad_sch
|
||||||
|
```
|
||||||
|
|
||||||
|
This helps with understanding component usage and ensuring proper design practices.
|
||||||
|
|
||||||
|
### Identifying Signal Paths
|
||||||
|
|
||||||
|
To trace signals through your design:
|
||||||
|
|
||||||
|
```
|
||||||
|
Trace the clock signal path in my schematic at /path/to/project.kicad_sch
|
||||||
|
```
|
||||||
|
|
||||||
|
This helps with understanding signal flow and potential issues.
|
||||||
|
|
||||||
|
### Board Metrics
|
||||||
|
|
||||||
|
To get metrics about your PCB:
|
||||||
|
|
||||||
|
```
|
||||||
|
What are the dimensions of my PCB at /path/to/project.kicad_pcb?
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
How many vias are in my PCB at /path/to/project.kicad_pcb?
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Schematic Reading Errors
|
||||||
|
|
||||||
|
If the server can't read your schematic:
|
||||||
|
|
||||||
|
1. Verify the file exists and has the correct extension (.kicad_sch)
|
||||||
|
2. Check if the file is a valid KiCad schematic
|
||||||
|
3. Ensure you have read permissions for the file
|
||||||
|
4. Try the analysis on a simpler schematic to isolate the issue
|
||||||
|
|
||||||
|
### PCB Analysis Issues
|
||||||
|
|
||||||
|
If PCB analysis fails:
|
||||||
|
|
||||||
|
1. Check if the PCB file exists and has the correct extension (.kicad_pcb)
|
||||||
|
2. Ensure the PCB file is not corrupted
|
||||||
|
3. Check for complex features that might cause parsing issues
|
||||||
|
4. Try a simplified PCB to isolate the problem
|
||||||
|
|
||||||
|
## Advanced Usage
|
||||||
|
|
||||||
|
### Design Reviews
|
||||||
|
|
||||||
|
Use the analysis features for comprehensive design reviews:
|
||||||
|
|
||||||
|
```
|
||||||
|
Review the power distribution network in my schematic at /path/to/project.kicad_sch
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
Check my PCB at /path/to/project.kicad_pcb for potential EMI issues
|
||||||
|
```
|
||||||
|
|
||||||
|
### Custom Analysis Scripts
|
||||||
|
|
||||||
|
For advanced users:
|
||||||
|
|
||||||
|
1. Use the schematic and PCB analysis tools to extract data
|
||||||
|
2. Ask for specific analytical insights on that data
|
||||||
|
3. Request recommendations based on the analysis
|
||||||
|
|
||||||
|
## Limitations
|
||||||
|
|
||||||
|
The current analysis capabilities have some limitations:
|
||||||
|
|
||||||
|
1. **Complexity limits**: Very large or complex designs may not be fully analyzed
|
||||||
|
2. **KiCad version compatibility**: Best results with the same KiCad version as the server
|
||||||
|
3. **Limited semantic understanding**: The analysis is primarily structural rather than functional
|
||||||
|
4. **No simulation capabilities**: The server cannot perform electrical simulation
|
||||||
|
|
||||||
|
## Future Improvements
|
||||||
|
|
||||||
|
Future versions of the KiCad MCP Server aim to enhance the analysis capabilities with:
|
||||||
|
|
||||||
|
1. More detailed component information extraction
|
||||||
|
2. Better understanding of circuit functionality
|
||||||
|
3. Enhanced power and signal analysis
|
||||||
|
4. Integration with KiCad's ERC and DRC engines
|
||||||
|
5. Support for hierarchical schematics
|
||||||
240
docs/configuration.md
Normal file
240
docs/configuration.md
Normal file
@ -0,0 +1,240 @@
|
|||||||
|
# Configuration Guide
|
||||||
|
|
||||||
|
This guide explains how to configure the KiCad MCP Server to suit your environment and requirements.
|
||||||
|
|
||||||
|
## Configuration Methods
|
||||||
|
|
||||||
|
The KiCad MCP Server can be configured in multiple ways:
|
||||||
|
|
||||||
|
1. **Environment Variables**: Set directly when running the server
|
||||||
|
2. **.env File**: Create a `.env` file in the project root (recommended)
|
||||||
|
3. **Code Modifications**: Edit configuration constants in `kicad_mcp/config.py`
|
||||||
|
|
||||||
|
## Core Configuration Options
|
||||||
|
|
||||||
|
### Project Paths
|
||||||
|
|
||||||
|
These settings control where the server looks for KiCad projects:
|
||||||
|
|
||||||
|
| Environment Variable | Description | Default Value | Example |
|
||||||
|
|---------------------|-------------|---------------|---------|
|
||||||
|
| `KICAD_USER_DIR` | The main KiCad user directory | `~/Documents/KiCad` (macOS/Windows)<br>`~/kicad` (Linux) | `~/Documents/KiCadProjects` |
|
||||||
|
| `KICAD_SEARCH_PATHS` | Additional directories to search for KiCad projects (comma-separated) | None | `~/pcb,~/Electronics,~/Projects/KiCad` |
|
||||||
|
|
||||||
|
### Application Paths
|
||||||
|
|
||||||
|
These settings control how the server locates KiCad:
|
||||||
|
|
||||||
|
| Environment Variable | Description | Default Value | Example |
|
||||||
|
|---------------------|-------------|---------------|---------|
|
||||||
|
| `KICAD_APP_PATH` | Path to the KiCad application | `/Applications/KiCad/KiCad.app` (macOS)<br>`C:\Program Files\KiCad` (Windows)<br>`/usr/share/kicad` (Linux) | `/Applications/KiCad7/KiCad.app` |
|
||||||
|
|
||||||
|
### Logging Configuration
|
||||||
|
|
||||||
|
These settings control server logging behavior:
|
||||||
|
|
||||||
|
| Environment Variable | Description | Default Value | Example |
|
||||||
|
|---------------------|-------------|---------------|---------|
|
||||||
|
| `LOG_LEVEL` | Sets logging verbosity | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
|
||||||
|
| `LOG_DIR` | Directory for log files | `logs` | `~/.kicad_mcp/logs` |
|
||||||
|
|
||||||
|
## Using a .env File (Recommended)
|
||||||
|
|
||||||
|
The recommended way to configure the server is by creating a `.env` file in the project root:
|
||||||
|
|
||||||
|
1. Copy the example file:
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Edit the `.env` file:
|
||||||
|
```bash
|
||||||
|
vim .env
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Add your configuration:
|
||||||
|
```
|
||||||
|
# KiCad MCP Server Configuration
|
||||||
|
|
||||||
|
# KiCad User Directory (where KiCad stores project files)
|
||||||
|
KICAD_USER_DIR=~/Documents/KiCad
|
||||||
|
|
||||||
|
# Additional directories to search for KiCad projects (comma-separated)
|
||||||
|
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad
|
||||||
|
|
||||||
|
# KiCad application path (needed for opening projects and command-line tools)
|
||||||
|
# macOS:
|
||||||
|
KICAD_APP_PATH=/Applications/KiCad/KiCad.app
|
||||||
|
# Windows:
|
||||||
|
# KICAD_APP_PATH=C:\Program Files\KiCad
|
||||||
|
# Linux:
|
||||||
|
# KICAD_APP_PATH=/usr/share/kicad
|
||||||
|
|
||||||
|
# Logging configuration
|
||||||
|
LOG_LEVEL=INFO
|
||||||
|
LOG_DIR=logs
|
||||||
|
```
|
||||||
|
|
||||||
|
## Directory Structure and Project Discovery
|
||||||
|
|
||||||
|
The server automatically searches for KiCad projects in:
|
||||||
|
|
||||||
|
1. The **KiCad user directory** (`KICAD_USER_DIR`)
|
||||||
|
2. Any **additional search paths** specified in `KICAD_SEARCH_PATHS`
|
||||||
|
3. **Common project locations** (auto-detected, including `~/Documents/PCB`, `~/Electronics`, etc.)
|
||||||
|
|
||||||
|
Projects are identified by the `.kicad_pro` file extension. The server recursively searches all configured directories to find KiCad projects.
|
||||||
|
|
||||||
|
## Client Configuration
|
||||||
|
|
||||||
|
### Claude Desktop Configuration
|
||||||
|
|
||||||
|
To configure Claude Desktop to use the KiCad MCP Server:
|
||||||
|
|
||||||
|
1. Create or edit the configuration file:
|
||||||
|
|
||||||
|
**macOS**:
|
||||||
|
```bash
|
||||||
|
mkdir -p ~/Library/Application\ Support/Claude
|
||||||
|
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
||||||
|
```
|
||||||
|
|
||||||
|
**Windows**:
|
||||||
|
```
|
||||||
|
mkdir -p %APPDATA%\Claude
|
||||||
|
notepad %APPDATA%\Claude\claude_desktop_config.json
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Add the server configuration:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"kicad": {
|
||||||
|
"command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/venv/bin/python",
|
||||||
|
"args": [
|
||||||
|
"/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
3. For Windows, use the appropriate path format:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"kicad": {
|
||||||
|
"command": "C:\\Path\\To\\Your\\Project\\kicad-mcp\\venv\\Scripts\\python.exe",
|
||||||
|
"args": [
|
||||||
|
"C:\\Path\\To\\Your\\Project\\kicad-mcp\\main.py"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Environment Variables in Client Configuration
|
||||||
|
|
||||||
|
You can also set environment variables directly in the client configuration:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"kicad": {
|
||||||
|
"command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/venv/bin/python",
|
||||||
|
"args": [
|
||||||
|
"/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py"
|
||||||
|
],
|
||||||
|
"env": {
|
||||||
|
"KICAD_SEARCH_PATHS": "/custom/path1,/custom/path2",
|
||||||
|
"LOG_LEVEL": "DEBUG"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Advanced Configuration
|
||||||
|
|
||||||
|
### Custom KiCad Extensions
|
||||||
|
|
||||||
|
If you need to modify the recognized KiCad file extensions, you can edit `kicad_mcp/config.py`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# File extensions
|
||||||
|
KICAD_EXTENSIONS = {
|
||||||
|
"project": ".kicad_pro",
|
||||||
|
"pcb": ".kicad_pcb",
|
||||||
|
"schematic": ".kicad_sch",
|
||||||
|
# Add or modify extensions as needed
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### DRC History Configuration
|
||||||
|
|
||||||
|
The server stores DRC history to track changes over time. By default, history is stored in:
|
||||||
|
|
||||||
|
- macOS/Linux: `~/.kicad_mcp/drc_history/`
|
||||||
|
- Windows: `%APPDATA%\kicad_mcp\drc_history\`
|
||||||
|
|
||||||
|
You can modify this in `kicad_mcp/utils/drc_history.py` if needed.
|
||||||
|
|
||||||
|
### Python Path for KiCad Modules
|
||||||
|
|
||||||
|
The server attempts to locate and add KiCad's Python modules to the Python path automatically. If this fails, you can modify the search paths in `kicad_mcp/utils/python_path.py`.
|
||||||
|
|
||||||
|
## Platform-Specific Configuration
|
||||||
|
|
||||||
|
### macOS
|
||||||
|
|
||||||
|
On macOS, KiCad is typically installed in `/Applications/KiCad/KiCad.app`. If you have multiple versions or a non-standard installation, set:
|
||||||
|
|
||||||
|
```
|
||||||
|
KICAD_APP_PATH=/path/to/your/KiCad.app
|
||||||
|
```
|
||||||
|
|
||||||
|
### Windows
|
||||||
|
|
||||||
|
On Windows, KiCad is typically installed in `C:\Program Files\KiCad`. If you have a different installation location, set:
|
||||||
|
|
||||||
|
```
|
||||||
|
KICAD_APP_PATH=D:\Software\KiCad
|
||||||
|
```
|
||||||
|
|
||||||
|
For paths in the `.env` file on Windows, you can use either:
|
||||||
|
- Forward slashes: `KICAD_SEARCH_PATHS=C:/Users/Username/Documents/KiCad`
|
||||||
|
- Escaped backslashes: `KICAD_SEARCH_PATHS=C:\\Users\\Username\\Documents\\KiCad`
|
||||||
|
|
||||||
|
### Linux
|
||||||
|
|
||||||
|
On Linux, KiCad's location varies by distribution. Common paths include:
|
||||||
|
- `/usr/share/kicad`
|
||||||
|
- `/usr/local/share/kicad`
|
||||||
|
- `/opt/kicad`
|
||||||
|
|
||||||
|
Set the appropriate path in your configuration:
|
||||||
|
|
||||||
|
```
|
||||||
|
KICAD_APP_PATH=/opt/kicad
|
||||||
|
```
|
||||||
|
|
||||||
|
## Debugging Configuration Issues
|
||||||
|
|
||||||
|
If you're having configuration problems:
|
||||||
|
|
||||||
|
1. Run the server with debug logging:
|
||||||
|
```bash
|
||||||
|
LOG_LEVEL=DEBUG python main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Check the logs for configuration-related messages:
|
||||||
|
```bash
|
||||||
|
cat logs/kicad_mcp_*.log | grep "config"
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Verify environment variables are being loaded:
|
||||||
|
```bash
|
||||||
|
python -c "import os; print(os.environ.get('KICAD_SEARCH_PATHS', 'Not set'))"
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Try absolute paths to eliminate path resolution issues
|
||||||
281
docs/development.md
Normal file
281
docs/development.md
Normal file
@ -0,0 +1,281 @@
|
|||||||
|
# Development Guide
|
||||||
|
|
||||||
|
This guide provides detailed information for developers who want to modify or extend the KiCad MCP Server.
|
||||||
|
|
||||||
|
## Development Environment Setup
|
||||||
|
|
||||||
|
1. **Set up your Python environment**:
|
||||||
|
```bash
|
||||||
|
# Create and activate a virtual environment
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||||
|
|
||||||
|
# Install development dependencies
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Run in development mode**:
|
||||||
|
```bash
|
||||||
|
# Run with development server for better debugging
|
||||||
|
python -m mcp.dev main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Use the MCP Inspector** for debugging:
|
||||||
|
```bash
|
||||||
|
npx @modelcontextprotocol/inspector uv --directory . run main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
The KiCad MCP Server follows a modular architecture:
|
||||||
|
|
||||||
|
```
|
||||||
|
kicad-mcp/
|
||||||
|
├── main.py # Entry point
|
||||||
|
├── kicad_mcp/ # Main package
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ ├── server.py # Server creation and setup
|
||||||
|
│ ├── config.py # Configuration settings
|
||||||
|
│ ├── context.py # Lifespan context management
|
||||||
|
│ ├── resources/ # Resource handlers
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── projects.py # Project listing resources
|
||||||
|
│ │ ├── files.py # File content resources
|
||||||
|
│ │ ├── drc_resources.py # DRC report resources
|
||||||
|
│ │ └── bom_resources.py # BOM resources
|
||||||
|
│ ├── tools/ # Tool handlers
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── project_tools.py # Project management tools
|
||||||
|
│ │ ├── analysis_tools.py # Design analysis tools
|
||||||
|
│ │ ├── drc_tools.py # DRC check tools
|
||||||
|
│ │ ├── export_tools.py # Export and thumbnail tools
|
||||||
|
│ │ └── bom_tools.py # BOM management tools
|
||||||
|
│ ├── prompts/ # Prompt templates
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── templates.py # General KiCad prompts
|
||||||
|
│ │ ├── drc_prompt.py # DRC-specific prompts
|
||||||
|
│ │ └── bom_prompts.py # BOM-specific prompts
|
||||||
|
│ └── utils/ # Utility functions
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ ├── file_utils.py # File handling utilities
|
||||||
|
│ ├── kicad_utils.py # KiCad-specific functions
|
||||||
|
│ ├── python_path.py # Python path setup for KiCad modules
|
||||||
|
│ ├── drc_history.py # DRC history tracking
|
||||||
|
│ ├── env.py # Environment variable handling
|
||||||
|
│ └── logger.py # Logging utilities
|
||||||
|
```
|
||||||
|
|
||||||
|
## Adding New Features
|
||||||
|
|
||||||
|
### Creating a New Resource
|
||||||
|
|
||||||
|
Resources provide read-only data to the LLM. To add a new resource:
|
||||||
|
|
||||||
|
1. Add your function to an existing resource file or create a new one in `kicad_mcp/resources/`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mcp.server.fastmcp import FastMCP
|
||||||
|
|
||||||
|
def register_my_resources(mcp: FastMCP) -> None:
|
||||||
|
"""Register my custom resources with the MCP server."""
|
||||||
|
|
||||||
|
@mcp.resource("kicad://my-resource/{parameter}")
|
||||||
|
def my_custom_resource(parameter: str) -> str:
|
||||||
|
"""Description of what this resource provides.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
parameter: Description of parameter
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Formatted data for the LLM
|
||||||
|
"""
|
||||||
|
# Implementation goes here
|
||||||
|
return f"Formatted data about {parameter}"
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Register your resources in `kicad_mcp/server.py`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from kicad_mcp.resources.my_resources import register_my_resources
|
||||||
|
|
||||||
|
def create_server() -> FastMCP:
|
||||||
|
# ...
|
||||||
|
register_my_resources(mcp)
|
||||||
|
# ...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Creating a New Tool
|
||||||
|
|
||||||
|
Tools are functions that perform actions or computations. To add a new tool:
|
||||||
|
|
||||||
|
1. Add your function to an existing tool file or create a new one in `kicad_mcp/tools/`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from typing import Dict, Any
|
||||||
|
from mcp.server.fastmcp import FastMCP, Context
|
||||||
|
|
||||||
|
def register_my_tools(mcp: FastMCP) -> None:
|
||||||
|
"""Register my custom tools with the MCP server."""
|
||||||
|
|
||||||
|
@mcp.tool()
|
||||||
|
async def my_custom_tool(parameter: str, ctx: Context) -> Dict[str, Any]:
|
||||||
|
"""Description of what this tool does.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
parameter: Description of parameter
|
||||||
|
ctx: MCP context for progress reporting
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Dictionary with tool results
|
||||||
|
"""
|
||||||
|
# Report progress to the user
|
||||||
|
await ctx.report_progress(10, 100)
|
||||||
|
ctx.info(f"Starting operation on {parameter}")
|
||||||
|
|
||||||
|
# Implementation goes here
|
||||||
|
|
||||||
|
# Complete progress
|
||||||
|
await ctx.report_progress(100, 100)
|
||||||
|
ctx.info("Operation complete")
|
||||||
|
|
||||||
|
return {
|
||||||
|
"success": True,
|
||||||
|
"message": "Operation completed successfully",
|
||||||
|
"result": "Some result data"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Register your tools in `kicad_mcp/server.py`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from kicad_mcp.tools.my_tools import register_my_tools
|
||||||
|
|
||||||
|
def create_server() -> FastMCP:
|
||||||
|
# ...
|
||||||
|
register_my_tools(mcp)
|
||||||
|
# ...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Creating a New Prompt
|
||||||
|
|
||||||
|
Prompts are reusable templates for common interactions. To add a new prompt:
|
||||||
|
|
||||||
|
1. Add your function to an existing prompt file or create a new one in `kicad_mcp/prompts/`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mcp.server.fastmcp import FastMCP
|
||||||
|
|
||||||
|
def register_my_prompts(mcp: FastMCP) -> None:
|
||||||
|
"""Register my custom prompts with the MCP server."""
|
||||||
|
|
||||||
|
@mcp.prompt()
|
||||||
|
def my_custom_prompt() -> str:
|
||||||
|
"""Description of what this prompt is for."""
|
||||||
|
prompt = """
|
||||||
|
I need help with [specific task] in KiCad. Please assist me with:
|
||||||
|
|
||||||
|
1. [First aspect]
|
||||||
|
2. [Second aspect]
|
||||||
|
3. [Third aspect]
|
||||||
|
|
||||||
|
My KiCad project is located at:
|
||||||
|
[Enter the full path to your .kicad_pro file here]
|
||||||
|
|
||||||
|
[Additional contextual information or instructions]
|
||||||
|
"""
|
||||||
|
|
||||||
|
return prompt
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Register your prompts in `kicad_mcp/server.py`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from kicad_mcp.prompts.my_prompts import register_my_prompts
|
||||||
|
|
||||||
|
def create_server() -> FastMCP:
|
||||||
|
# ...
|
||||||
|
register_my_prompts(mcp)
|
||||||
|
# ...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Using the Lifespan Context
|
||||||
|
|
||||||
|
The KiCad MCP Server uses a typed lifespan context to share data across requests:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from kicad_mcp.context import KiCadAppContext
|
||||||
|
|
||||||
|
@mcp.tool()
|
||||||
|
def my_tool(parameter: str, ctx: Context) -> Dict[str, Any]:
|
||||||
|
"""Example tool using lifespan context."""
|
||||||
|
# Access the typed context
|
||||||
|
app_context: KiCadAppContext = ctx.request_context.lifespan_context
|
||||||
|
|
||||||
|
# Check if KiCad modules are available
|
||||||
|
if app_context.kicad_modules_available:
|
||||||
|
# Use KiCad Python modules
|
||||||
|
pass
|
||||||
|
else:
|
||||||
|
# Fall back to alternative method
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Use the cache to store expensive results
|
||||||
|
cache_key = f"my_operation_{parameter}"
|
||||||
|
if cache_key in app_context.cache:
|
||||||
|
return app_context.cache[cache_key]
|
||||||
|
|
||||||
|
# Perform operation
|
||||||
|
result = {}
|
||||||
|
|
||||||
|
# Cache the result
|
||||||
|
app_context.cache[cache_key] = result
|
||||||
|
|
||||||
|
return result
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
To run tests:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run all tests
|
||||||
|
pytest
|
||||||
|
|
||||||
|
# Run specific test file
|
||||||
|
pytest tests/test_resources.py
|
||||||
|
|
||||||
|
# Run with verbose output
|
||||||
|
pytest -v
|
||||||
|
```
|
||||||
|
|
||||||
|
## Debugging
|
||||||
|
|
||||||
|
For debugging, use:
|
||||||
|
|
||||||
|
1. The Python debugger (pdb)
|
||||||
|
2. Print statements to the console (captured in Claude Desktop logs)
|
||||||
|
3. Structured logging via the Logger class
|
||||||
|
4. The MCP Inspector tool
|
||||||
|
|
||||||
|
## Performance Considerations
|
||||||
|
|
||||||
|
1. Use caching for expensive operations
|
||||||
|
2. Report progress to the user for long-running operations
|
||||||
|
3. Include proper error handling and fallbacks
|
||||||
|
4. Use asyncio for concurrent operations
|
||||||
|
|
||||||
|
## Security Best Practices
|
||||||
|
|
||||||
|
1. Validate all file paths and user inputs
|
||||||
|
2. Use absolute paths for better predictability
|
||||||
|
3. Implement proper error handling
|
||||||
|
4. Don't expose sensitive information in responses
|
||||||
|
5. Sanitize output before returning it to the client
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
When adding new features, remember to:
|
||||||
|
|
||||||
|
1. Add thorough docstrings to all functions and classes
|
||||||
|
2. Update relevant documentation files in the `docs/` directory
|
||||||
|
3. Include examples of how to use your feature
|
||||||
185
docs/project_guide.md
Normal file
185
docs/project_guide.md
Normal file
@ -0,0 +1,185 @@
|
|||||||
|
# KiCad Project Management Guide
|
||||||
|
|
||||||
|
This guide explains how to use the project management features in the KiCad MCP Server.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The project management functionality allows you to:
|
||||||
|
|
||||||
|
1. List all KiCad projects on your system
|
||||||
|
2. View detailed information about specific projects
|
||||||
|
3. Open projects directly in KiCad
|
||||||
|
4. Validate project files for completeness and correctness
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Task | Example Prompt |
|
||||||
|
|------|---------------|
|
||||||
|
| List all projects | `List all my KiCad projects` |
|
||||||
|
| View project details | `Show details for my KiCad project at /path/to/project.kicad_pro` |
|
||||||
|
| Open a project | `Open my KiCad project at /path/to/project.kicad_pro` |
|
||||||
|
| Validate a project | `Validate my KiCad project at /path/to/project.kicad_pro` |
|
||||||
|
|
||||||
|
## Using Project Management Features
|
||||||
|
|
||||||
|
### Listing Projects
|
||||||
|
|
||||||
|
To see all KiCad projects available on your system:
|
||||||
|
|
||||||
|
```
|
||||||
|
Could you list all my KiCad projects?
|
||||||
|
```
|
||||||
|
|
||||||
|
This will:
|
||||||
|
- Search your KiCad user directory (typically `~/Documents/KiCad`)
|
||||||
|
- Search any additional directories specified in your configuration
|
||||||
|
- Display a formatted list of projects with:
|
||||||
|
- Project names
|
||||||
|
- File paths
|
||||||
|
- Last modified dates
|
||||||
|
|
||||||
|
The listing is sorted by last modified date, with most recently modified projects first.
|
||||||
|
|
||||||
|
#### How Project Discovery Works
|
||||||
|
|
||||||
|
Projects are discovered by:
|
||||||
|
1. Looking in the standard KiCad user directory
|
||||||
|
2. Searching directories specified in the `KICAD_SEARCH_PATHS` environment variable
|
||||||
|
3. Looking in common project directories (automatically detected)
|
||||||
|
|
||||||
|
### Viewing Project Details
|
||||||
|
|
||||||
|
To get detailed information about a specific project:
|
||||||
|
|
||||||
|
```
|
||||||
|
Show me details about my KiCad project at /path/to/your/project.kicad_pro
|
||||||
|
```
|
||||||
|
|
||||||
|
This will display:
|
||||||
|
- Basic project information
|
||||||
|
- Associated files (schematic, PCB, etc.)
|
||||||
|
- Project settings
|
||||||
|
- Metadata
|
||||||
|
|
||||||
|
Example output:
|
||||||
|
```
|
||||||
|
# Project: my_project
|
||||||
|
|
||||||
|
## Project Files
|
||||||
|
- **project**: /path/to/my_project.kicad_pro
|
||||||
|
- **schematic**: /path/to/my_project.kicad_sch
|
||||||
|
- **pcb**: /path/to/my_project.kicad_pcb
|
||||||
|
- **netlist**: /path/to/my_project_netlist.net
|
||||||
|
|
||||||
|
## Project Settings
|
||||||
|
- **version**: 20210606
|
||||||
|
- **generator**: pcbnew
|
||||||
|
- **board_thickness**: 1.6
|
||||||
|
```
|
||||||
|
|
||||||
|
### Opening Projects
|
||||||
|
|
||||||
|
To open a KiCad project:
|
||||||
|
|
||||||
|
```
|
||||||
|
Can you open my KiCad project at /path/to/your/project.kicad_pro?
|
||||||
|
```
|
||||||
|
|
||||||
|
This will:
|
||||||
|
- Launch KiCad with the specified project
|
||||||
|
- Return confirmation and status information
|
||||||
|
|
||||||
|
Note that this requires KiCad to be properly installed in the standard location for your operating system. The server detects KiCad's location automatically based on your platform.
|
||||||
|
|
||||||
|
### Validating Projects
|
||||||
|
|
||||||
|
To validate a KiCad project for issues:
|
||||||
|
|
||||||
|
```
|
||||||
|
Validate my KiCad project at /path/to/your/project.kicad_pro
|
||||||
|
```
|
||||||
|
|
||||||
|
The validation will check for:
|
||||||
|
- Missing or corrupt project files
|
||||||
|
- Required components (schematic, PCB)
|
||||||
|
- Valid project structure
|
||||||
|
- Proper JSON formatting
|
||||||
|
|
||||||
|
This is useful for identifying issues with project files before attempting to open them in KiCad.
|
||||||
|
|
||||||
|
## Project Resources
|
||||||
|
|
||||||
|
The server provides several resources for accessing project information:
|
||||||
|
|
||||||
|
- `kicad://projects` - List of all projects
|
||||||
|
- `kicad://project/{project_path}` - Details about a specific project
|
||||||
|
|
||||||
|
These resources can be accessed programmatically by other MCP clients or directly referenced in conversations.
|
||||||
|
|
||||||
|
## Tips for Project Management
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
For smooth project management:
|
||||||
|
|
||||||
|
1. **Use consistent naming**: Keep project filenames consistent and meaningful
|
||||||
|
2. **Organize by functionality**: Group related projects in themed directories
|
||||||
|
3. **Include documentation**: Add README files or documentation in project directories
|
||||||
|
4. **Back up regularly**: Create backups of important projects
|
||||||
|
5. **Use version control**: Consider using git for tracking project changes
|
||||||
|
|
||||||
|
### Path Handling
|
||||||
|
|
||||||
|
When specifying project paths:
|
||||||
|
|
||||||
|
- Use absolute paths for reliability
|
||||||
|
- Ensure paths are properly escaped if they contain spaces
|
||||||
|
- On Windows, use forward slashes (/) instead of backslashes (\\)
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Projects Not Found
|
||||||
|
|
||||||
|
If your projects aren't being discovered:
|
||||||
|
|
||||||
|
1. Check your `.env` file to ensure search paths are correctly specified
|
||||||
|
2. Verify that projects have the `.kicad_pro` extension
|
||||||
|
3. Check if you have read permissions for the specified directories
|
||||||
|
4. Try using absolute paths instead of relative paths
|
||||||
|
5. Restart the server after changing configuration
|
||||||
|
|
||||||
|
### Can't Open Projects
|
||||||
|
|
||||||
|
If you can't open projects:
|
||||||
|
|
||||||
|
1. Verify that KiCad is installed correctly
|
||||||
|
2. Check the `KICAD_APP_PATH` configuration if KiCad is in a non-standard location
|
||||||
|
3. Ensure the project path is correctly specified and accessible
|
||||||
|
4. Check if you have permissions to launch applications
|
||||||
|
5. Look for errors in the server logs
|
||||||
|
|
||||||
|
## Advanced Usage
|
||||||
|
|
||||||
|
### Custom Project Queries
|
||||||
|
|
||||||
|
You can ask more specific questions about your projects:
|
||||||
|
|
||||||
|
```
|
||||||
|
Which of my KiCad projects were modified in the last week?
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
Show me all KiCad projects in my ~/Electronics directory that have a PCB file
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Statistics
|
||||||
|
|
||||||
|
For insights across multiple projects:
|
||||||
|
|
||||||
|
```
|
||||||
|
What's the average board size across all my KiCad projects?
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
Which components are most commonly used across my KiCad projects?
|
||||||
|
```
|
||||||
37
docs/prompt_guide.md
Normal file
37
docs/prompt_guide.md
Normal file
@ -0,0 +1,37 @@
|
|||||||
|
# KiCad Prompt Templates Guide
|
||||||
|
|
||||||
|
This guide explains how to use the prompt templates feature in the KiCad MCP Server to improve your interaction with Claude and other LLMs when working with KiCad projects.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Prompt templates are pre-built conversation starters designed to help you get the most out of LLMs when working with KiCad. They provide structured formats for common KiCad tasks, ensuring you get high-quality assistance from the AI.
|
||||||
|
|
||||||
|
## Available Prompt Templates
|
||||||
|
|
||||||
|
The KiCad MCP Server includes several specialized prompt templates for common KiCad workflows:
|
||||||
|
|
||||||
|
### General KiCad Prompts
|
||||||
|
|
||||||
|
| Prompt Template | Description | Use When |
|
||||||
|
|----------------|-------------|----------|
|
||||||
|
| `create_new_component` | Guidance for creating new KiCad components | You need to create a schematic symbol, PCB footprint, or 3D model |
|
||||||
|
| `debug_pcb_issues` | Help with troubleshooting PCB problems | You encounter issues with your PCB design |
|
||||||
|
| `pcb_manufacturing_checklist` | Preparation guidance for manufacturing | You're getting ready to send your PCB for fabrication |
|
||||||
|
|
||||||
|
### DRC-Specific Prompts
|
||||||
|
|
||||||
|
| Prompt Template | Description | Use When |
|
||||||
|
|----------------|-------------|----------|
|
||||||
|
| `fix_drc_violations` | Help with resolving DRC violations | You have design rule violations to fix |
|
||||||
|
| `custom_design_rules` | Guidance for creating custom design rules | You need specialized design rules for your project |
|
||||||
|
|
||||||
|
### BOM-Related Prompts
|
||||||
|
|
||||||
|
| Prompt Template | Description | Use When |
|
||||||
|
|----------------|-------------|----------|
|
||||||
|
| `analyze_components` | Analysis of component usage in your design | You want insights about your component selections |
|
||||||
|
| `cost_estimation` | Help with estimating project costs | You need to budget for your PCB project |
|
||||||
|
| `bom_export_help` | Assistance with exporting BOMs | You need help creating or customizing BOMs |
|
||||||
|
| `component_sourcing` | Guidance for finding and sourcing components | You need to purchase components for your project |
|
||||||
|
| `bom_comparison` | Compare BOMs between different design revisions | You want to understand changes between versions |
|
||||||
|
|
||||||
289
docs/troubleshooting.md
Normal file
289
docs/troubleshooting.md
Normal file
@ -0,0 +1,289 @@
|
|||||||
|
# Troubleshooting Guide
|
||||||
|
|
||||||
|
This guide helps you troubleshoot common issues with the KiCad MCP Server.
|
||||||
|
|
||||||
|
## Server Setup Issues
|
||||||
|
|
||||||
|
### Server Not Starting
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Error messages when running `python main.py`
|
||||||
|
- Server crashes immediately
|
||||||
|
|
||||||
|
**Possible Causes and Solutions:**
|
||||||
|
|
||||||
|
1. **Missing Dependencies**
|
||||||
|
- **Error:** `ModuleNotFoundError: No module named 'mcp'`
|
||||||
|
- **Solution:** Ensure you have installed the required packages
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Python Version**
|
||||||
|
- **Error:** Syntax errors or unsupported features
|
||||||
|
- **Solution:** Verify you're using Python 3.10 or higher
|
||||||
|
```bash
|
||||||
|
python --version
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Configuration Issues**
|
||||||
|
- **Error:** `FileNotFoundError` or errors related to paths
|
||||||
|
- **Solution:** Check your `.env` file and ensure all paths exist
|
||||||
|
|
||||||
|
4. **Permission Issues**
|
||||||
|
- **Error:** `PermissionError: [Errno 13] Permission denied`
|
||||||
|
- **Solution:** Ensure you have the necessary permissions for all directories and files
|
||||||
|
|
||||||
|
## MCP Client Integration Issues
|
||||||
|
|
||||||
|
### Server Not Appearing in Client
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Server not showing in Claude Desktop tools dropdown
|
||||||
|
- Unable to access KiCad tools in the client
|
||||||
|
|
||||||
|
**Possible Causes and Solutions:**
|
||||||
|
|
||||||
|
1. **Configuration File Issues**
|
||||||
|
- **Problem:** Incorrect or missing configuration
|
||||||
|
- **Solution:** Check your client configuration file:
|
||||||
|
|
||||||
|
For Claude Desktop (macOS):
|
||||||
|
```bash
|
||||||
|
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
||||||
|
```
|
||||||
|
|
||||||
|
For Claude Desktop (Windows):
|
||||||
|
```bash
|
||||||
|
type %APPDATA%\Claude\claude_desktop_config.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Ensure it contains the correct server configuration:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"kicad": {
|
||||||
|
"command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/venv/bin/python",
|
||||||
|
"args": [
|
||||||
|
"/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Working Directory Issues**
|
||||||
|
- **Problem:** The server can't find files due to working directory issues
|
||||||
|
- **Solution:** Always use absolute paths in your configuration
|
||||||
|
|
||||||
|
Replace:
|
||||||
|
```json
|
||||||
|
"args": ["main.py"]
|
||||||
|
```
|
||||||
|
|
||||||
|
With:
|
||||||
|
```json
|
||||||
|
"args": ["/absolute/path/to/main.py"]
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Client Needs Restart**
|
||||||
|
- **Problem:** Changes to configuration not applied
|
||||||
|
- **Solution:** Close and reopen your MCP client
|
||||||
|
|
||||||
|
4. **MCP Protocol Version Mismatch**
|
||||||
|
- **Problem:** Client and server using incompatible protocol versions
|
||||||
|
- **Solution:** Update both the client and server to compatible versions
|
||||||
|
|
||||||
|
## Working with KiCad
|
||||||
|
|
||||||
|
### KiCad Python Modules Not Found
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Warning messages about missing KiCad Python modules
|
||||||
|
- Limited functionality for PCB analysis, DRC, etc.
|
||||||
|
|
||||||
|
**Possible Causes and Solutions:**
|
||||||
|
|
||||||
|
1. **KiCad Not Installed**
|
||||||
|
- **Problem:** KiCad installation not found
|
||||||
|
- **Solution:** Install KiCad from [kicad.org](https://www.kicad.org/download/)
|
||||||
|
|
||||||
|
2. **Non-standard KiCad Installation**
|
||||||
|
- **Problem:** KiCad installed in a non-standard location
|
||||||
|
- **Solution:** Set the `KICAD_APP_PATH` environment variable in your `.env` file:
|
||||||
|
```
|
||||||
|
KICAD_APP_PATH=/path/to/KiCad/KiCad.app
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Python Path Issues**
|
||||||
|
- **Problem:** KiCad Python modules not in Python path
|
||||||
|
- **Solution:** Check server logs for Python path setup errors
|
||||||
|
|
||||||
|
### Unable to Open KiCad Projects
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Error when trying to open a KiCad project
|
||||||
|
- KiCad doesn't launch when requested
|
||||||
|
|
||||||
|
**Possible Causes and Solutions:**
|
||||||
|
|
||||||
|
1. **KiCad Not Found**
|
||||||
|
- **Problem:** KiCad executable not found
|
||||||
|
- **Solution:** Set the correct `KICAD_APP_PATH` in your `.env` file
|
||||||
|
|
||||||
|
2. **Project Path Issues**
|
||||||
|
- **Problem:** Project file not found
|
||||||
|
- **Solution:** Double-check the path to your KiCad project file
|
||||||
|
- Ensure the path is an absolute path
|
||||||
|
- Ensure the file exists and has a `.kicad_pro` extension
|
||||||
|
|
||||||
|
3. **Permission Issues**
|
||||||
|
- **Problem:** Insufficient permissions to launch KiCad
|
||||||
|
- **Solution:** Check file and application permissions
|
||||||
|
|
||||||
|
## Project Discovery Issues
|
||||||
|
|
||||||
|
### KiCad Projects Not Found
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- No projects listed when asking for KiCad projects
|
||||||
|
- Missing specific projects that you know exist
|
||||||
|
|
||||||
|
**Possible Causes and Solutions:**
|
||||||
|
|
||||||
|
1. **Search Path Issues**
|
||||||
|
- **Problem:** Server not looking in the right directories
|
||||||
|
- **Solution:** Configure search paths in your `.env` file:
|
||||||
|
```
|
||||||
|
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **KiCad User Directory Override**
|
||||||
|
- **Problem:** Custom KiCad user directory not being searched
|
||||||
|
- **Solution:** Set `KICAD_USER_DIR` in your `.env` file:
|
||||||
|
```
|
||||||
|
KICAD_USER_DIR=~/Documents/KiCadProjects
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **File Extension Issues**
|
||||||
|
- **Problem:** Projects not recognized due to file extensions
|
||||||
|
- **Solution:** Ensure your KiCad projects have the `.kicad_pro` extension
|
||||||
|
|
||||||
|
## Debugging and Logging
|
||||||
|
|
||||||
|
### Checking Logs
|
||||||
|
|
||||||
|
To diagnose issues, check the server logs:
|
||||||
|
|
||||||
|
1. **Development Mode Logs**
|
||||||
|
- When running in development mode with `python -m mcp.dev main.py`, logs appear in the console
|
||||||
|
|
||||||
|
2. **Claude Desktop Logs (macOS)**
|
||||||
|
- Server logs:
|
||||||
|
```bash
|
||||||
|
tail -n 20 -F ~/Library/Logs/Claude/mcp-server-kicad.log
|
||||||
|
```
|
||||||
|
- General MCP logs:
|
||||||
|
```bash
|
||||||
|
tail -n 20 -F ~/Library/Logs/Claude/mcp.log
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Claude Desktop Logs (Windows)**
|
||||||
|
- Check logs in:
|
||||||
|
```
|
||||||
|
%APPDATA%\Claude\Logs\
|
||||||
|
```
|
||||||
|
|
||||||
|
### Enabling Debug Logging
|
||||||
|
|
||||||
|
For more detailed logs, set the logging level to DEBUG in your `.env` file:
|
||||||
|
|
||||||
|
```
|
||||||
|
LOG_LEVEL=DEBUG
|
||||||
|
```
|
||||||
|
|
||||||
|
## DRC and Export Feature Issues
|
||||||
|
|
||||||
|
### DRC Checks Failing
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Error messages when running DRC checks
|
||||||
|
- Incomplete DRC results
|
||||||
|
|
||||||
|
**Possible Causes and Solutions:**
|
||||||
|
|
||||||
|
1. **KiCad CLI Tools Not Found**
|
||||||
|
- **Problem:** Command-line tools not available
|
||||||
|
- **Solution:** Ensure you have a complete KiCad installation with CLI tools
|
||||||
|
|
||||||
|
2. **PCB File Issues**
|
||||||
|
- **Problem:** Invalid or corrupted PCB file
|
||||||
|
- **Solution:** Verify the PCB file can be opened in KiCad
|
||||||
|
|
||||||
|
### PCB Thumbnail Generation Failing
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Unable to generate PCB thumbnails
|
||||||
|
- Error messages about missing modules
|
||||||
|
|
||||||
|
**Possible Causes and Solutions:**
|
||||||
|
|
||||||
|
1. **Missing KiCad Python Modules**
|
||||||
|
- **Problem:** Unable to import pcbnew module
|
||||||
|
- **Solution:** The server will try alternative methods, but functionality may be limited
|
||||||
|
|
||||||
|
2. **File Path Issues**
|
||||||
|
- **Problem:** PCB file not found
|
||||||
|
- **Solution:** Ensure you're using absolute paths and the PCB file exists
|
||||||
|
|
||||||
|
## Environment-Specific Issues
|
||||||
|
|
||||||
|
### macOS Issues
|
||||||
|
|
||||||
|
1. **Permissions**
|
||||||
|
- **Problem:** Permission denied when accessing files
|
||||||
|
- **Solution:** Ensure Terminal has full disk access in System Preferences > Security & Privacy
|
||||||
|
|
||||||
|
2. **Python Environment**
|
||||||
|
- **Problem:** System Python vs. Homebrew Python confusion
|
||||||
|
- **Solution:** Specify the full path to the Python interpreter in your client configuration
|
||||||
|
|
||||||
|
### Windows Issues
|
||||||
|
|
||||||
|
1. **Path Separator Issues**
|
||||||
|
- **Problem:** Backslashes in Windows paths causing issues
|
||||||
|
- **Solution:** Use forward slashes (/) in all paths, or double backslashes (\\\\)
|
||||||
|
|
||||||
|
2. **Command Execution**
|
||||||
|
- **Problem:** Issues launching KiCad from the server
|
||||||
|
- **Solution:** Ensure the KICAD_APP_PATH is set correctly in your `.env` file
|
||||||
|
|
||||||
|
### Linux Issues
|
||||||
|
|
||||||
|
1. **KiCad Installation Location**
|
||||||
|
- **Problem:** KiCad installed in non-standard location
|
||||||
|
- **Solution:** Set KICAD_APP_PATH to your KiCad installation location
|
||||||
|
|
||||||
|
2. **Permission Issues**
|
||||||
|
- **Problem:** Unable to access certain files
|
||||||
|
- **Solution:** Check file permissions with `ls -la` and adjust with `chmod` if needed
|
||||||
|
|
||||||
|
## Still Having Issues?
|
||||||
|
|
||||||
|
If you're still experiencing problems:
|
||||||
|
|
||||||
|
1. Try running the server in development mode for more detailed output:
|
||||||
|
```bash
|
||||||
|
python -m mcp.dev main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Use the MCP Inspector for direct server testing:
|
||||||
|
```bash
|
||||||
|
npx @modelcontextprotocol/inspector uv --directory . run main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Open an issue on GitHub with:
|
||||||
|
- A clear description of the problem
|
||||||
|
- Steps to reproduce
|
||||||
|
- Error messages or logs
|
||||||
|
- Your environment details (OS, Python version, KiCad version)
|
||||||
Loading…
x
Reference in New Issue
Block a user