From c220ad28eb40a0d552d20b7abaa6b521902ae834 Mon Sep 17 00:00:00 2001 From: Fahad Date: Mon, 9 Jun 2025 19:17:17 +0400 Subject: [PATCH] feat: add comprehensive Windows/WSL support and documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 107 +++++++++++++++++++++++++++- examples/claude_config_macos.json | 10 +++ examples/claude_config_windows.json | 10 +++ examples/claude_config_wsl.json | 11 +++ run_gemini.bat | 21 +++++- run_gemini.sh | 2 +- test_wsl_setup.bat | 81 +++++++++++++++++++++ 7 files changed, 235 insertions(+), 7 deletions(-) create mode 100644 examples/claude_config_macos.json create mode 100644 examples/claude_config_windows.json create mode 100644 examples/claude_config_wsl.json create mode 100644 test_wsl_setup.bat diff --git a/README.md b/README.md index c1acceb..4f8f275 100644 --- 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. diff --git a/examples/claude_config_macos.json b/examples/claude_config_macos.json new file mode 100644 index 0000000..bf9f8ca --- /dev/null +++ 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" + } + } + } +} \ No newline at end of file diff --git a/examples/claude_config_windows.json b/examples/claude_config_windows.json new file mode 100644 index 0000000..f4ed615 --- /dev/null +++ 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" + } + } + } +} \ No newline at end of file diff --git a/examples/claude_config_wsl.json b/examples/claude_config_wsl.json new file mode 100644 index 0000000..1f65c50 --- /dev/null +++ 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" + } + } + } +} \ No newline at end of file diff --git a/run_gemini.bat b/run_gemini.bat index b0e3ca5..3a7bbd3 100644 --- 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" \ No newline at end of file +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 + ) +) \ No newline at end of file diff --git a/run_gemini.sh b/run_gemini.sh index 63c14b6..d8ea5ab 100755 --- 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" \ No newline at end of file +exec "$PYTHON_EXEC" "$SCRIPT_DIR/server.py" \ No newline at end of file diff --git a/test_wsl_setup.bat b/test_wsl_setup.bat new file mode 100644 index 0000000..ecc8396 --- /dev/null +++ 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 } \ No newline at end of file