# 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
1. Identify component type (resource/tool/prompt)
2. Add implementation to appropriate module in `kicad_mcp/`
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