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`

```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`

```python
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`

```python
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`

```typescript
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**

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

2. **Fix Python Path Detection**

   ```python
   # 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**
   ```python
   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**

   ```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`:

```python
"""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