Merge branch 'main' into pr-3-security-input-validation

Author: lamaalrajih

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,11 +1,3 @@
----
-name: Bug Report
-about: Report a bug or issue with the KiCad MCP Server
-title: "[BUG] "
-labels: bug
-assignees: ''
----
-
 ## Bug Description
 <!-- A clear and concise description of the bug -->
 

.github/workflows/ci.yml

@@ -120,4 +120,4 @@ jobs:
       uses: actions/upload-artifact@v4
       with:
         name: dist
-        path: dist/
+        path: dist/

.gitignore

@@ -18,6 +18,11 @@ __pycache__/
 dist/
 build/
 *.egg-info/
+*.egg
+*.whl
+
+# PyPI
+.pypirc
 
 # Unit test / coverage reports
 htmlcov/
@@ -28,6 +33,7 @@ htmlcov/
 nosetests.xml
 coverage.xml
 *.cover
+.pytest_cache/
 
 # Logs
 logs/
@@ -42,3 +48,25 @@ logs/
 
 # MCP specific
 ~/.kicad_mcp/drc_history/
+
+# UV and modern Python tooling
+uv.lock
+.uv-cache/
+.ruff_cache/
+
+# Pre-commit
+.pre-commit-config.yaml
+
+# KiCad backup files
+*-backups/
+fp-info-cache
+*.bak
+*.backup
+*.kicad_pcb-bak
+*.kicad_sch-bak
+*.kicad_pro-bak
+*.kicad_prl
+*.kicad_prl-bak
+*.kicad_sch.lck
+*.kicad_pcb.lck
+*.kicad_pro.lck

.python-version

@@ -0,0 +1 @@
+3.10

MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include requirements.txt
+include .env.example
+recursive-include kicad_mcp *.py
+recursive-include docs *.md

Makefile

@@ -0,0 +1,39 @@
+.PHONY: help install test lint format clean build run
+
+help:
+	@echo "Available commands:"
+	@echo "  install     Install dependencies"
+	@echo "  test        Run tests"
+	@echo "  lint        Run linting"
+	@echo "  format      Format code"
+	@echo "  clean       Clean build artifacts"
+	@echo "  build       Build package"
+
+install:
+	uv sync --group dev
+
+test:
+	uv run python -m pytest tests/ -v
+
+lint:
+	uv run ruff check kicad_mcp/ tests/
+	uv run mypy kicad_mcp/
+
+format:
+	uv run ruff format kicad_mcp/ tests/
+
+clean:
+	rm -rf dist/
+	rm -rf build/
+	rm -rf *.egg-info/
+	rm -rf .pytest_cache/
+	rm -rf htmlcov/
+	rm -f coverage.xml
+	find . -type d -name __pycache__ -delete
+	find . -type f -name "*.pyc" -delete
+
+build:
+	uv build
+
+run:
+	uv run python main.py

README.md

@@ -22,6 +22,7 @@ This guide will help you set up a Model Context Protocol (MCP) server for KiCad.
 - macOS, Windows, or Linux
 - Python 3.10 or higher
 - KiCad 9.0 or higher
+- uv 0.8.0 or higher
 - Claude Desktop (or another MCP client)
 
 ## Installation Steps
@@ -32,14 +33,15 @@ First, let's install dependencies and set up our environment:
 
 ```bash
 # Clone the repository
-git clone https://github.com/lamaalrajih/kicad-mcp.git .
+git clone https://github.com/lamaalrajih/kicad-mcp.git
+cd kicad-mcp
 
-# Create a virtual environment and activate it
-python3 -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
+# Install dependencies – `uv` will create a `.venv/` folder automatically
+# (Install `uv` first: `brew install uv` on macOS or `pipx install uv`)
+make install
 
-# Install the MCP SDK and other dependencies
-pip install -r requirements.txt
+# Optional: activate the environment for manual commands
+source .venv/bin/activate
 ```
 
 ### 2. Configure Your Environment
