Ryan Malloy
995dfd57c1
- 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>
124 lines
4.5 KiB
Markdown
124 lines
4.5 KiB
Markdown
# 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 |