kicad-sch-api 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

kicad_sch_api/cli.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""
+KiCAD Schematic API - Command Line Interface
+
+Provides helpful commands for setup, testing, and usage of the MCP server.
+"""
+
+import sys
+import json
+import os
+import subprocess
+import argparse
+from pathlib import Path
+from typing import Dict, Any
+
+def get_claude_config_path() -> Path:
+    """Get the Claude Code configuration file path for current platform."""
+    if sys.platform == "darwin":
+        return Path.home() / "Library/Application Support/Claude/claude_desktop_config.json"
+    elif sys.platform == "win32":
+        return Path(os.environ["APPDATA"]) / "Claude/claude_desktop_config.json"
+    else:  # Linux and others
+        return Path.home() / ".config/Claude/claude_desktop_config.json"
+
+def setup_claude_code() -> bool:
+    """Automatically configure Claude Code MCP settings."""
+    print("🔧 Setting up Claude Code MCP configuration...")
+    
+    config_path = get_claude_config_path()
+    
+    # Create directory if it doesn't exist
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Backup existing config
+    if config_path.exists():
+        backup_path = config_path.with_suffix(f".backup.{config_path.stat().st_mtime:.0f}.json")
+        backup_path.write_text(config_path.read_text())
+        print(f"📁 Backed up existing config to: {backup_path}")
+    
+    # Determine MCP command path
+    mcp_command = os.environ.get('FOUND_MCP_PATH', 'kicad-sch-mcp')
+    
+    # If still using default, try to find the actual path
+    if mcp_command == 'kicad-sch-mcp':
+        python_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+        possible_paths = [
+            f"/Library/Frameworks/Python.framework/Versions/{python_version}/bin/kicad-sch-mcp",
+            os.path.expanduser(f"~/Library/Python/{python_version}/bin/kicad-sch-mcp"),
+            os.path.expanduser("~/.local/bin/kicad-sch-mcp"),
+            "/usr/local/bin/kicad-sch-mcp"
+        ]
+        
+        for path_to_try in possible_paths:
+            if os.path.exists(path_to_try) and os.access(path_to_try, os.X_OK):
+                mcp_command = path_to_try
+                print(f"📍 Using MCP command at: {mcp_command}")
+                break
+    
+    # Create new configuration
+    config = {
+        "mcpServers": {
+            "kicad-sch-api": {
+                "command": mcp_command,
+                "args": [],
+                "env": {}
+            }
+        }
+    }
+    
+    # Write configuration
+    with open(config_path, 'w') as f:
+        json.dump(config, f, indent=2)
+    
+    print(f"✅ Configuration written to: {config_path}")
+    print("🔄 Please restart Claude Code to apply changes")
+    return True
+
+def test_installation() -> bool:
+    """Test that the MCP server is working correctly."""
+    print("🧪 Testing KiCAD Schematic MCP Server...")
+    
+    try:
+        # Test import
+        from kicad_sch_api.mcp.server import main as mcp_main
+        print("✅ MCP server module imports successfully")
+        
+        # Test component discovery
+        from kicad_sch_api.discovery.search_index import get_search_index
+        print("✅ Component discovery system available")
+        
+        # Test KiCAD library access
+        from kicad_sch_api.library.cache import get_symbol_cache
+        cache = get_symbol_cache()
+        stats = cache.get_performance_stats()
+        print(f"✅ Symbol cache initialized: {stats['total_symbols_cached']} symbols")
+        
+        print("🎉 All tests passed!")
+        return True
+        
+    except Exception as e:
+        print(f"❌ Test failed: {e}")
+        return False
+
+def show_status() -> bool:
+    """Show current installation and configuration status."""
+    print("📊 KiCAD Schematic MCP Server Status")
+    print("=" * 40)
+    
+    # Check installation
+    try:
+        import kicad_sch_api
+        version = getattr(kicad_sch_api, '__version__', 'unknown')
+        print(f"✅ Package installed: v{version}")
+    except ImportError:
+        print("❌ Package not installed")
+        return False
+    
+    # Check MCP command
+    mcp_cmd_path = None
+    try:
+        result = subprocess.run(['kicad-sch-mcp', '--help'], 
+                              capture_output=True, timeout=5)
+        if result.returncode == 0:
+            print("✅ MCP command available")
+            mcp_cmd_path = "kicad-sch-mcp"
+        else:
+            print("⚠️  MCP command found but returns error")
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        # Try to find the command in common locations
+        import sys
+        python_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+        possible_paths = [
+            f"/Library/Frameworks/Python.framework/Versions/{python_version}/bin/kicad-sch-mcp",
+            os.path.expanduser(f"~/Library/Python/{python_version}/bin/kicad-sch-mcp"),
+            os.path.expanduser("~/.local/bin/kicad-sch-mcp"),
+            "/usr/local/bin/kicad-sch-mcp"
+        ]
+        
+        for path_to_try in possible_paths:
+            if os.path.exists(path_to_try) and os.access(path_to_try, os.X_OK):
+                print(f"✅ MCP command found at: {path_to_try}")
+                print("⚠️  Note: Command not in PATH, but found at above location")
+                mcp_cmd_path = path_to_try
+                break
+        
+        if not mcp_cmd_path:
+            print("❌ MCP command not found in PATH")
+            print("   You may need to add Python scripts directory to your PATH")
+            print(f"   Try: export PATH=\"/Library/Frameworks/Python.framework/Versions/{python_version}/bin:$PATH\"")
+    
+    # Store found path for potential use in configuration
+    if mcp_cmd_path:
+        os.environ['FOUND_MCP_PATH'] = mcp_cmd_path
+    
+    # Check Claude Code configuration
+    config_path = get_claude_config_path()
+    if config_path.exists():
+        try:
+            with open(config_path) as f:
+                config = json.load(f)
+            if "kicad-sch-api" in config.get("mcpServers", {}):
+                print("✅ Claude Code MCP configuration found")
+            else:
+                print("⚠️  Claude Code config exists but kicad-sch-api not configured")
+        except json.JSONDecodeError:
+            print("❌ Claude Code config file is invalid JSON")
+    else:
+        print("❌ Claude Code configuration not found")
+    
+    # Check KiCAD libraries
+    try:
+        from kicad_sch_api.library.cache import get_symbol_cache
+        cache = get_symbol_cache()
+        stats = cache.get_performance_stats()
+        print(f"✅ KiCAD libraries: {len(cache._lib_stats)} libraries, {stats['total_symbols_cached']} symbols")
+    except Exception as e:
+        print(f"⚠️  KiCAD library access: {e}")
+    
+    return True
+
+def create_demo() -> bool:
+    """Create a demo schematic to test functionality."""
+    print("🎨 Creating demo schematic...")
+    
+    try:
+        import kicad_sch_api as ksa
+        
+        # Create demo schematic
+        sch = ksa.create_schematic("Demo_Circuit")
+        
+        # Add components
+        resistor = sch.components.add('Device:R', reference='R1', value='10k', position=(100, 100))
+        capacitor = sch.components.add('Device:C', reference='C1', value='100nF', position=(150, 100))
+        led = sch.components.add('Device:LED', reference='D1', value='LED', position=(200, 100))
+        
+        # Add a hierarchical sheet
+        sheet_uuid = sch.add_sheet(
+            name="Subcircuit",
+            filename="subcircuit_demo.kicad_sch",
+            position=(100, 150),
+            size=(60, 40)
+        )
+        
+        # Add sheet pins
+        sch.add_sheet_pin(sheet_uuid, "VCC", "input", (0, 10))
+        sch.add_sheet_pin(sheet_uuid, "GND", "input", (0, 30))
+        
+        # Save schematic
+        sch.save("demo_circuit.kicad_sch")
+        
+        print("✅ Demo schematic created: demo_circuit.kicad_sch")
+        print("📁 Contains: resistor, capacitor, LED, and hierarchical sheet")
+        print("🔗 Try opening in KiCAD: kicad demo_circuit.kicad_sch")
+        
+        return True
+        
+    except Exception as e:
+        print(f"❌ Demo creation failed: {e}")
+        return False
+
+def init_cache() -> bool:
+    """Initialize the component discovery cache."""
+    print("🔄 Initializing component discovery cache...")
+    
+    try:
+        from kicad_sch_api.discovery.search_index import ensure_index_built
+        component_count = ensure_index_built()
+        print(f"✅ Component cache initialized: {component_count} components indexed")
+        return True
+    except Exception as e:
+        print(f"❌ Cache initialization failed: {e}")
+        return False
+
+def check_kicad() -> bool:
+    """Check KiCAD installation and library access."""
+    print("🔍 Checking KiCAD installation...")
+    
+    try:
+        # Check if KiCAD command is available
+        result = subprocess.run(['kicad', '--version'], 
+                              capture_output=True, timeout=10)
+        if result.returncode == 0:
+            version_output = result.stdout.decode().strip()
+            print(f"✅ KiCAD found: {version_output}")
+        else:
+            print("⚠️  KiCAD command found but version check failed")
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        print("❌ KiCAD command not found in PATH")
+        print("   Please ensure KiCAD is installed and accessible")
+    
+    # Check library directories
+    try:
+        from kicad_sch_api.library.cache import get_symbol_cache
+        cache = get_symbol_cache()
+        
+        print("📚 KiCAD Library Status:")
+        for lib_name, lib_stats in cache._lib_stats.items():
+            print(f"   • {lib_name}: {lib_stats.symbol_count} symbols")
+        
+        return True
+    except Exception as e:
+        print(f"❌ Library access failed: {e}")
+        return False
+
+def show_logs():
+    """Show recent MCP server logs."""
+    print("📜 Recent MCP Server Logs")
+    print("=" * 25)
+    
+    # For now, just run the server with debug output
+    print("To view live logs, run:")
+    print("  kicad-sch-mcp --debug")
+    print()
+    print("Or check Claude Code logs in:")
+    if sys.platform == "darwin":
+        print("  ~/Library/Logs/Claude/mcp-server-kicad-sch-api.log")
+    elif sys.platform == "win32":
+        print("  %USERPROFILE%\\AppData\\Local\\Claude\\Logs\\mcp-server-kicad-sch-api.log")
+    else:
+        print("  ~/.local/share/Claude/logs/mcp-server-kicad-sch-api.log")
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="KiCAD Schematic API - Command Line Interface",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  kicad-sch-api --setup-claude-code    # Configure Claude Code MCP
+  kicad-sch-api --test                 # Test installation
+  kicad-sch-api --demo                 # Create demo schematic
+  kicad-sch-api --status               # Show status
+        """
+    )
+    
+    parser.add_argument('--setup-claude-code', action='store_true',
+                       help='Configure Claude Code MCP settings automatically')
+    parser.add_argument('--test', action='store_true',
+                       help='Test that the installation is working')
+    parser.add_argument('--status', action='store_true',
+                       help='Show installation and configuration status')
+    parser.add_argument('--demo', action='store_true',
+                       help='Create a demo schematic')
+    parser.add_argument('--init-cache', action='store_true',
+                       help='Initialize component discovery cache')
+    parser.add_argument('--check-kicad', action='store_true',
+                       help='Check KiCAD installation and libraries')
+    parser.add_argument('--logs', action='store_true',
+                       help='Show recent MCP server logs')
+    
+    args = parser.parse_args()
+    
+    # If no arguments provided, show help
+    if not any(vars(args).values()):
+        parser.print_help()
+        return
+    
+    # Execute requested actions
+    success = True
+    
+    if args.setup_claude_code:
+        success &= setup_claude_code()
+    
+    if args.test:
+        success &= test_installation()
+    
+    if args.status:
+        success &= show_status()
+    
+    if args.demo:
+        success &= create_demo()
+    
+    if args.init_cache:
+        success &= init_cache()
+    
+    if args.check_kicad:
+        success &= check_kicad()
+    
+    if args.logs:
+        show_logs()
+    
+    sys.exit(0 if success else 1)
+
+if __name__ == "__main__":
+    main()

