@hybridlabor-api/bdb-hardware-pcb 0.1.0

package/mcp_servers/kicad-mcp-server/docs/VALIDATION.md

@@ -0,0 +1,268 @@
+# Design Rule Checking Guide
+
+Comprehensive guide for using KiCad MCP Server's design rule checking capabilities.
+
+## Overview
+
+The validation tools provide automated design rule checking (DRC) and electrical rules check (ERC) to ensure your hardware designs are correct before manufacturing.
+
+## Tools
+
+### ERC Tools
+
+#### `run_erc(schematic_path: str) -> str`
+
+Run Electrical Rules Check on a schematic file.
+
+**What it checks:**
+- Unconnected pins
+- Power conflicts (VCC to VCC, GND to GND)
+- Multiple outputs on same net
+- Pin type mismatches
+
+**Example:**
+```python
+result = run_erc("board.kicad_sch")
+if "X" in result:
+    print("ERC violations found")
+else:
+    print("No ERC violations")
+```
+
+**Returns:**
+- ✅ Pass: No violations detected
+- ❌ Fail: List of violations with severity and descriptions
+
+#### `get_erc_violations(schematic_path: str, severity: str = "") -> str`
+
+Get filtered ERC violations by severity.
+
+**Parameters:**
+- `severity`: "error", "warning", or "" for all
+
+**Example:**
+```python
+# Get only errors
+errors = get_erc_violations("board.kicad_sch", severity="error")
+
+# Get all violations
+all_violations = get_erc_violations("board.kicad_sch")
+```
+
+### DRC Tools
+
+#### `run_drc(pcb_path: str) -> str`
+
+Run Design Rules Check on a PCB file.
+
+**What it checks:**
+- Clearance violations (< 0.15mm default)
+- Track spacing violations
+- Missing connections (unrouted nets)
+- Pad/footprint overlaps
+- Board edge constraints
+
+**Example:**
+```python
+result = run_drc("board.kicad_pcb")
+if "X" in result:
+    print("DRC violations found")
+    # Parse violations and fix in KiCad
+else:
+    print("No DRC violations - ready for manufacturing")
+```
+
+#### `get_drc_violations(pcb_path: str, violation_type: str = "") -> str`
+
+Get filtered DRC violations by type.
+
+**Parameters:**
+- `violation_type`: "clearance", "spacing", "missing_connection", or "" for all
+
+**Example:**
+```python
+# Get only clearance violations
+clearance_issues = get_drc_violations("board.kicad_pcb", violation_type="clearance")
+
+# Get all violations
+all_violations = get_drc_violations("board.kicad_pcb")
+```
+
+### Export Tools
+
+#### `export_erc_report(schematic_path: str, output_path: str = "") -> str`
+#### `export_drc_report(pcb_path: str, output_path: str = "") -> str`
+
+Export validation reports to files for documentation.
+
+**Example:**
+```python
+export_erc_report("board.kicad_sch", "reports/erc_report.txt")
+export_drc_report("board.kicad_pcb", "reports/drc_report.txt")
+```
+
+## Usage Patterns
+
+### Pre-Manufacturing Checklist
+
+Before sending your design to manufacturing:
+
+```python
+# 1. Run ERC on schematic
+erc_result = run_erc("board.kicad_sch")
+assert "X" not in erc_result, "Fix ERC violations first"
+
+# 2. Run DRC on PCB
+drc_result = run_drc("board.kicad_pcb")
+assert "X" not in drc_result, "Fix DRC violations first"
+
+# 3. Export reports for documentation
+export_erc_report("board.kicad_sch", "manufacturing/erc.txt")
+export_drc_report("board.kicad_pcb", "manufacturing/drc.txt")
+
+print("OK Design ready for manufacturing")
+```
+
+### CI/CD Integration
+
+Automated validation in continuous integration:
+
+```bash
+# In your CI pipeline
+python -c "
+from kicad_mcp_server.tools import validation
+import sys
+
+# Run checks
+erc = validation.run_erc('board.kicad_sch')
+drc = validation.run_drc('board.kicad_pcb')
+
+# Fail if violations found
+if 'X' in erc or 'X' in drc:
+    sys.exit(1)
+"
+```
+
+### Iterative Design Process
+
+During design iteration:
+
+```python
+while True:
+    # Make design changes in KiCad
+    input("Make changes in KiCad, then press Enter...")
+
+    # Run validation
+    erc = run_erc("board.kicad_sch")
+    drc = run_drc("board.kicad_pcb")
+
+    # Check for violations
+    if "X" not in erc and "X" not in drc:
+        print("OK Design is clean!")
+        break
+
+    # Show violations to fix
+    print(erc)
+    print(drc)
+```
+
+## Common Violations
+
+### ERC Violations
+
+**Unconnected Input Pin**
+```
+X ERC violation detected
+Type: unconnected_input
+Component: U1
+Pin: 3 (RESET)
+Description: Unconnected input pin may cause undefined behavior
+```
+**Fix:** Connect the pin to appropriate signal or add pull-up/pull-down resistor.
+
+**Multiple Outputs on Same Net**
+```
+X ERC violation detected
+Type: multiple_outputs
+Components: U1:8, U2:3
+Description: Multiple outputs on same net can cause damage
+```
+**Fix:** Remove one output or add proper isolation (diode, buffer).
+
+**Power Conflict**
+```
+X ERC violation detected
+Type: power_conflict
+Components: U1:1, U2:1
+Description: Multiple power outputs on same net
+```
+**Fix:** Ensure only one power source per net or use proper power distribution.
+
+### DRC Violations
+
+**Clearance Violation**
+```
+X DRC violation detected
+Type: clearance
+Location: (45.2, 23.1)
+Description: Insufficient clearance (0.12mm < 0.15mm required)
+```
+**Fix:** Increase spacing between tracks/pads to meet clearance requirements.
+
+**Missing Connection**
+```
+X DRC violation detected
+Type: missing_connection
+Net: I2C_SDA
+Description: Unrouted net detected
+```
+**Fix:** Route the connection in KiCad or mark as no-route if intentional.
+
+## Best Practices
+
+1. **Run ERC Early:** Check schematic frequently during design
+2. **Run DRC After Layout:** Check PCB after routing is complete
+3. **Fix Errors First:** Always fix error-level violations before warnings
+4. **Document Exceptions:** Some warnings may be acceptable design choices
+5. **Version Control:** Commit validation reports with design files
+
+## Troubleshooting
+
+**Issue:** kicad-cli not found
+```bash
+# Install KiCad or add to PATH
+export PATH=$PATH:/path/to/kicad/bin
+```
+
+**Issue:** False positives in ERC
+- Some warnings may be intentional design choices
+- Use `get_erc_violations()` with severity filters to focus on errors
+- Document design exceptions in your project notes
+
+**Issue:** DRC takes too long
+- Check design rules in KiCad (Board Setup → Design Rules)
+- Simplify rules if too strict for your application
+- Use `get_drc_violations()` to check specific violation types
+
+## Integration with Other Tools
+
+### Before Device Tree Generation
+```python
+# Always validate before generating code
+validate_pin_configuration("board.kicad_sch")  # Run ERC/DRC first
+generate_device_tree("board.kicad_sch", "stm32f4", "board.dts")
+```
+
+### Before Test Generation
+```python
+# Ensure design is valid before generating tests
+run_erc("board.kicad_sch")
+run_drc("board.kicad_pcb")
+generate_hardware_tests("board.kicad_sch", "pytest")
+```
+
+## Resources
+
+- [KiCad Design Rules](https://docs.kicad.org/doxygen/latest/)
+- [IPC Standards](https://www.ipc.org/)
+- [Project-specific design rules](board.kicad_pcb setup)

package/mcp_servers/kicad-mcp-server/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kicad-mcp-server"
+version = "0.1.0"
+description = "Model Context Protocol server for KiCad schematic/PCB analysis and validation"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Seeed Studio" }
+]
+keywords = ["kicad", "mcp", "schematic", "pcb", "eda"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+dependencies = [
+    # The upper bounds are load-bearing. Without them pip/uv resolve
+    # fastmcp 2.14.1 + mcp 2.0.0, which install WITHOUT pydantic-settings,
+    # and the server dies on import (ModuleNotFoundError: pydantic_settings).
+    # Keep these in sync with requirements.txt.
+    "mcp[cli]>=1.27,<2",
+    "fastmcp>=3.2,<4",
+    "kicad-skip>=0.2.5",
+    "pydantic>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "jinja2>=3.1.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.12.0",
+]
+hardware = [
+    "RPi.GPIO>=0.7.0; platform_machine == 'aarch64' or platform_machine == 'armv7l'",
+    "smbus2>=0.4.0",
+    "spidev>=3.5; platform_machine == 'aarch64' or platform_machine == 'armv7l'",
+    "pyserial>=3.5",
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+all = [
+    "kicad-mcp-server[test,hardware,dev]"
+]
+
+[project.scripts]
+kicad-mcp-server = "kicad_mcp_server.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/Seeed-Studio/kicad-mcp-server"
+Documentation = "https://github.com/Seeed-Studio/kicad-mcp-server#readme"
+Issues = "https://github.com/Seeed-Studio/kicad-mcp-server/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kicad_mcp_server"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311", "py312", "py313", "py314"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

package/mcp_servers/kicad-mcp-server/requirements-dev.txt

@@ -0,0 +1,16 @@
+# Development dependencies for KiCad MCP Server
+-r requirements.txt
+
+# Testing
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+pytest-cov>=4.0.0
+
+# Code quality
+black>=23.0.0
+ruff>=0.1.0
+mypy>=1.0.0
+
+# Documentation
+sphinx>=7.0.0
+sphinx-rtd-theme>=1.3.0

package/mcp_servers/kicad-mcp-server/requirements-test.txt

@@ -0,0 +1,24 @@
+# Testing dependencies for hardware testing
+# These are optional dependencies for running hardware tests with actual hardware interaction
+
+# Python testing framework
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+pytest-cov>=4.0.0
+pytest-mock>=3.12.0
+
+# Hardware interaction libraries (optional)
+# Raspberry Pi GPIO
+RPi.GPIO>=0.7.0; platform_machine == "aarch64" or platform_machine == "armv7l"
+
+# I2C communication
+smbus2>=0.4.0
+
+# SPI communication
+spidev>=3.5; platform_machine == "aarch64" or platform_machine == "armv7l"
+
+# Serial communication
+pyserial>=3.5
+
+# Mock hardware for testing
+mock>=4.0.0

package/mcp_servers/kicad-mcp-server/requirements.txt

@@ -0,0 +1,13 @@
+# Core dependencies for KiCad MCP Server
+#
+# The upper bounds are load-bearing. Without them pip/uv resolve
+# fastmcp 2.14.1 + mcp 2.0.0, which install WITHOUT pydantic-settings, and
+# the server dies on import:
+#     ModuleNotFoundError: No module named 'pydantic_settings'
+# fastmcp 3.x is what actually provides the FastMCP API this server uses.
+mcp[cli]>=1.27,<2
+fastmcp>=3.2,<4
+kicad-skip>=0.2.5
+pydantic>=2.0.0
+python-dotenv>=1.0.0
+jinja2>=3.1.0

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""KiCad MCP Server - Model Context Protocol server for KiCad file analysis."""
+
+__version__ = "0.1.0"

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/__main__.py

@@ -0,0 +1,17 @@
+"""Main entry point for KiCad MCP Server."""
+
+
+
+def main() -> None:
+    """Entry point for running the MCP server."""
+    from .server import mcp
+
+    # show_banner=False skips log_server_banner(), which performs a *blocking*
+    # httpx.get("https://pypi.org/pypi/fastmcp/json") before stdio_server()
+    # opens the transport. That delays the initialize handshake and stalls the
+    # client entirely when PyPI is slow or unreachable.
+    mcp.run(show_banner=False)
+
+
+if __name__ == "__main__":
+    main()

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/config.py

@@ -0,0 +1,46 @@
+"""Configuration management for KiCad MCP Server."""
+
+import os
+
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+class Config:
+    """Configuration settings for the MCP server."""
+
+    def __init__(self) -> None:
+        """Initialize configuration from environment variables."""
+        # KiCad project search paths
+        project_paths_str = os.getenv("KICAD_PROJECT_PATHS", "")
+        self.kicad_project_paths: list[str] = [
+            p.strip() for p in project_paths_str.split(",") if p.strip()
+        ]
+
+        # Summary settings
+        self.default_summary_detail_level: str = os.getenv(
+            "DEFAULT_SUMMARY_DETAIL_LEVEL", "standard"
+        )
+        self.include_nets_in_summary: bool = (
+            os.getenv("INCLUDE_NETS_IN_SUMMARY", "true").lower() == "true"
+        )
+        self.include_power_in_summary: bool = (
+            os.getenv("INCLUDE_POWER_IN_SUMMARY", "true").lower() == "true"
+        )
+
+        # Test generation settings
+        self.default_test_framework: str = os.getenv("DEFAULT_TEST_FRAMEWORK", "pytest")
+        self.default_test_type: str = os.getenv("DEFAULT_TEST_TYPE", "connectivity")
+
+    @classmethod
+    def get_instance(cls) -> "Config":
+        """Get singleton instance of Config."""
+        if not hasattr(cls, "_instance"):
+            cls._instance = cls()
+        return cls._instance
+
+
+# Global config instance
+config = Config.get_instance()

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/models/__init__.py

@@ -0,0 +1 @@
+"""Data models for KiCad MCP Server."""

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/models/types.py

@@ -0,0 +1,87 @@
+"""Type definitions for KiCad MCP Server."""
+
+
+from pydantic import BaseModel, Field
+
+
+class ComponentInfo(BaseModel):
+    """Information about a schematic component."""
+
+    reference: str = Field(description="Component reference designator (e.g., R1, U1)")
+    value: str = Field(description="Component value (e.g., 10k, ATmega328P)")
+    footprint: str | None = Field(default=None, description="Assigned footprint")
+    library_id: str = Field(description="Symbol library identifier")
+    properties: dict[str, str] = Field(default_factory=dict, description="Additional properties")
+    position: tuple[float, float] = Field(description="X, Y coordinates in schematic")
+    unit: int | None = Field(default=None, description="Multi-unit part unit number")
+
+
+class NetInfo(BaseModel):
+    """Information about a net."""
+
+    name: str = Field(description="Net name")
+    code: int = Field(description="Internal net code")
+    node_count: int = Field(description="Number of connected pins")
+    pins: list[str] = Field(default_factory=list, description="Connected pins (ref:pin)")
+
+
+class PinInfo(BaseModel):
+    """Information about a component pin."""
+
+    number: str = Field(description="Pin number")
+    name: str = Field(description="Pin name/function")
+    type: str = Field(description="Electrical type (input, output, power, etc.)")
+
+
+class SymbolInfo(BaseModel):
+    """Detailed information about a schematic symbol."""
+
+    reference: str = Field(description="Component reference designator")
+    value: str = Field(description="Component value")
+    library_id: str = Field(description="Symbol library identifier")
+    pins: list[PinInfo] = Field(default_factory=list, description="Pin definitions")
+    properties: dict[str, str] = Field(default_factory=dict, description="Symbol properties")
+    unit_count: int = Field(default=1, description="Number of units in symbol")
+
+
+class FootprintInfo(BaseModel):
+    """Information about a PCB footprint."""
+
+    reference: str = Field(description="Component reference designator")
+    footprint_id: str = Field(description="Footprint library identifier")
+    value: str = Field(description="Component value")
+    layer: str = Field(description="PCB layer (F.Cu, B.Cu, etc.)")
+    position: tuple[float, float] = Field(description="X, Y coordinates")
+    rotation: float = Field(description="Rotation angle in degrees")
+    pads: int = Field(default=0, description="Number of pads")
+
+
+class PCBStatistics(BaseModel):
+    """Statistics about a PCB design."""
+
+    total_footprints: int = Field(description="Total number of footprints")
+    total_pads: int = Field(description="Total number of pads")
+    total_tracks: int = Field(description="Total number of track segments")
+    total_vias: int = Field(description="Total number of vias")
+    total_zones: int = Field(description="Total number of copper zones")
+    board_width: float = Field(description="Board width in mm")
+    board_height: float = Field(description="Board height in mm")
+    layers: int = Field(description="Number of copper layers")
+
+
+class ERCError(BaseModel):
+    """Electrical Rules Check error."""
+
+    severity: str = Field(description="Error severity (error, warning)")
+    type: str = Field(description="Error type")
+    description: str = Field(description="Error description")
+    components: list[str] = Field(default_factory=list, description="Involved components")
+
+
+class DRCError(BaseModel):
+    """Design Rules Check error."""
+
+    severity: str = Field(description="Error severity (error, warning)")
+    type: str = Field(description="Error type")
+    description: str = Field(description="Error description")
+    location: tuple[float, float] = Field(description="X, Y coordinates")

package/mcp_servers/kicad-mcp-server/src/kicad_mcp_server/parsers/__init__.py

@@ -0,0 +1 @@
+"""File parsers for KiCad MCP Server."""