@@ -89,7 +91,7 @@ vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
 {
     "mcpServers": {
         "kicad": {
-            "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/venv/bin/python",
+            "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/.venv/bin/python",
             "args": [
                 "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py"
             ]

kicad_mcp/__init__.py

@@ -3,5 +3,27 @@
 
 A Model Context Protocol (MCP) server for KiCad electronic design automation (EDA) files.
 """
+from .server import *
+from .config import *
+from .context import *
 
-__version__ = "0.2.0"
+__version__ = "0.1.0"
+__author__ = "Lama Al Rajih"
+__description__ = "Model Context Protocol server for KiCad on Mac, Windows, and Linux"
+
+__all__ = [
+    # Package metadata
+    "__version__",
+    "__author__",
+    "__description__",
+
+    # Server creation / shutdown helpers
+    "create_server",
+    "add_cleanup_handler",
+    "run_cleanup_handlers",
+    "shutdown_server",
+
+    # Lifespan / context helpers
+    "kicad_lifespan",
+    "KiCadAppContext",
+]

kicad_mcp/server.py

@@ -5,8 +5,9 @@
 import os
 import signal
 import logging
+import functools
 from typing import Callable
-from mcp.server.fastmcp import FastMCP
+from fastmcp import FastMCP
 
 # Import resource handlers
 from kicad_mcp.resources.projects import register_project_resources
@@ -127,9 +128,11 @@ def create_server() -> FastMCP:
     # Always print this now, as we rely on CLI
     logging.info(f"KiCad Python module setup removed; relying on kicad-cli for external operations.")
 
+    # Build a lifespan callable with the kwarg baked in (FastMCP 2.x dropped lifespan_kwargs)
+    lifespan_factory = functools.partial(kicad_lifespan, kicad_modules_available=kicad_modules_available)
+
     # Initialize FastMCP server
-    # Pass the availability flag (always False now) to the lifespan context
-    mcp = FastMCP("KiCad", lifespan=kicad_lifespan, lifespan_kwargs={"kicad_modules_available": kicad_modules_available})
+    mcp = FastMCP("KiCad", lifespan=lifespan_factory)
     logging.info(f"Created FastMCP server instance with lifespan management")
 
     # Register resources
@@ -186,3 +189,43 @@ def cleanup_temp_dirs():
 
     logging.info(f"Server initialization complete")
     return mcp
+
+
+def setup_signal_handlers() -> None:
+    """Setup signal handlers for graceful shutdown."""
+    # Signal handlers are set up in register_signal_handlers
+    pass
+
+
+def cleanup_handler() -> None:
+    """Handle cleanup during shutdown."""
+    run_cleanup_handlers()
+
+
+def setup_logging() -> None:
+    """Configure logging for the server."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+
+
+def main() -> None:
+    """Start the KiCad MCP server (blocking)."""
+    setup_logging()
+    logging.info("Starting KiCad MCP server...")
+    
+    server = create_server()
+    
+    try:
+        server.run()  # FastMCP manages its own event loop
+    except KeyboardInterrupt:
+        logging.info("Server interrupted by user")
+    except Exception as e:
+        logging.error(f"Server error: {e}")
+    finally:
+        logging.info("Server shutdown complete")
+
+
+if __name__ == "__main__":
+    main()

kicad_mcp/tools/export_tools.py

@@ -20,7 +20,7 @@ def register_export_tools(mcp: FastMCP) -> None:
     """
 
     @mcp.tool()
-    async def generate_pcb_thumbnail(project_path: str, ctx: Context) -> Optional[Image]:
+    async def generate_pcb_thumbnail(project_path: str, ctx: Context):
         """Generate a thumbnail image of a KiCad PCB layout using kicad-cli.
 
         Args:
@@ -88,14 +88,14 @@ async def generate_pcb_thumbnail(project_path: str, ctx: Context) -> Optional[Im
             return None
 
     @mcp.tool()
-    async def generate_project_thumbnail(project_path: str, ctx: Context) -> Optional[Image]:
+    async def generate_project_thumbnail(project_path: str, ctx: Context):
         """Generate a thumbnail of a KiCad project's PCB layout (Alias for generate_pcb_thumbnail)."""
         # This function now just calls the main CLI-based thumbnail generator
         print(f"generate_project_thumbnail called, redirecting to generate_pcb_thumbnail for {project_path}")
         return await generate_pcb_thumbnail(project_path, ctx)
 
 # Helper functions for thumbnail generation
-async def generate_thumbnail_with_cli(pcb_file: str, ctx: Context) -> Optional[Image]:
+async def generate_thumbnail_with_cli(pcb_file: str, ctx: Context):
     """Generate PCB thumbnail using command line tools.
     This is a fallback method when the kicad Python module is not available or fails.