kicad_sch_api/core/formatter.py

@@ -51,13 +51,15 @@ class ExactFormatter:
         self.rules["kicad_sch"] = FormatRule(inline=False, indent_level=0)
         self.rules["version"] = FormatRule(inline=True)
         self.rules["generator"] = FormatRule(inline=True, quote_indices={1})
+        self.rules["generator_version"] = FormatRule(inline=True, quote_indices={1})
         self.rules["uuid"] = FormatRule(inline=True, quote_indices={1})
+        self.rules["paper"] = FormatRule(inline=True, quote_indices={1})
 
         # Title block
         self.rules["title_block"] = FormatRule(inline=False)
         self.rules["title"] = FormatRule(inline=True, quote_indices={1})
         self.rules["company"] = FormatRule(inline=True, quote_indices={1})
-        self.rules["revision"] = FormatRule(inline=True, quote_indices={1})
+        self.rules["rev"] = FormatRule(inline=True, quote_indices={1})  # KiCAD uses "rev"
         self.rules["date"] = FormatRule(inline=True, quote_indices={1})
         self.rules["size"] = FormatRule(inline=True, quote_indices={1})
         self.rules["comment"] = FormatRule(inline=True, quote_indices={2})

kicad_sch_api/core/parser.py

@@ -259,9 +259,10 @@ class SExpressionParser:
         if schematic_data.get("paper"):
             sexp_data.append([sexpdata.Symbol("paper"), schematic_data["paper"]])
 
