From 8a1cb46b39f59f93fb3dcae5bce8959d0e797428 Mon Sep 17 00:00:00 2001
From: KiCAD MCP Bot <kicad-mcp@example.com>
Date: Sun, 28 Dec 2025 11:35:59 -0500
Subject: [PATCH] fix: Add macOS support for KiCad bundled Python detection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds macOS-specific detection for KiCad's bundled Python, eliminating manual
PYTHONPATH configuration for macOS users.

Changes:
- Detects KiCad bundled Python at standard macOS install path (Python 3.9-3.12)
- Makes KICAD_PYTHON environment variable cross-platform (not just Windows)
- Adds logging for Python detection to aid debugging
- Updates documentation with simplified macOS setup (no PYTHONPATH needed)

Fixes server startup on macOS where existsSync('python3') was failing validation
because it doesn't check PATH.

Based on PR #18 by @hexatriene - applied manually due to merge conflict with
router implementation. Full credit to hexatriene for the solution design and
implementation.

Co-authored-by: hexatriene <106840313+hexatriene@users.noreply.github.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 docs/CLIENT_CONFIGURATION.md | 24 ++++++++++++++++++------
 src/server.ts                | 24 ++++++++++++++++++++----
 2 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/docs/CLIENT_CONFIGURATION.md b/docs/CLIENT_CONFIGURATION.md
index f875ab1..430a1ea 100644
--- a/docs/CLIENT_CONFIGURATION.md
+++ b/docs/CLIENT_CONFIGURATION.md
@@ -46,17 +46,29 @@ This guide shows how to configure the KiCAD MCP Server with various MCP-compatib
   "mcpServers": {
     "kicad": {
       "command": "node",
-      "args": ["/Users/YOUR_USERNAME/MCP/KiCAD-MCP-Server/dist/index.js"],
-      "env": {
-        "PYTHONPATH": "/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/lib/python3.11/site-packages",
-        "NODE_ENV": "production"
-      }
+      "args": ["/Users/YOUR_USERNAME/MCP/KiCAD-MCP-Server/dist/index.js"]
     }
   }
 }
 ```
 
-**Note:** Adjust Python version (3.11) and KiCAD path based on your installation.
+**Note:** For standard KiCad installations in `/Applications/KiCad/`, the server auto-detects KiCad's bundled Python (versions 3.9-3.12). No `PYTHONPATH` configuration is required.
+
+If KiCad is installed in a non-standard location, you can override the Python path:
+
+```json
+{
+  "mcpServers": {
+    "kicad": {
+      "command": "node",
+      "args": ["/Users/YOUR_USERNAME/MCP/KiCAD-MCP-Server/dist/index.js"],
+      "env": {
+        "KICAD_PYTHON": "/custom/path/to/python3"
+      }
+    }
+  }
+}
+```
 
 ### Windows Configuration
 
diff --git a/src/server.ts b/src/server.ts
index 3a1fe8d..4326aeb 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -56,16 +56,32 @@ function findPythonExecutable(scriptPath: string): string {
     }
   }
 
-  // Fall back to system Python or environment-specified Python
-  if (isWindows && process.env.KICAD_PYTHON) {
-    // Allow override via KICAD_PYTHON environment variable
+  // Allow override via KICAD_PYTHON environment variable (any platform)
+  if (process.env.KICAD_PYTHON) {
+    logger.info(`Using KICAD_PYTHON environment variable: ${process.env.KICAD_PYTHON}`);
     return process.env.KICAD_PYTHON;
-  } else if (isWindows && process.env.PYTHONPATH?.includes('KiCad')) {
+  }
+
+  // Platform-specific KiCAD bundled Python detection
+  const isMac = process.platform === 'darwin';
+
+  if (isWindows && process.env.PYTHONPATH?.includes('KiCad')) {
     // Windows: Try KiCAD's bundled Python
     const kicadPython = 'C:\\Program Files\\KiCad\\9.0\\bin\\python.exe';
     if (existsSync(kicadPython)) {
+      logger.info(`Found KiCAD bundled Python at: ${kicadPython}`);
       return kicadPython;
     }
+  } else if (isMac) {
+    // macOS: Try KiCAD's bundled Python (check multiple versions)
+    const kicadPythonVersions = ['3.9', '3.10', '3.11', '3.12'];
+    for (const version of kicadPythonVersions) {
+      const kicadPython = `/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/${version}/bin/python3`;
+      if (existsSync(kicadPython)) {
+        logger.info(`Found KiCAD bundled Python at: ${kicadPython}`);
+        return kicadPython;
+      }
+    }
   }
 
   // Default to system Python