kicad-mcp-server/docs/LINUX_COMPATIBILITY_AUDIT.md

Linux Compatibility Audit Report

Date: 2025-10-25 Target Platform: Ubuntu 24.04 LTS (primary), Fedora, Arch (secondary) Current Status: Windows-optimized, partial Linux support

---

Executive Summary

The KiCAD MCP Server was originally developed for Windows and has several compatibility issues preventing smooth operation on Linux. This audit identifies all platform-specific issues and provides remediation priorities.

Overall Status: 🟡 PARTIAL COMPATIBILITY

• ✅ TypeScript server: Good cross-platform support
• 🟡 Python interface: Mixed (some hardcoded paths)
• ❌ Configuration: Windows-specific examples
• ❌ Documentation: Windows-only instructions

---

Critical Issues (P0 - Must Fix)

1. Hardcoded Windows Paths in Config Examples

File: config/claude-desktop-config.json

"cwd": "c:/repo/KiCAD-MCP",
"PYTHONPATH": "C:/Program Files/KiCad/9.0/lib/python3/dist-packages"

Impact: Config file won't work on Linux without manual editing Fix: Create platform-specific config templates Priority: P0

---

2. Library Search Paths (Mixed Approach)

File: python/commands/library_schematic.py:16

search_paths = [
    "C:/Program Files/KiCad/*/share/kicad/symbols/*.kicad_sym",  # Windows
    "/usr/share/kicad/symbols/*.kicad_sym",                      # Linux
    "/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols/*.kicad_sym",  # macOS
]

Impact: Works but inefficient (checks all platforms) Fix: Auto-detect platform and use appropriate paths Priority: P0

---

3. Python Path Detection

File: python/kicad_interface.py:38-45

kicad_paths = [
    os.path.join(os.path.dirname(sys.executable), 'Lib', 'site-packages'),
    os.path.dirname(sys.executable)
]

Impact: Paths use Windows convention ('Lib' is 'lib' on Linux) Fix: Platform-specific path detection Priority: P0

---

High Priority Issues (P1)

4. Documentation is Windows-Only

Files: README.md, installation instructions

Issues:

• Installation paths reference C:\Program Files
• VSCode settings path is Windows format
• No Linux-specific troubleshooting

Fix: Add Linux installation section Priority: P1

---

5. Missing Python Dependencies Documentation

File: None (no requirements.txt)

Impact: Users don't know what Python packages to install Fix: Create requirements.txt and requirements-dev.txt Priority: P1

---

6. Path Handling Uses os.path Instead of pathlib

Files: All Python files (11 files)

Impact: Code is less readable and more error-prone Fix: Migrate to pathlib.Path throughout Priority: P1

---

Medium Priority Issues (P2)

7. No Linux-Specific Testing

Impact: Can't verify Linux compatibility Fix: Add GitHub Actions with Ubuntu runner Priority: P2

---

8. Log File Paths May Differ

File: src/logger.ts:13

const DEFAULT_LOG_DIR = join(os.homedir(), ".kicad-mcp", "logs");

Impact: .kicad-mcp is okay for Linux, but best practice is ~/.config/kicad-mcp Fix: Use XDG Base Directory spec on Linux Priority: P2

---

9. No Bash/Shell Scripts for Linux

Impact: Manual setup is harder on Linux Fix: Create install.sh and run.sh scripts Priority: P2

---

Low Priority Issues (P3)

10. TypeScript Build Uses Windows Conventions

File: package.json

Impact: Works but could be more Linux-friendly Fix: Add platform-specific build scripts Priority: P3

---

Positive Findings ✅

What's Already Good:

1. TypeScript Path Handling - Uses path.join() and os.homedir() correctly
2. Node.js Dependencies - All cross-platform
3. JSON Communication - Platform-agnostic
4. Python Base - Python 3 works identically on all platforms

---

Recommended Fixes - Priority Order

Week 1 - Critical Fixes (P0)

1. Create Platform-Specific Config Templates

   config/
   ├── linux-config.example.json
   ├── windows-config.example.json
   └── macos-config.example.json
   

