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 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

## 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:**
```python
from kicad_mcp.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:**
```python
# 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`:
```toml
[project.scripts]
kicad-mcp = "kicad_mcp.server:main"
```
This enables running via `uvx kicad-mcp` after installation.

### Logging
- All logs written to `kicad-mcp.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`:
```python
from kicad_mcp.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:
   ```python
   {
       "success": bool,
       "data": Any,  # Results on success
       "error": str  # Error message on failure
   }
   ```

### Progress Reporting
For long operations, use progress constants:
```python
from kicad_mcp.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
```bash
# 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
```python
from kicad_mcp.utils.ipc_client import check_kicad_availability
print(check_kicad_availability())
```

### Test FreeRouting Setup
```python
from kicad_mcp.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