Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
414 lines (296 loc) · 9.52 KB

CONTRIBUTING.md

File metadata and controls

414 lines (296 loc) · 9.52 KB

Contributing to KiCAD MCP Server

Thank you for your interest in contributing to the KiCAD MCP Server! This guide will help you get started with development.

Table of Contents

Development Environment Setup

Prerequisites

  • KiCAD 9.0 or higher - Download here
  • Node.js v18+ - Download here
  • Python 3.10+ - Should come with KiCAD, or install separately
  • Git - For version control

Platform-Specific Setup

Linux (Ubuntu/Debian)

# Install KiCAD 9.0 from official PPA
sudo add-apt-repository --yes ppa:kicad/kicad-9.0-releases
sudo apt-get update
sudo apt-get install -y kicad kicad-libraries

# Install Node.js (if not already installed)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Clone the repository
git clone https://github.com/yourusername/kicad-mcp-server.git
cd kicad-mcp-server

# Install Node.js dependencies
npm install

# Install Python dependencies
pip3 install -r requirements-dev.txt

# Build TypeScript
npm run build

# Run tests
npm test
pytest

Windows

# Install KiCAD 9.0 from https://www.kicad.org/download/windows/

# Install Node.js from https://nodejs.org/

# Clone the repository
git clone https://github.com/yourusername/kicad-mcp-server.git
cd kicad-mcp-server

# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -r requirements-dev.txt

# Build TypeScript
npm run build

# Run tests
npm test
pytest

macOS

# Install KiCAD 9.0 from https://www.kicad.org/download/macos/

# Install Node.js via Homebrew
brew install node

# Clone the repository
git clone https://github.com/yourusername/kicad-mcp-server.git
cd kicad-mcp-server

# Install Node.js dependencies
npm install

# Install Python dependencies
pip3 install -r requirements-dev.txt

# Build TypeScript
npm run build

# Run tests
npm test
pytest

Project Structure

kicad-mcp-server/
├── .github/
│   └── workflows/        # CI/CD pipelines
├── config/               # Configuration examples
│   ├── linux-config.example.json
│   ├── windows-config.example.json
│   └── macos-config.example.json
├── docs/                 # Documentation
├── python/               # Python interface layer
│   ├── commands/         # KiCAD command handlers
│   ├── integrations/     # External API integrations (JLCPCB, Digikey)
│   ├── utils/            # Utility modules
│   └── kicad_interface.py  # Main Python entry point
├── src/                  # TypeScript MCP server
│   ├── tools/            # MCP tool implementations
│   ├── resources/        # MCP resource implementations
│   ├── prompts/          # MCP prompt implementations
│   └── server.ts         # Main server
├── tests/                # Test suite
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── dist/                 # Compiled JavaScript (generated)
├── node_modules/         # Node dependencies (generated)
├── package.json          # Node.js configuration
├── tsconfig.json         # TypeScript configuration
├── pytest.ini            # Pytest configuration
├── requirements.txt      # Python production dependencies
└── requirements-dev.txt  # Python dev dependencies

Architecture Overview

The KiCAD MCP Server is organized into several key components:

  • TypeScript MCP Server (src/) - Handles MCP protocol communication and tool routing
  • Python KiCAD Interface (python/) - Interfaces with KiCAD's Python API (pcbnew)
  • Tool Router - Organizes 122+ tools into 8 discoverable categories
  • Resource System - Provides dynamic project/board state information
  • Prompt System - Offers context-aware design prompts

Current Tool Count: 122+ tools across 8 categories (direct + routed)

For detailed architecture information, see docs/ROUTER_ARCHITECTURE.md.

Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name

2. Make Changes

  • Edit TypeScript files in src/
  • Edit Python files in python/
  • Add tests for new features

3. Build & Test

# Build TypeScript
npm run build

# Run TypeScript linter
npm run lint

# Run Python formatter
black python/

# Run Python type checker
mypy python/

