feat: add comprehensive Windows/WSL support and documentation

Major improvements for Windows users: - Add detailed Windows Setup Guide with native and WSL options - Create platform-specific example configurations (Windows/WSL/macOS) - Add troubleshooting section addressing common Windows/WSL errors - Create test_wsl_setup.bat diagnostic script for Windows users Script improvements: - Enhance run_gemini.bat with error handling and helpful messages - Update both run scripts to use server.py as main entry point - Keep gemini_server.py as backward compatibility wrapper Documentation: - Add clear instructions for both native Windows and WSL setups - Explain the wsl.exe bridge approach for WSL users - Include performance recommendations for WSL file access - Add specific troubleshooting for spawn ENOENT errors All tests passing, code properly formatted and linted. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-06-09 19:17:17 +04:00
parent 783ba73181
commit c220ad28eb
7 changed files with 235 additions and 7 deletions
--- a/README.md
+++ b/README.md
@@ -73,7 +73,7 @@ Add the server to your `claude_desktop_config.json`:
 }
 ```

-**Windows:**
+**Windows (Native Python):**
 ```json
 {
  "mcpServers": {
@@ -87,10 +87,29 @@ Add the server to your `claude_desktop_config.json`:
 }
 ```

+**Windows (Using WSL):**
+If your development environment is in WSL, use `wsl.exe` as a bridge:
+```json
+{
+  "mcpServers": {
+    "gemini": {
+      "command": "wsl.exe",
+      "args": ["/home/YOUR_WSL_USERNAME/gemini-mcp-server/run_gemini.sh"],
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-api-key-here"
+      }
+    }
+  }
+}
+```
+
 **Important**: 
- Replace `YOUR_USERNAME` with your actual username
+- Replace `YOUR_USERNAME` with your actual Windows username
+- Replace `YOUR_WSL_USERNAME` with your WSL username
 - Use the full absolute path where you cloned the repository
- Windows users: Note the double backslashes `\\` in the path
+- Windows native: Note the double backslashes `\\` in the path
+- WSL: Use Linux-style paths starting with `/`
+- See `examples/` folder for complete configuration examples

 ### 4. Restart Claude Desktop
 Completely quit and restart Claude Desktop for the changes to take effect.
@@ -124,6 +143,52 @@ Just ask Claude naturally:
 - **Want to understand code?** → `analyze` (architecture, patterns, dependencies)
 - **Server info?** → `get_version` (version and configuration details)

+## Windows Setup Guide
+
+### Option 1: Native Windows (Recommended)
+
+For the smoothest experience on Windows, we recommend running the server natively:
+
+1. **Install Python on Windows**
+   - Download from [python.org](https://python.org) or install via Microsoft Store
+   - Ensure Python 3.10 or higher
+
+2. **Set up the project**
+   ```powershell
+   cd C:\Users\YOUR_USERNAME\gemini-mcp-server
+   python -m venv venv
+   .\venv\Scripts\activate
+   pip install -r requirements.txt
+   ```
+
+3. **Configure Claude Desktop** using the Windows native configuration shown above
+
+### Option 2: Using WSL (Advanced)
+
+If you prefer to use WSL (Windows Subsystem for Linux):
+
+1. **Prerequisites**
+   - WSL2 installed with a Linux distribution (e.g., Ubuntu)
+   - Python installed in your WSL environment
+   - Project cloned inside WSL (recommended: `~/gemini-mcp-server`)
+
+2. **Set up in WSL**
+   ```bash
+   # Inside WSL terminal
+   cd ~/gemini-mcp-server
+   python3 -m venv venv
+   source venv/bin/activate
+   pip install -r requirements.txt
+   chmod +x run_gemini.sh
+   ```
+
+3. **Configure Claude Desktop** using the WSL configuration shown above
+
+**Important WSL Notes:**
+- For best performance, clone the repository inside WSL (`~/`) rather than on Windows (`/mnt/c/`)
+- Ensure `run_gemini.sh` has Unix line endings (LF, not CRLF)
+- If you have multiple WSL distributions, specify which one: `wsl.exe -d Ubuntu-22.04`
+
 **Tools Overview:**
 1. [`chat`](#1-chat---general-development-chat--collaborative-thinking) - Collaborative thinking and development conversations
 2. [`think_deeper`](#2-think_deeper---extended-reasoning-partner) - Extended reasoning and problem-solving
@@ -644,6 +709,42 @@ The project includes GitHub Actions workflows that:

 The CI pipeline works without any secrets and will pass all tests using mocked responses. Live integration tests only run if a `GEMINI_API_KEY` secret is configured in the repository.

+## Troubleshooting
+
+### Windows/WSL Issues
+
+**Error: `spawn P:\path\to\run_gemini.bat ENOENT`**
+
+This error occurs when Claude Desktop (running on Windows) can't properly execute the server. Common causes:
+
+1. **Wrong execution environment**: You're trying to run WSL-based code from Windows
+   - **Solution**: Use the WSL bridge configuration with `wsl.exe` (see Windows Setup Guide above)
+
+2. **Path format mismatch**: Using Linux paths (`/mnt/c/...`) in Windows context
+   - **Solution**: Use Windows paths for native execution, Linux paths only after `wsl.exe`
+
+3. **Missing dependencies**: Python or required packages not installed in the execution environment
+   - **Solution**: Ensure Python and dependencies are installed where you're trying to run (Windows or WSL)
+
+**Testing your setup:**
+- Windows users: Run `test_wsl_setup.bat` to verify your WSL configuration
+- Check Python availability: `python --version` (Windows) or `wsl python3 --version` (WSL)
+
+### Common Issues
+
+**"GEMINI_API_KEY environment variable is required"**
+- Ensure you've added your API key to the Claude Desktop configuration
+- The key should be in the `env` section of your MCP server config
+
+**"Connection failed" in Claude Desktop**
+- Verify the command path is correct and uses proper escaping (`\\` for Windows paths)
+- Ensure the script has execute permissions (Linux/macOS: `chmod +x run_gemini.sh`)
+- Check Claude Desktop logs for detailed error messages
+
+**Performance issues with WSL**
+- Files on Windows drives (`/mnt/c/`) are slower to access from WSL
+- For best performance, clone the repository inside WSL (`~/gemini-mcp-server`)
+
 ## License

 MIT License - see LICENSE file for details.
--- a/examples/claude_config_macos.json
+++ b/examples/claude_config_macos.json
@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "gemini": {
+      "command": "/Users/YOUR_USERNAME/gemini-mcp-server/run_gemini.sh",
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-api-key-here"
+      }
+    }
+  }
+}
--- a/examples/claude_config_windows.json
+++ b/examples/claude_config_windows.json
@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "gemini": {
+      "command": "C:\\Users\\YOUR_USERNAME\\gemini-mcp-server\\run_gemini.bat",
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-api-key-here"
+      }
+    }
+  }
+}
--- a/examples/claude_config_wsl.json
+++ b/examples/claude_config_wsl.json
@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "gemini": {
+      "command": "wsl.exe",
+      "args": ["/home/YOUR_WSL_USERNAME/gemini-mcp-server/run_gemini.sh"],
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-api-key-here"
+      }
+    }
+  }
+}
--- a/run_gemini.bat
+++ b/run_gemini.bat
@@ -4,6 +4,21 @@ REM Windows batch script to run Gemini MCP server
 REM Get the directory where this script is located
 set SCRIPT_DIR=%~dp0

-REM Activate the virtual environment and run the server
-call "%SCRIPT_DIR%venv\Scripts\activate.bat"
-python "%SCRIPT_DIR%gemini_server.py"
+REM Check if virtual environment exists
+if exist "%SCRIPT_DIR%venv\Scripts\activate.bat" (
+    REM Activate the virtual environment
+    call "%SCRIPT_DIR%venv\Scripts\activate.bat"
+    python "%SCRIPT_DIR%server.py"
+) else (
+    REM Try to use python directly if no venv
+    echo Warning: Virtual environment not found at %SCRIPT_DIR%venv >&2
+    echo Attempting to run with system Python... >&2
+    python "%SCRIPT_DIR%server.py"
+    if errorlevel 1 (
+        echo Error: Failed to run server. Please ensure Python is installed and dependencies are available. >&2
+        echo Run: python -m venv venv >&2
+        echo Then: venv\Scripts\activate >&2
+        echo Then: pip install -r requirements.txt >&2
+        exit /b 1
+    )
+)
--- a/run_gemini.sh
+++ b/run_gemini.sh
@@ -16,4 +16,4 @@ else
 fi

 # Run the server
-exec "$PYTHON_EXEC" "$SCRIPT_DIR/gemini_server.py"
+exec "$PYTHON_EXEC" "$SCRIPT_DIR/server.py"
--- a/test_wsl_setup.bat
+++ b/test_wsl_setup.bat
@@ -0,0 +1,81 @@
+@echo off
+REM Test script for Windows users to verify WSL setup
+
+echo Testing WSL setup for Gemini MCP Server...
+echo.
+
+REM Check if WSL is available
+wsl --status >nul 2>&1
+if errorlevel 1 (
+    echo ERROR: WSL is not installed or not available.
+    echo Please install WSL2 from: https://docs.microsoft.com/en-us/windows/wsl/install
+    exit /b 1
+)
+
+echo [OK] WSL is installed
+echo.
+
+REM Get default WSL distribution
+for /f "tokens=1" %%i in ('wsl -l -q') do (
+    set WSL_DISTRO=%%i
+    goto :found_distro
+)
+
+:found_distro
+echo Default WSL distribution: %WSL_DISTRO%
+echo.
+
+REM Test Python in WSL
+echo Testing Python in WSL...
+wsl python3 --version
+if errorlevel 1 (
+    echo ERROR: Python3 not found in WSL
+    echo Please install Python in your WSL distribution:
+    echo   wsl sudo apt update
+    echo   wsl sudo apt install python3 python3-pip python3-venv
+    exit /b 1
+)
+
+echo [OK] Python is available in WSL
+echo.
+
+REM Provide example configurations
+echo Example Claude Desktop configurations:
+echo.
+echo For WSL (if your code is in Windows filesystem):
+echo {
+echo   "mcpServers": {
+echo     "gemini": {
+echo       "command": "wsl.exe",
+echo       "args": ["/mnt/c/path/to/gemini-mcp-server/run_gemini.sh"],
+echo       "env": {
+echo         "GEMINI_API_KEY": "your-key-here"
+echo       }
+echo     }
+echo   }
+echo }
+echo.
+echo For WSL (if your code is in WSL home directory - recommended):
+echo {
+echo   "mcpServers": {
+echo     "gemini": {
+echo       "command": "wsl.exe",
+echo       "args": ["~/gemini-mcp-server/run_gemini.sh"],
+echo       "env": {
+echo         "GEMINI_API_KEY": "your-key-here"
+echo       }
+echo     }
+echo   }
+echo }
+echo.
+echo For Native Windows:
+echo {
+echo   "mcpServers": {
+echo     "gemini": {
+echo       "command": "C:\\path\\to\\gemini-mcp-server\\run_gemini.bat",
+echo       "env": {
+echo         "GEMINI_API_KEY": "your-key-here"
+echo       }
+echo     }
+echo   }
+echo }