From bb8a101dbf32381874baf9cb4df01b74197c769b Mon Sep 17 00:00:00 2001 From: Fahad Date: Tue, 10 Jun 2025 16:30:58 +0400 Subject: [PATCH] cleanup: remove Windows native support, enforce WSL requirement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove Windows batch scripts and native setup instructions since Claude Code CLI requires WSL on Windows. Consolidate Docker as primary recommendation across all platforms. Changes: - Remove setup.bat, run_gemini.bat, setup-docker-env.bat - Remove examples/claude_config_windows.json - Update README to clarify WSL requirement for Windows users - Promote Docker as recommended setup for all platforms - Update troubleshooting section for WSL-only support - Apply code formatting fixes from ruff/black 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 117 +++++++++----------------- examples/claude_config_windows.json | 13 --- run_gemini.bat | 34 -------- server.py | 2 +- setup-docker-env.bat | 124 ---------------------------- setup.bat | 91 -------------------- tools/base.py | 3 +- tools/codereview.py | 2 +- tools/precommit.py | 4 +- utils/file_utils.py | 8 +- 10 files changed, 47 insertions(+), 351 deletions(-) delete mode 100644 examples/claude_config_windows.json delete mode 100644 run_gemini.bat delete mode 100644 setup-docker-env.bat delete mode 100644 setup.bat diff --git a/README.md b/README.md index 3ffc1e6..8bff2ff 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ The ultimate development partner for Claude - a Model Context Protocol server th - [Docker Architecture](#docker-architecture) - How Docker integration works - **Resources** - - [Windows Setup](#windows-setup-guide) - Windows-specific instructions + - [Windows Setup](#windows-setup-guide) - WSL setup instructions for Windows - [Troubleshooting](#troubleshooting) - Common issues and solutions - [Contributing](#contributing) - How to contribute - [Testing](#testing) - Running tests @@ -72,15 +72,17 @@ The final implementation resulted in a 26% improvement in JSON parsing performan ### Prerequisites -Choose one of the following options: - -**Option A: Docker (Recommended - No Python Required!)** +**Recommended: Docker Setup (Works on all platforms)** - Docker Desktop installed ([Download here](https://www.docker.com/products/docker-desktop/)) - Git +- **Windows users**: WSL2 is required for Claude Code CLI +- **Benefits**: No Python setup, consistent environment, easy updates, works everywhere -**Option B: Traditional Setup** +**Alternative: Traditional Python Setup** - **Python 3.10 or higher** (required by the `mcp` package) - Git +- **Windows users**: Must use WSL2 with Python installed inside WSL +- **Note**: More setup complexity, potential environment issues ### 1. Get a Gemini API Key Visit [Google AI Studio](https://makersuite.google.com/app/apikey) and generate an API key. For best results with Gemini 2.5 Pro, use a paid API key as the free tier has limited access to the latest models. @@ -93,18 +95,15 @@ git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git cd gemini-mcp-server ``` -Now choose your setup method: +**We strongly recommend Docker for the most reliable experience across all platforms.** -#### Option A: Docker Setup (Recommended) +#### Docker Setup (Recommended for all platforms) ```bash # 1. Generate the .env file with your current directory as workspace # macOS/Linux: ./setup-docker-env.sh -# Windows (Command Prompt): -setup-docker-env.bat - # Windows (PowerShell): .\setup-docker-env.ps1 ``` @@ -131,20 +130,19 @@ setup-docker-env.bat **That's it!** The setup script handles everything - building the Docker image, setting up the environment, and configuring your API key. -#### Option B: Traditional Setup +#### Traditional Python Setup (Alternative) ```bash # Run the setup script to install dependencies # macOS/Linux: ./setup.sh -# Windows: -setup.bat +# Note: Claude Code requires WSL on Windows. See WSL setup instructions below. ``` **Note the full path** - you'll need it in the next step: - **macOS/Linux**: `/Users/YOUR_USERNAME/gemini-mcp-server` -- **Windows**: `C:\Users\YOUR_USERNAME\gemini-mcp-server` +- **Windows (WSL)**: `/home/YOUR_WSL_USERNAME/gemini-mcp-server` **Important**: The setup script will: - Create a Python virtual environment @@ -159,7 +157,7 @@ Add the server to your `claude_desktop_config.json`: **Find your config file:** - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` (configure for WSL usage) (configure for WSL usage) **Or use Claude Desktop UI (macOS):** - Open Claude Desktop @@ -167,11 +165,11 @@ Add the server to your `claude_desktop_config.json`: Choose your configuration based on your setup method: -#### Option A: Docker Configuration (Recommended) +#### Docker Configuration (Recommended for all platforms) **How it works:** Claude Desktop launches Docker, which runs the MCP server in a container. The communication happens through stdin/stdout, just like running a regular command. -**All Platforms (macOS/Linux/Windows):** +**All Platforms (macOS/Linux/Windows WSL):** ```json { "mcpServers": { @@ -224,30 +222,21 @@ Choose your configuration based on your setup method: } ``` -**Example for Windows:** +**Example for Windows (WSL with Docker):** ```json { "mcpServers": { "gemini": { - "command": "docker", - "args": [ - "run", - "--rm", - "-i", - "--env-file", "C:/path/to/gemini-mcp-server/.env", - "-e", "WORKSPACE_ROOT=C:/Users/YOUR_USERNAME", - "-e", "MCP_PROJECT_ROOT=/workspace", - "-v", "C:/Users/YOUR_USERNAME:/workspace:ro", - "gemini-mcp-server:latest" - ] + "command": "wsl.exe", + "args": ["-e", "docker", "run", "--rm", "-i", "--env-file", "/home/YOUR_WSL_USERNAME/gemini-mcp-server/.env", "-v", "/home/YOUR_WSL_USERNAME:/workspace:ro", "gemini-mcp-server:latest"] } } } ``` -> **Note**: Run `setup-docker-env.sh` (macOS/Linux) or `setup-docker-env.ps1` (Windows) to generate this configuration automatically with your paths. +> **Note**: Run `setup-docker-env.sh` (macOS/Linux/WSL) or `setup-docker-env.ps1` (Windows PowerShell) to generate this configuration automatically with your paths. -#### Option B: Traditional Configuration +#### Traditional Python Configuration (Alternative) **macOS/Linux:** ```json @@ -263,19 +252,6 @@ Choose your configuration based on your setup method: } ``` -**Windows (Native Python):** -```json -{ - "mcpServers": { - "gemini": { - "command": "C:\\Users\\YOUR_USERNAME\\gemini-mcp-server\\run_gemini.bat", - "env": { - "GEMINI_API_KEY": "your-gemini-api-key-here" - } - } - } -} -``` **Windows (Using WSL):** ```json @@ -309,9 +285,9 @@ claude mcp add-from-claude-desktop -s user claude mcp add gemini -s user -e GEMINI_API_KEY=your-gemini-api-key-here -- /path/to/gemini-mcp-server/run_gemini.sh ``` -**For Traditional Setup (Windows):** +**For Traditional Setup (Windows WSL):** ```bash -claude mcp add gemini -s user -e GEMINI_API_KEY=your-gemini-api-key-here -- C:\path\to\gemini-mcp-server\run_gemini.bat +claude mcp add gemini -s user -e GEMINI_API_KEY=your-gemini-api-key-here -- /home/YOUR_WSL_USERNAME/gemini-mcp-server/run_gemini.sh ``` **For Docker Setup:** @@ -349,12 +325,14 @@ Just ask Claude naturally: The Docker setup provides a consistent, hassle-free experience across all platforms without worrying about Python versions or dependencies. -### Why Docker? +### Why Docker is Recommended - **Zero Python Setup**: No need to install Python or manage virtual environments -- **Consistent Environment**: Same behavior across Windows, macOS, and Linux +- **Consistent Environment**: Same behavior across macOS, Linux, and Windows WSL - **Easy Updates**: Just run the setup script again to rebuild with latest changes - **Isolated Dependencies**: No conflicts with your system Python packages +- **Platform Reliability**: Eliminates Python version conflicts and dependency issues +- **Windows Compatibility**: Works seamlessly with Claude Code's WSL requirement ### Quick Setup Guide @@ -403,27 +381,11 @@ docker run --rm -i --env-file .env -v "$(pwd):/workspace:ro" gemini-mcp-server:l ## Windows Setup Guide -### Option 1: Native Windows (Recommended) +**Important**: Claude Code CLI does not support native Windows. You must use WSL (Windows Subsystem for Linux). -For the smoothest experience on Windows, we recommend running the server natively: +### WSL Setup (Required for Windows) -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): +To use Claude Code on Windows, you must use WSL: 1. **Prerequisites** - WSL2 installed with a Linux distribution (e.g., Ubuntu) @@ -1178,22 +1140,21 @@ The CI pipeline works without any secrets and will pass all tests using mocked r ### Windows/WSL Issues -**Error: `spawn P:\path\to\run_gemini.bat ENOENT`** +**Important**: Claude Code CLI only supports WSL on Windows, not native Windows. -This error occurs when Claude Desktop (running on Windows) can't properly execute the server. Common causes: +**Error: `spawn ENOENT` or execution issues** -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) +This error occurs when Claude Desktop can't properly execute the server. Since Claude Code requires WSL: -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) +1. **Ensure WSL is properly installed**: WSL2 with a Linux distribution (Ubuntu recommended) +2. **Use WSL configuration**: Always use `wsl.exe` in your Claude Desktop configuration +3. **Install dependencies in WSL**: Python and all packages must be installed inside WSL, not Windows +4. **Use WSL paths**: File paths should be WSL paths (`/home/username/...`) not Windows paths (`C:\...`) **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) +- Verify WSL is working: `wsl.exe --list --verbose` +- Check Python in WSL: `wsl.exe python3 --version` +- Test server in WSL: `wsl.exe /home/YOUR_WSL_USERNAME/gemini-mcp-server/run_gemini.sh` ### Common Issues diff --git a/examples/claude_config_windows.json b/examples/claude_config_windows.json deleted file mode 100644 index ec59210..0000000 --- a/examples/claude_config_windows.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "comment": "Traditional Windows configuration (non-Docker)", - "comment2": "Replace YOUR_USERNAME with your actual username", - "comment3": "Note the double backslashes in the path", - "mcpServers": { - "gemini": { - "command": "C:\\Users\\YOUR_USERNAME\\gemini-mcp-server\\run_gemini.bat", - "env": { - "GEMINI_API_KEY": "your-gemini-api-key-here" - } - } - } -} diff --git a/run_gemini.bat b/run_gemini.bat deleted file mode 100644 index 01e8da8..0000000 --- a/run_gemini.bat +++ /dev/null @@ -1,34 +0,0 @@ -@echo off -REM Windows batch script to run Gemini MCP server - -REM Get the directory where this script is located -set SCRIPT_DIR=%~dp0 - -REM Change to script directory to ensure proper working directory -cd /d "%SCRIPT_DIR%" - -REM Check if virtual environment exists -if not exist "%SCRIPT_DIR%venv\" ( - echo Virtual environment not found. Running setup... >&2 - - REM Check if setup.bat exists - if exist "%SCRIPT_DIR%setup.bat" ( - REM Run setup script - call "%SCRIPT_DIR%setup.bat" >&2 - - REM Check if setup was successful - if errorlevel 1 ( - echo Setup failed. Please run setup.bat manually to see the error. >&2 - exit /b 1 - ) - ) else ( - echo Error: setup.bat not found. Please ensure you have the complete repository. >&2 - exit /b 1 - ) -) - -REM Activate virtual environment -call "%SCRIPT_DIR%venv\Scripts\activate.bat" - -REM Run the server -python "%SCRIPT_DIR%server.py" \ No newline at end of file diff --git a/server.py b/server.py index b700165..0d4b0b8 100644 --- a/server.py +++ b/server.py @@ -81,7 +81,7 @@ def configure_gemini(): """ api_key = os.getenv("GEMINI_API_KEY") if not api_key: - raise ValueError("GEMINI_API_KEY environment variable is required. " "Please set it with your Gemini API key.") + raise ValueError("GEMINI_API_KEY environment variable is required. Please set it with your Gemini API key.") # Note: We don't store the API key globally for security reasons # Each tool creates its own Gemini client with the API key when needed logger.info("Gemini API key found") diff --git a/setup-docker-env.bat b/setup-docker-env.bat deleted file mode 100644 index 6972d54..0000000 --- a/setup-docker-env.bat +++ /dev/null @@ -1,124 +0,0 @@ -@echo off -REM Helper script to set up .env file for Docker usage on Windows - -echo Setting up .env file for Gemini MCP Server Docker... - -REM Get the current working directory (absolute path) -set CURRENT_DIR=%CD% - -REM Check if .env already exists -if exist .env ( - echo Warning: .env file already exists! Skipping creation. - echo. -) else ( - REM Check if GEMINI_API_KEY is already set in environment - if defined GEMINI_API_KEY ( - set API_KEY_VALUE=%GEMINI_API_KEY% - echo Found existing GEMINI_API_KEY in environment - ) else ( - set API_KEY_VALUE=your-gemini-api-key-here - ) - - REM Create the .env file - ( - echo # Gemini MCP Server Docker Environment Configuration - echo # Generated on %DATE% %TIME% - echo. - echo # Your Gemini API key ^(get one from https://makersuite.google.com/app/apikey^) - echo # IMPORTANT: Replace this with your actual API key - echo GEMINI_API_KEY=%API_KEY_VALUE% - ) > .env - echo. - echo Created .env file - echo. -) - -REM Check if Docker is installed and running -where docker >nul 2>nul -if %errorlevel% neq 0 ( - echo Warning: Docker is not installed. Please install Docker first. - echo Visit: https://docs.docker.com/get-docker/ -) else ( - REM Check if Docker daemon is running - docker info >nul 2>nul - if %errorlevel% neq 0 ( - echo Warning: Docker daemon is not running. Please start Docker. - ) else ( - REM Clean up and build Docker image - echo. - echo Building Docker image... - - REM Stop running containers - echo - Checking for running containers... - for /f "tokens=*" %%i in ('docker ps -q --filter ancestor^=gemini-mcp-server 2^>nul') do ( - docker stop %%i >nul 2>&1 - ) - - REM Remove containers - echo - Removing old containers... - for /f "tokens=*" %%i in ('docker ps -aq --filter ancestor^=gemini-mcp-server 2^>nul') do ( - docker rm %%i >nul 2>&1 - ) - - REM Remove existing image - echo - Removing old image... - docker rmi gemini-mcp-server:latest >nul 2>&1 - - REM Build fresh image - echo - Building fresh image with --no-cache... - docker build -t gemini-mcp-server:latest . --no-cache >nul 2>&1 - if %errorlevel% equ 0 ( - echo Docker image built successfully! - ) else ( - echo Failed to build Docker image. Run 'docker build -t gemini-mcp-server:latest .' manually to see errors. - ) - echo. - ) -) - -echo Next steps: -if "%API_KEY_VALUE%"=="your-gemini-api-key-here" ( - echo 1. Edit .env and replace 'your-gemini-api-key-here' with your actual Gemini API key - echo 2. Copy this configuration to your Claude Desktop config: -) else ( - echo 1. Copy this configuration to your Claude Desktop config: -) -echo. -echo ===== COPY BELOW THIS LINE ===== -echo { -echo "mcpServers": { -echo "gemini": { -echo "command": "%CURRENT_DIR%\gemini-mcp-docker.bat" -echo } -echo } -echo } -echo ===== COPY ABOVE THIS LINE ===== -echo. -echo Alternative: If you prefer the direct Docker command: -echo { -echo "mcpServers": { -echo "gemini": { -echo "command": "docker", -echo "args": [ -echo "run", -echo "--rm", -echo "-i", -echo "--env-file", "%CURRENT_DIR%\.env", -echo "-e", "WORKSPACE_ROOT=%USERPROFILE%", -echo "-v", "%USERPROFILE%:/workspace:ro", -echo "gemini-mcp-server:latest" -echo ] -echo } -echo } -echo } -echo. -echo Config file location: -echo Windows: %%APPDATA%%\Claude\claude_desktop_config.json -echo. -echo Note: This configuration mounts your user directory ^(%USERPROFILE%^). -echo Docker can access any file within your user directory. -echo. -echo If you want to restrict access to a specific directory: -echo Change both the mount ^(-v^) and WORKSPACE_ROOT to match: -echo Example: -v "%CURRENT_DIR%:/workspace:ro" and WORKSPACE_ROOT=%CURRENT_DIR% -echo The container will automatically use /workspace as the sandbox boundary. \ No newline at end of file diff --git a/setup.bat b/setup.bat deleted file mode 100644 index bebde2b..0000000 --- a/setup.bat +++ /dev/null @@ -1,91 +0,0 @@ -@echo off -REM Gemini MCP Server Setup Script for Windows -REM This script helps users set up the virtual environment and install dependencies - -echo Gemini MCP Server Setup -echo ======================= - -REM Get the directory where this script is located -set SCRIPT_DIR=%~dp0 -cd /d "%SCRIPT_DIR%" - -REM Check if Python is installed -python --version >nul 2>&1 -if errorlevel 1 ( - echo Error: Python is not installed or not in PATH. - echo Please install Python 3.10 or higher from https://python.org - echo Make sure to check "Add Python to PATH" during installation. - exit /b 1 -) - -REM Display Python version -echo Found Python: -python --version - -REM Check Python version is at least 3.10 -for /f "tokens=2 delims= " %%i in ('python --version 2^>^&1') do set PYTHON_VERSION=%%i -for /f "tokens=1,2 delims=." %%a in ("%PYTHON_VERSION%") do ( - set PYTHON_MAJOR=%%a - set PYTHON_MINOR=%%b -) - -if %PYTHON_MAJOR% LSS 3 ( - goto :pythonTooOld -) -if %PYTHON_MAJOR% EQU 3 if %PYTHON_MINOR% LSS 10 ( - goto :pythonTooOld -) -goto :pythonOk - -:pythonTooOld -echo Error: Python 3.10 or higher is required (you have Python %PYTHON_VERSION%) -echo. -echo The 'mcp' package requires Python 3.10 or newer. -echo Please download and install Python from https://python.org -echo Make sure to check "Add Python to PATH" during installation. -exit /b 1 - -:pythonOk - -REM Check if venv exists -if exist "venv\" ( - echo Virtual environment already exists -) else ( - echo Creating virtual environment... - python -m venv venv - if errorlevel 1 ( - echo Error: Failed to create virtual environment - exit /b 1 - ) - echo Virtual environment created -) - -REM Activate virtual environment -echo Activating virtual environment... -call venv\Scripts\activate.bat - -REM Upgrade pip -echo Upgrading pip... -python -m pip install --upgrade pip - -REM Install requirements -echo Installing dependencies... -pip install -r requirements.txt - -if errorlevel 1 ( - echo. - echo Error: Failed to install dependencies - echo Please check the error messages above and try again. - exit /b 1 -) else ( - echo. - echo Setup completed successfully! - echo. - echo Next steps: - echo 1. Get your Gemini API key from: https://makersuite.google.com/app/apikey - echo 2. Configure Claude Desktop with your API key (see README.md) - echo 3. Restart Claude Desktop - echo. - echo Note: The virtual environment has been activated for this session. - echo The run_gemini.bat script will automatically activate it when needed. -) \ No newline at end of file diff --git a/tools/base.py b/tools/base.py index 143d4d5..156b2a5 100644 --- a/tools/base.py +++ b/tools/base.py @@ -525,8 +525,7 @@ If any of these would strengthen your analysis, specify what Claude should searc within_limit, estimated_tokens = check_token_limit(text) if not within_limit: raise ValueError( - f"{context_type} too large (~{estimated_tokens:,} tokens). " - f"Maximum is {MAX_CONTEXT_TOKENS:,} tokens." + f"{context_type} too large (~{estimated_tokens:,} tokens). Maximum is {MAX_CONTEXT_TOKENS:,} tokens." ) def create_model(self, model_name: str, temperature: float, thinking_mode: str = "medium"): diff --git a/tools/codereview.py b/tools/codereview.py index 3e523cd..eb24b21 100644 --- a/tools/codereview.py +++ b/tools/codereview.py @@ -256,7 +256,7 @@ Please provide a code review aligned with the user's context and expectations, f if request.focus_on: header += f" - Focus: {request.focus_on}" return f"""{header} -{'=' * 50} +{"=" * 50} {response} diff --git a/tools/precommit.py b/tools/precommit.py index a6f2155..f808c51 100644 --- a/tools/precommit.py +++ b/tools/precommit.py @@ -294,7 +294,9 @@ class Precommit(BaseTool): # Use standardized file reading with token budget file_content = read_files( - translated_files, max_tokens=remaining_tokens, reserve_tokens=1000 # Small reserve for formatting + translated_files, + max_tokens=remaining_tokens, + reserve_tokens=1000, # Small reserve for formatting ) if file_content: diff --git a/utils/file_utils.py b/utils/file_utils.py index d8b2e39..277142b 100644 --- a/utils/file_utils.py +++ b/utils/file_utils.py @@ -267,9 +267,7 @@ def resolve_and_validate_path(path_str: str) -> Path: # Step 3: Security Policy - Require absolute paths # Relative paths could be interpreted differently depending on working directory if not user_path.is_absolute(): - raise ValueError( - f"Relative paths are not supported. Please provide an absolute path.\n" f"Received: {path_str}" - ) + raise ValueError(f"Relative paths are not supported. Please provide an absolute path.\nReceived: {path_str}") # Step 4: Resolve the absolute path (follows symlinks, removes .. and .) # This is critical for security as it reveals the true destination of symlinks @@ -286,9 +284,7 @@ def resolve_and_validate_path(path_str: str) -> Path: f"Requested: {path_str}, Resolved: {resolved_path}, Root: {PROJECT_ROOT}" ) raise PermissionError( - f"Path outside project root: {path_str}\n" - f"Project root: {PROJECT_ROOT}\n" - f"Resolved path: {resolved_path}" + f"Path outside project root: {path_str}\nProject root: {PROJECT_ROOT}\nResolved path: {resolved_path}" ) return resolved_path