torbjorn/my-pal-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

cleanup: remove Windows native support, enforce WSL requirement

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Fahad
2025-06-10 16:30:58 +04:00
parent 1be339ecc0
commit bb8a101dbf
10 changed files with 47 additions and 351 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
README.md
View File

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

13
examples/claude_config_windows.json
View File

@@ -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"
}
}
}
}

34
run_gemini.bat
View File

@@ -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"

2
server.py
View File

@@ -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")

124
setup-docker-env.bat
View File

@@ -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.

91
setup.bat
View File

@@ -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.
)

3
tools/base.py
View File

@@ -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"):

2
tools/codereview.py
View File

@@ -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}

4
tools/precommit.py
View File

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

8
utils/file_utils.py
View File

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