kicad-mcp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Essential Commands

• make install - Install dependencies using uv (creates .venv automatically)
• make run - Start the KiCad MCP server (uv run python main.py)
• make test - Run all tests with pytest
• make test <file> - Run specific test file
• make lint - Run linting with ruff and mypy (uv run ruff check mckicad/ tests/ + uv run mypy mckicad/)
• make format - Format code with ruff (uv run ruff format mckicad/ tests/)
• make build - Build package with uv
• make clean - Clean build artifacts

Development Environment

• Uses uv for dependency management (Python 3.10+ required)
• Virtual environment is automatically created in .venv/
• Configuration via .env file (copy from .env.example)

Architecture

MCP Server Components

This project implements a Model Context Protocol (MCP) server for KiCad electronic design automation. The architecture follows MCP patterns with three main component types:

Resources (read-only data):

• kicad://projects - List KiCad projects
• kicad://project/{project_path} - Project details
• kicad://drc_report/{project_path} - DRC reports
• kicad://bom/{project_path} - Bill of materials
• kicad://netlist/{project_path} - Circuit netlists
• kicad://patterns/{project_path} - Circuit pattern analysis

Tools (actions/computations):

• Project management (open projects, analysis)
• DRC checking with KiCad CLI integration
• BOM generation and export
• PCB visualization and thumbnails
• Circuit pattern recognition
• File export operations

Prompts (reusable templates):

• PCB debugging assistance
• BOM analysis workflows
• Circuit pattern identification
• DRC troubleshooting

Key Modules

Core Server (mckicad/server.py)

• FastMCP server initialization with lifespan management
• Registers all resources, tools, and prompts
• Signal handling for graceful shutdown
• Cleanup handlers for temporary directories

Configuration (mckicad/config.py)

• Platform-specific KiCad paths (macOS/Windows/Linux)
• Environment variable handling (KICAD_SEARCH_PATHS, KICAD_USER_DIR)
• Component library mappings and default footprints
• Timeout and display constants

Context Management (mckicad/context.py)

• Lifespan context with KiCad module availability detection
• Shared cache across requests
• Application state management

Security Features

• Path validation utilities in utils/path_validator.py
• Secure subprocess execution in utils/secure_subprocess.py
• Input sanitization for KiCad CLI operations
• Boundary validation for file operations

KiCad Integration Strategy

• Primary: KiCad CLI (kicad-cli) for all operations
• Fallback: Direct file parsing for basic operations
• Detection: Automatic KiCad installation detection across platforms
• Isolation: Subprocess-based execution for security

Project Structure

mckicad/
├── resources/          # MCP resources (data providers)
├── tools/             # MCP tools (action performers)  
├── prompts/           # MCP prompt templates
└── utils/             # Utility functions and helpers
    ├── kicad_utils.py      # KiCad-specific operations
    ├── file_utils.py       # File handling utilities
    ├── path_validator.py   # Security path validation
    └── secure_subprocess.py # Safe process execution

Development Notes

Adding New Features

1. Identify component type (resource/tool/prompt)
2. Add implementation to appropriate module in mckicad/
3. Register in server.py create_server() function
4. Use lifespan context for shared state and caching
5. Include progress reporting for long operations

KiCad CLI Integration

• All KiCad operations use CLI interface for security
• CLI detection in utils/kicad_cli.py
• Path validation prevents directory traversal
• Subprocess timeouts prevent hanging operations

Testing

• Unit tests in tests/unit/
• Test markers: unit, integration, requires_kicad, slow, performance
• Coverage target: 80% (configured in pyproject.toml)
• Run with: pytest or make test

Configuration

• Environment variables override defaults in config.py
• .env file support for development
• Platform detection for KiCad paths
• Search path expansion with ~ support

Entry Point

• main.py is the server entry point
• Handles logging setup and .env file loading
• Manages server lifecycle with proper cleanup
• Uses asyncio for MCP server execution

Revolutionary Features: KiCad IPC + FreeRouting Integration

This project implements groundbreaking real-time PCB automation through two advanced integrations:

KiCad IPC API Integration (utils/ipc_client.py)

• Real-time design manipulation via kicad-python library (kipy package)
• Live component access: Move, rotate, analyze footprints in real-time
• Connectivity monitoring: Track routing status and net connections
• Transaction-based operations: Automatic rollback on errors
• Lazy connection: Gracefully degrades when KiCad isn't running
• Context manager pattern: Use kicad_ipc_session() for automatic cleanup

Key Usage Pattern:

from mckicad.utils.ipc_client import kicad_ipc_session

with kicad_ipc_session(board_path) as client:
    footprints = client.get_footprints()
    client.move_footprint("R1", Vector2(100.0, 50.0))
    stats = client.get_board_statistics()

FreeRouting Integration (utils/freerouting_engine.py)

• Professional autorouting via FreeRouting JAR execution
• Complete workflow automation: DSN export → Route → SES import
• Multi-strategy routing: Conservative, balanced, aggressive presets
• Technology-specific optimization: Standard, HDI, RF, automotive modes
• Post-routing optimization: Via minimization, trace cleanup
• Configuration system: Routing parameters, layer preferences, cost functions

Routing Workflow:

1. Export board to DSN format via KiCad CLI
2. Execute FreeRouting with optimized parameters
3. Import routed SES file back via IPC API
4. Validate and optimize routing results
5. Run DRC checks and report statistics

Complete Automation Pipeline (tools/project_automation.py)

The automate_complete_design() tool orchestrates:

1. AI-driven design analysis (circuit pattern recognition)
2. Component placement optimization (thermal-aware)
3. Automated PCB routing (FreeRouting integration)
4. DRC validation and fixing
5. Manufacturing file generation (Gerber, drill, assembly)
6. Supply chain optimization (component availability)

Important Implementation Notes

Dual-Mode Operation

This server operates in TWO modes depending on KiCad availability:

Mode 1: KiCad Running (IPC Available)

• Real-time component manipulation
• Live board statistics
• Interactive routing optimization
• Immediate DRC feedback

Mode 2: KiCad CLI Only

• File-based operations via kicad-cli
• Batch processing and exports
• Static analysis and validation
• Manufacturing file generation

Detection Logic:

# IPC availability checked at runtime
if check_kicad_availability()["available"]:
    # Use real-time IPC features
else:
    # Fall back to CLI operations

FreeRouting Setup

For automated routing to work:

1. Download FreeRouting JAR from https://freerouting.app/
2. Place in one of these locations:
   • ~/freerouting.jar
   • /usr/local/bin/freerouting.jar
   • /opt/freerouting/freerouting.jar
3. Ensure Java runtime is installed (java -version)
4. Use check_routing_capability() tool to verify setup

Environment Configuration

Key environment variables in .env:

• KICAD_USER_DIR: KiCad user documents directory
• KICAD_SEARCH_PATHS: Comma-separated project search paths
• FREEROUTING_JAR_PATH: Explicit path to FreeRouting JAR
• KICAD_CLI_PATH: Explicit path to kicad-cli executable

Package Entry Point

The package declares a script entry point in pyproject.toml:

[project.scripts]
mckicad = "mckicad.server:main"

This enables running via uvx mckicad after installation.

Logging

• All logs written to mckicad.log in project root
• Log file overwritten on each server start
• PID included in log messages for process tracking
• Use logging module, never print() statements

Tool Implementation Patterns

FastMCP Tool Registration

All tools follow this registration pattern in server.py:

from mckicad.tools.example_tools import register_example_tools

def create_server() -> FastMCP:
    mcp = FastMCP("KiCad", lifespan=lifespan_factory)

    # Register tools
    register_example_tools(mcp)

    return mcp

Tool Module Structure

Each tool module should:

1. Define a register_*_tools(mcp: FastMCP) function
2. Use @mcp.tool() decorator for each tool
3. Include comprehensive docstrings with examples
4. Return dictionaries with consistent structure:

   {
       "success": bool,
       "data": Any,  # Results on success
       "error": str  # Error message on failure
   }
   

Progress Reporting

For long operations, use progress constants:

from mckicad.config import PROGRESS_CONSTANTS

progress_callback(PROGRESS_CONSTANTS["start"])
# ... do work ...
progress_callback(PROGRESS_CONSTANTS["processing"])
# ... finish ...
progress_callback(PROGRESS_CONSTANTS["complete"])

Security Architecture

Path Validation (utils/path_validator.py)

• All file paths validated before access
• Directory traversal prevention
• Boundary checking for project directories
• Whitelist-based validation

Secure Subprocess (utils/secure_subprocess.py)

• All external commands executed securely
• Timeouts prevent hanging operations
• Output sanitization
• Error handling with safe error messages

Always Validate:

1. Project paths exist and are within search paths
2. File extensions match expected types
3. Subprocess commands are sanitized
4. Timeout values are reasonable

Testing Strategy

Test Organization

tests/
├── unit/              # Fast, isolated tests
│   └── utils/         # Utility function tests
└── integration/       # Full workflow tests (future)

Test Markers

Use pytest markers to categorize tests:

• @pytest.mark.unit - Unit tests (fast)
• @pytest.mark.integration - Integration tests
• @pytest.mark.requires_kicad - Requires KiCad installation
• @pytest.mark.slow - Tests taking >5 seconds
• @pytest.mark.performance - Performance benchmarks

Running Specific Tests

# Single test file
make test tests/unit/utils/test_path_validator.py

# Specific test function
make test tests/unit/utils/test_path_validator.py::test_validate_project_path

# By marker
pytest -m "unit and not slow"

Debugging Tips

Enable Verbose Logging

Add to .env:

LOG_LEVEL=DEBUG

Test IPC Connection

from mckicad.utils.ipc_client import check_kicad_availability
print(check_kicad_availability())

Test FreeRouting Setup

from mckicad.utils.freerouting_engine import check_routing_prerequisites
print(check_routing_prerequisites())

Common Issues

IPC Connection Fails:

• Ensure KiCad is running and has a project open
• Check that kicad-python (kipy) is installed
• Verify no other MCP clients are connected

FreeRouting Not Found:

• Verify JAR exists at expected location
• Test Java with: java -version
• Set FREEROUTING_JAR_PATH explicitly in .env

CLI Operations Timeout:

• Increase timeout in config.py TIMEOUT_CONSTANTS
• Check KiCad CLI is in PATH: kicad-cli version
• Verify project files aren't corrupted