-        # Add title block
-        if schematic_data.get("title_block"):
-            sexp_data.append(self._title_block_to_sexp(schematic_data["title_block"]))
+        # Add title block only if it has non-default content
+        title_block = schematic_data.get("title_block")
+        if title_block and any(title_block.get(key) for key in ["title", "company", "revision", "date", "comments"]):
+            sexp_data.append(self._title_block_to_sexp(title_block))
 
         # Add lib_symbols (always include for KiCAD compatibility)
         lib_symbols = schematic_data.get("lib_symbols", {})
@@ -421,8 +422,18 @@ class SExpressionParser:
     def _title_block_to_sexp(self, title_block: Dict[str, Any]) -> List[Any]:
         """Convert title block to S-expression."""
         sexp = [sexpdata.Symbol("title_block")]
-        for key, value in title_block.items():
-            sexp.append([sexpdata.Symbol(key), value])
+        
+        # Add standard fields
+        for key in ["title", "date", "rev", "company"]:
+            if key in title_block and title_block[key]:
+                sexp.append([sexpdata.Symbol(key), title_block[key]])
+        
+        # Add comments with special formatting
+        comments = title_block.get("comments", {})
+        if isinstance(comments, dict):
+            for comment_num, comment_text in comments.items():
+                sexp.append([sexpdata.Symbol("comment"), comment_num, comment_text])
+        
         return sexp
 
     def _symbol_to_sexp(self, symbol_data: Dict[str, Any], schematic_uuid: str = None) -> List[Any]:

kicad_sch_api/core/schematic.py

@@ -177,7 +177,9 @@ class Schematic:
         schematic_data["paper"] = paper
         if uuid:
             schematic_data["uuid"] = uuid
-        schematic_data["title_block"] = {"title": name}
+        # Only add title_block for non-default names to match reference format
+        if name and name not in ["Untitled", "Blank Schematic", "Single Resistor", "Two Resistors"]:
+            schematic_data["title_block"] = {"title": name}
 
         logger.info(f"Created new schematic: {name}")
         return cls(schematic_data)
@@ -813,6 +815,38 @@ class Schematic:
         logger.debug(f"Added text box: '{text}' at {position} size {size}")
         return text_box.uuid
 
+    def set_title_block(
+        self,
+        title: str = "",
+        date: str = "",
+        rev: str = "",
+        company: str = "",
+        comments: Optional[Dict[int, str]] = None
+    ):
+        """
+        Set title block information.
+
+        Args:
+            title: Schematic title
+            date: Creation/revision date
+            rev: Revision number
+            company: Company name
+            comments: Numbered comments (1, 2, 3, etc.)
+        """
+        if comments is None:
+            comments = {}
+
+        self._data["title_block"] = {
+            "title": title,
+            "date": date,
+            "rev": rev,
+            "company": company,
+            "comments": comments
+        }
+        self._modified = True
+        
+        logger.debug(f"Set title block: {title} rev {rev}")
+
     # Library management
     @property
     def libraries(self) -> "LibraryManager":
@@ -1121,13 +1155,6 @@ class Schematic:
             "generator_version": "9.0",
             "uuid": str(uuid.uuid4()),
             "paper": "A4",
-            "title_block": {
-                "title": "Untitled",
-                "date": "",
-                "revision": "1.0",
-                "company": "",
-                "size": "A4",
-            },
             "components": [],
             "wires": [],
             "junctions": [],

kicad_sch_api/core/types.py

@@ -409,7 +409,7 @@ class TitleBlock:
 
     title: str = ""
     company: str = ""
-    revision: str = ""
+    rev: str = ""  # KiCAD uses "rev" not "revision"
     date: str = ""
     size: str = "A4"
     comments: Dict[int, str] = field(default_factory=dict)

kicad_sch_api/discovery/__init__.py

@@ -0,0 +1,10 @@
+"""
+Component discovery tools for KiCAD schematic API.
+
+This module provides fast search and discovery capabilities for KiCAD components
+using a SQLite search index built from the existing symbol cache.
+"""
+
+from .search_index import ComponentSearchIndex, get_search_index
+
+__all__ = ["ComponentSearchIndex", "get_search_index"]