# Run all tests
npm test
pytest

# Run specific test file
pytest tests/test_platform_helper.py -v

# Run with coverage
pytest --cov=python --cov-report=html

4. Commit Changes

git add .
git commit -m "feat: Add your feature description"

Commit Message Convention:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • test: - Adding/updating tests
  • refactor: - Code refactoring
  • chore: - Maintenance tasks

5. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Testing

Running Tests

# All tests
pytest

# Unit tests only
pytest -m unit

# Integration tests (requires KiCAD installed)
pytest -m integration

# Platform-specific tests
pytest -m linux      # Linux tests only
pytest -m windows    # Windows tests only

# With coverage report
pytest --cov=python --cov-report=term-missing

# Verbose output
pytest -v

# Stop on first failure
pytest -x

Writing Tests

Tests should be placed in tests/ directory:

# tests/test_my_feature.py
import pytest

@pytest.mark.unit
def test_my_feature():
    """Test description"""
    # Arrange
    expected = "result"

    # Act
    result = my_function()

    # Assert
    assert result == expected

@pytest.mark.integration
@pytest.mark.linux
def test_linux_integration():
    """Integration test for Linux"""
    # This test will only run on Linux in CI
    pass

Code Style

Python

We use Black for code formatting and MyPy for type checking.

# Format all Python files
black python/

# Check types
mypy python/

# Run linter
pylint python/

Python Style Guidelines:

  • Use type hints for all function signatures
  • Use pathlib.Path for file paths (not os.path)
  • Use descriptive variable names
  • Add docstrings to all public functions/classes
  • Follow PEP 8

Example:

from pathlib import Path
from typing import List, Optional

def find_kicad_libraries(search_path: Path) -> List[Path]:
    """
    Find all KiCAD symbol libraries in the given path.

    Args:
        search_path: Directory to search for .kicad_sym files

    Returns:
        List of paths to found library files

    Raises:
        ValueError: If search_path doesn't exist
    """
    if not search_path.exists():
        raise ValueError(f"Search path does not exist: {search_path}")

    return list(search_path.glob("**/*.kicad_sym"))

TypeScript

We use ESLint and Prettier for TypeScript.

# Format TypeScript files
npx prettier --write "src/**/*.ts"

# Run linter
npx eslint src/

TypeScript Style Guidelines:

  • Use interfaces for data structures
  • Use async/await for asynchronous code
  • Use descriptive variable names
  • Add JSDoc comments to exported functions

Pull Request Process

  1. Update Documentation - If you change functionality, update docs
  2. Add Tests - All new features should have tests
  3. Run CI Locally - Ensure all tests pass before pushing
  4. Create PR - Use a clear, descriptive title
  5. Request Review - Tag relevant maintainers
  6. Address Feedback - Make requested changes
  7. Merge - Maintainer will merge when approved

PR Checklist

  • Code follows style guidelines
  • All tests pass locally
  • New tests added for new features
  • Documentation updated
  • Commit messages follow convention
  • No merge conflicts
  • CI/CD pipeline passes

Roadmap & Planning

We track work using GitHub Projects and Issues:

  • GitHub Projects - High-level roadmap and sprints
  • GitHub Issues - Specific bugs and features
  • GitHub Discussions - Design discussions and proposals

Current Priorities (Week 1-4)

  1. ✅ Linux compatibility fixes
  2. ✅ Platform-agnostic path handling
  3. ✅ CI/CD pipeline setup
  4. 🔄 Migrate to KiCAD IPC API
  5. ⏳ Add JLCPCB integration
  6. ⏳ Add Digikey integration

See docs/REBUILD_PLAN.md for the complete 12-week roadmap.

Getting Help

  • GitHub Discussions - Ask questions, propose ideas
  • GitHub Issues - Report bugs, request features
  • Discord - Real-time chat (link TBD)

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank You! 🎉

Your contributions make this project better for everyone. We appreciate your time and effort!