Ryan Malloy 995dfd57c1 Add comprehensive advanced KiCad features and fix MCP compatibility issues

- Implement 3D model analysis and mechanical constraints checking
- Add advanced DRC rule customization for HDI, RF, and automotive applications
- Create symbol library management with analysis and validation tools
- Implement PCB layer stack-up analysis with impedance calculations
- Fix Context parameter validation errors causing client failures
- Add enhanced tool annotations with examples for better LLM compatibility
- Include comprehensive test coverage improvements (22.21% coverage)
- Add CLAUDE.md documentation for development guidance

New Advanced Tools:
• 3D model analysis: analyze_3d_models, check_mechanical_constraints
• Advanced DRC: create_drc_rule_set, analyze_pcb_drc_violations
• Symbol management: analyze_symbol_library, validate_symbol_library
• Layer analysis: analyze_pcb_stackup, calculate_trace_impedance

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-08-11 15:57:46 -06:00

4.5 KiB

Raw Blame History

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 kicad_mcp/ tests/ + uv run mypy kicad_mcp/)
make format - Format code with ruff (uv run ruff format kicad_mcp/ 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 (`kicad_mcp/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 (`kicad_mcp/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 (`kicad_mcp/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

kicad_mcp/
├── 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

Identify component type (resource/tool/prompt)
Add implementation to appropriate module in kicad_mcp/
Register in server.py create_server() function
Use lifespan context for shared state and caching
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

4.5 KiB Raw Blame History