2. Fix Python Path Detection

   # Detect platform and set appropriate paths
   import platform
   import sys
   from pathlib import Path
   
   if platform.system() == "Windows":
       kicad_paths = [Path(sys.executable).parent / "Lib" / "site-packages"]
   else:  # Linux/Mac
       kicad_paths = [Path(sys.executable).parent / "lib" / "python3.X" / "site-packages"]
   

3. Update Library Search Path Logic

   def get_kicad_library_paths():
       """Auto-detect KiCAD library paths based on platform"""
       system = platform.system()
       if system == "Windows":
           return ["C:/Program Files/KiCad/*/share/kicad/symbols/*.kicad_sym"]
       elif system == "Linux":
           return ["/usr/share/kicad/symbols/*.kicad_sym"]
       elif system == "Darwin":  # macOS
           return ["/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols/*.kicad_sym"]
   

Week 1 - High Priority (P1)

4. Create requirements.txt

   # requirements.txt
   kicad-skip>=0.1.0
   Pillow>=9.0.0
   cairosvg>=2.7.0
   colorlog>=6.7.0
   

5. Add Linux Installation Documentation

   • Ubuntu/Debian instructions
   • Fedora/RHEL instructions
   • Arch Linux instructions

6. Migrate to pathlib

   • Convert all os.path calls to Path
   • More Pythonic and readable

---

Testing Checklist

Ubuntu 24.04 LTS Testing

• Install KiCAD 9.0 from official PPA
• Install Node.js 18+ from NodeSource
• Clone repository
• Run npm install
• Run npm run build
• Configure MCP settings (Cline)
• Test: Create project
• Test: Place components
• Test: Export Gerbers

Fedora Testing

• Install KiCAD from Fedora repos
• Test same workflow

Arch Testing

• Install KiCAD from AUR
• Test same workflow

---

Platform Detection Helper

Create python/utils/platform_helper.py:

"""Platform detection and path utilities"""
import platform
import sys
from pathlib import Path
from typing import List

class PlatformHelper:
    @staticmethod
    def is_windows() -> bool:
        return platform.system() == "Windows"

    @staticmethod
    def is_linux() -> bool:
        return platform.system() == "Linux"

    @staticmethod
    def is_macos() -> bool:
        return platform.system() == "Darwin"

    @staticmethod
    def get_kicad_python_path() -> Path:
        """Get KiCAD Python dist-packages path"""
        if PlatformHelper.is_windows():
            return Path("C:/Program Files/KiCad/9.0/lib/python3/dist-packages")
        elif PlatformHelper.is_linux():
            # Common Linux paths
            candidates = [
                Path("/usr/lib/kicad/lib/python3/dist-packages"),
                Path("/usr/share/kicad/scripting/plugins"),
            ]
            for path in candidates:
                if path.exists():
                    return path
        elif PlatformHelper.is_macos():
            return Path("/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.X/lib/python3.X/site-packages")

        raise RuntimeError(f"Could not find KiCAD Python path for {platform.system()}")

    @staticmethod
    def get_config_dir() -> Path:
        """Get appropriate config directory"""
        if PlatformHelper.is_windows():
            return Path.home() / ".kicad-mcp"
        elif PlatformHelper.is_linux():
            # Use XDG Base Directory specification
            xdg_config = os.environ.get("XDG_CONFIG_HOME")
            if xdg_config:
                return Path(xdg_config) / "kicad-mcp"
            return Path.home() / ".config" / "kicad-mcp"
        elif PlatformHelper.is_macos():
            return Path.home() / "Library" / "Application Support" / "kicad-mcp"

---

Success Criteria

✅ Server starts on Ubuntu 24.04 LTS without errors ✅ Can create and manipulate KiCAD projects ✅ CI/CD pipeline tests on Linux ✅ Documentation includes Linux setup ✅ All tests pass on Linux

---

Next Steps

1. Implement P0 fixes (this week)
2. Set up GitHub Actions CI/CD
3. Test on Ubuntu 24.04 LTS
4. Document Linux-specific issues
5. Create installation scripts

---

Audited by: Claude Code Review Status: ✅ Complete