gemini-bridge 1.0.0__py3-none-any.whl

gemini_bridge-1.0.0.dist-info/METADATA

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: gemini-bridge
+Version: 1.0.0
+Summary: Lightweight MCP server bridging Claude Code to Google's Gemini AI via official CLI
+Author-email: Shelakh <info@shelakh.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shelakh/gemini-bridge
+Project-URL: Repository, https://github.com/shelakh/gemini-bridge
+Project-URL: Issues, https://github.com/shelakh/gemini-bridge/issues
+Keywords: mcp,gemini,ai,coding,assistant
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Dynamic: license-file
+
+# Gemini Bridge
+
+![PyPI Version](https://img.shields.io/pypi/v/gemini-bridge)
+![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
+![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)
+![CI Status](https://github.com/shelakh/gemini-bridge/actions/workflows/ci.yml/badge.svg)
+
+A lightweight MCP (Model Context Protocol) server that enables Claude Code to interact with Google's Gemini AI through the official CLI. Designed for simplicity, reliability, and seamless integration.
+
+## ✨ Features
+
+- **Direct Gemini CLI Integration**: Zero API costs using official Gemini CLI
+- **Simple MCP Tools**: Two core functions for basic queries and file analysis
+- **Stateless Operation**: No sessions, caching, or complex state management
+- **Production Ready**: Robust error handling with configurable 60-second timeouts
+- **Minimal Dependencies**: Only requires `mcp>=1.0.0` and Gemini CLI
+- **Easy Deployment**: Support for both uvx and traditional pip installation
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+1. **Install Gemini CLI**:
+   ```bash
+   npm install -g @google/gemini-cli
+   ```
+
+2. **Authenticate with Gemini**:
+   ```bash
+   gemini auth login
+   ```
+
+3. **Verify installation**:
+   ```bash
+   gemini --version
+   ```
+
+### Installation
+
+**🎯 Recommended: PyPI Installation**
+```bash
+# Install from PyPI
+pip install gemini-bridge
+
+# Add to Claude Code with uvx (recommended)
+claude mcp add gemini-bridge -s user -- uvx gemini-bridge
+```
+
+**Alternative: From Source**
+```bash
+# Clone the repository
+git clone https://github.com/shelakh/gemini-bridge.git
+cd gemini-bridge
+
+# Build and install locally
+uvx --from build pyproject-build
+pip install dist/*.whl
+
+# Add to Claude Code
+claude mcp add gemini-bridge -s user -- uvx gemini-bridge
+```
+
+**Development Installation**
+```bash
+# Clone and install in development mode
+git clone https://github.com/shelakh/gemini-bridge.git
+cd gemini-bridge
+pip install -e .
+
+# Add to Claude Code (development)
+claude mcp add gemini-bridge-dev -s user -- python -m src
+```
+
+## 🛠️ Available Tools
+
+### `consult_gemini`
+Direct CLI bridge for simple queries.
+
+**Parameters:**
+- `query` (string): The question or prompt to send to Gemini
+- `directory` (string): Working directory for the query (default: current directory)
+- `model` (string, optional): Model to use - "flash" or "pro" (default: "flash")
+
+**Example:**
+```python
+consult_gemini(
+    query="Find authentication patterns in this codebase",
+    directory="/path/to/project",
+    model="flash"
+)
+```
+
+### `consult_gemini_with_files`
+CLI bridge with file attachments for detailed analysis.
+
+**Parameters:**
+- `query` (string): The question or prompt to send to Gemini
+- `directory` (string): Working directory for the query
+- `files` (list): List of file paths relative to the directory
+- `model` (string, optional): Model to use - "flash" or "pro" (default: "flash")
+
+**Example:**
+```python
+consult_gemini_with_files(
+    query="Analyze these auth files and suggest improvements",
+    directory="/path/to/project",
+    files=["src/auth.py", "src/models.py"],
+    model="pro"
+)
+```
+
+## 📋 Usage Examples
+
+### Basic Code Analysis
+```python
+# Simple research query
+consult_gemini(
+    query="What authentication patterns are used in this project?",
+    directory="/Users/dev/my-project"
+)
+```
+
+### Detailed File Review
+```python
+# Analyze specific files
+consult_gemini_with_files(
+    query="Review these files and suggest security improvements",
+    directory="/Users/dev/my-project",
+    files=["src/auth.py", "src/middleware.py"],
+    model="pro"
+)
+```
+
+### Multi-file Analysis
+```python
+# Compare multiple implementation files
+consult_gemini_with_files(
+    query="Compare these database implementations and recommend the best approach",
+    directory="/Users/dev/my-project",
+    files=["src/db/postgres.py", "src/db/sqlite.py", "src/db/redis.py"]
+)
+```
+
+## 🏗️ Architecture
+
+### Core Design
+- **CLI-First**: Direct subprocess calls to `gemini` command
+- **Stateless**: Each tool call is independent with no session state
+- **Fixed Timeout**: 60-second maximum execution time
+- **Simple Error Handling**: Clear error messages with fail-fast approach
+
+### Project Structure
+```
+gemini-bridge/
+├── src/
+│   ├── __init__.py              # Entry point
+│   ├── __main__.py              # Module execution entry point
+│   └── mcp_server.py            # Main MCP server implementation
+├── .github/                     # GitHub templates and workflows
+├── start_server_uvx.sh         # Production startup script
+├── start_server_dev.sh         # Development startup script
+├── pyproject.toml              # Python package configuration
+├── README.md                   # This file
+├── CONTRIBUTING.md             # Contribution guidelines
+├── CODE_OF_CONDUCT.md          # Community standards
+├── SECURITY.md                 # Security policies
+├── CHANGELOG.md               # Version history
+└── LICENSE                    # MIT license
+```
+
+## 🔧 Development
+
+### Local Testing
+```bash
+# Install in development mode
+pip install -e .
+
+# Run directly
+python -m src
+
+# Test CLI availability
+gemini --version
+```
+
+### Integration with Claude Code
+The server automatically integrates with Claude Code when properly configured through the MCP protocol.
+
+## 🔍 Troubleshooting
+
+### CLI Not Available
+```bash
+# Install Gemini CLI
+npm install -g @google/gemini-cli
+
+# Authenticate
+gemini auth login
+
+# Test
+gemini --version
+```
+
+### Connection Issues
+- Verify Gemini CLI is properly authenticated
+- Check network connectivity
+- Ensure Claude Code MCP configuration is correct
+- Check that the `gemini` command is in your PATH
+
+### Common Error Messages
+- **"CLI not available"**: Gemini CLI is not installed or not in PATH
+- **"Authentication required"**: Run `gemini auth login`
+- **"Timeout after 60 seconds"**: Query took too long, try breaking it into smaller parts
+
+## 🤝 Contributing
+
+We welcome contributions from the community! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started.
+
+### Quick Contributing Guide
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🔄 Version History
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
+
+## 🆘 Support
+
+- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/shelakh/gemini-bridge/issues)
+- **Discussions**: Join the community discussion
+- **Documentation**: Additional docs available in the `docs/` directory
+
+---
+
+**Focus**: A simple, reliable bridge between Claude Code and Gemini AI through the official CLI.

gemini_bridge-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+gemini_bridge-1.0.0.dist-info/licenses/LICENSE,sha256=yTz_R8ocWu64Eubxr6vdZCKRS0dB_Pi3RbjUNn4qPxQ,1063
+src/__init__.py,sha256=FYM7cJkOKgimwO1wUNk3wgQPKz6_Kn8kuYQR6IR_e9k,190
+src/__main__.py,sha256=12FoIYCXYYKu2_BYX1GS_h9E9qO41Q26B8zedRIDPBs,149
+src/mcp_server.py,sha256=SGdrmNMvpCvJseSvvMlBGvDS71RkwWS7yM4JnSPg_Yg,6871
+gemini_bridge-1.0.0.dist-info/METADATA,sha256=B7tBEvl0NmOdeXZ9k1jtQYJPModC0DRNXO0JQj6x8sY,7962
+gemini_bridge-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+gemini_bridge-1.0.0.dist-info/entry_points.txt,sha256=ygWf0B23Gygq8mW_GzPx8rxIA19RR_RH4RG2I15lU3E,43
+gemini_bridge-1.0.0.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+gemini_bridge-1.0.0.dist-info/RECORD,,

gemini_bridge-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gemini_bridge-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gemini-bridge = src:main

gemini_bridge-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shelakh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gemini_bridge-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/__init__.py

@@ -0,0 +1,9 @@
+"""
+MCP Gemini Assistant - Simple CLI bridge to Gemini AI.
+Version 1.0.0 - Production ready, radically simplified.
+"""
+
+from .mcp_server import main
+
+__version__ = "1.0.0"
+__all__ = ["main"]

src/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Entry point for running the MCP server as a module."""
+
+from .mcp_server import main
+
+if __name__ == "__main__":
+    main()

src/mcp_server.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+Gemini MCP Server - Simple CLI Bridge
+Version 1.0.0
+A minimal MCP server to interface with Gemini AI via the gemini CLI.
+Created by @shelakh/elyin
+"""
+
+import os
+import shutil
+import subprocess
+from typing import List, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("gemini-assistant")
+
+
+def _normalize_model_name(model: Optional[str]) -> str:
+    """
+    Normalize user-provided model identifiers to canonical Gemini CLI model names.
+    Defaults to gemini-2.5-flash when not provided or unrecognized.
+
+    Accepted forms:
+    - "flash", "2.5-flash", "gemini-2.5-flash"
+    - "pro", "2.5-pro", "gemini-2.5-pro"
+    """
+    if not model:
+        return "gemini-2.5-flash"
+    value = model.strip().lower()
+    # Common short aliases
+    if value in {"flash", "2.5-flash", "gemini-2.5-flash"}:
+        return "gemini-2.5-flash"
+    if value in {"pro", "2.5-pro", "gemini-2.5-pro"}:
+        return "gemini-2.5-pro"
+    # If the caller passed a full model name, keep it
+    if value.startswith("gemini-"):
+        return value
+    # Fallback to flash for anything else
+    return "gemini-2.5-flash"
+
+
+def execute_gemini_simple(query: str, directory: str = ".", model: Optional[str] = None) -> str:
+    """
+    Execute gemini CLI command for simple queries without file attachments.
+    
+    Args:
+        query: The prompt to send to Gemini
+        directory: Working directory for the command
+        model: Optional model name (flash, pro, etc.)
+        
+    Returns:
+        CLI output or error message
+    """
+    # Check if gemini CLI is available
+    if not shutil.which("gemini"):
+        return "Error: Gemini CLI not found. Install with: npm install -g @google/gemini-cli"
+    
+    # Validate directory
+    if not os.path.isdir(directory):
+        return f"Error: Directory does not exist: {directory}"
+    
+    # Build command - use stdin for input to avoid hanging
+    selected_model = _normalize_model_name(model)
+    cmd = ["gemini", "-m", selected_model]
+    
+    # Execute CLI command - simple timeout, no retries
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=directory,
+            capture_output=True,
+            text=True,
+            timeout=60,
+            input=query
+        )
+        
+        if result.returncode == 0:
+            return result.stdout.strip() if result.stdout.strip() else "No output from Gemini CLI"
+        else:
+            return f"Gemini CLI Error: {result.stderr.strip()}"
+            
+    except subprocess.TimeoutExpired:
+        return "Error: Gemini CLI command timed out after 60 seconds"
+    except Exception as e:
+        return f"Error executing Gemini CLI: {str(e)}"
+
+
+def execute_gemini_with_files(query: str, directory: str = ".", files: Optional[List[str]] = None, model: Optional[str] = None) -> str:
+    """
+    Execute gemini CLI command with file attachments.
+    
+    Args:
+        query: The prompt to send to Gemini
+        directory: Working directory for the command
+        files: List of file paths to attach (relative to directory)
+        model: Optional model name (flash, pro, etc.)
+        
+    Returns:
+        CLI output or error message
+    """
+    # Check if gemini CLI is available
+    if not shutil.which("gemini"):
+        return "Error: Gemini CLI not found. Install with: npm install -g @google/gemini-cli"
+    
+    # Validate directory
+    if not os.path.isdir(directory):
+        return f"Error: Directory does not exist: {directory}"
+    
+    # Validate files parameter
+    if not files:
+        return "Error: No files provided for file attachment mode"
+    
+    # Build command - use stdin for input to avoid hanging
+    selected_model = _normalize_model_name(model)
+    cmd = ["gemini", "-m", selected_model]
+    
+    # Read and concatenate file contents
+    file_contents = []
+    for file_path in files:
+        try:
+            # Convert relative paths to absolute based on directory
+            if not os.path.isabs(file_path):
+                file_path = os.path.join(directory, file_path)
+            
+            if os.path.isfile(file_path):
+                with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                    content = f.read()
+                    file_contents.append(f"=== {os.path.basename(file_path)} ===\n{content}")
+            else:
+                file_contents.append(f"=== {os.path.basename(file_path)} ===\n[File not found]")
+        except Exception as e:
+            file_contents.append(f"=== {os.path.basename(file_path)} ===\n[Error reading file: {str(e)}]")
+    
+    # Combine file contents with query
+    stdin_content = "\n\n".join(file_contents) + "\n\n" + query
+    
+    # Execute CLI command - simple timeout, no retries
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=directory,
+            capture_output=True,
+            text=True,
+            timeout=60,
+            input=stdin_content
+        )
+        
+        if result.returncode == 0:
+            return result.stdout.strip() if result.stdout.strip() else "No output from Gemini CLI"
+        else:
+            return f"Gemini CLI Error: {result.stderr.strip()}"
+            
+    except subprocess.TimeoutExpired:
+        return "Error: Gemini CLI command timed out after 60 seconds"
+    except Exception as e:
+        return f"Error executing Gemini CLI: {str(e)}"
+
+
+@mcp.tool()
+def consult_gemini(
+    query: str,
+    directory: str,
+    model: Optional[str] = None
+) -> str:
+    """
+    Send a query directly to Gemini CLI.
+    
+    This is the core function - a direct bridge between Claude and Gemini.
+    No caching, no sessions, no complexity. Just execute and return.
+    
+    Args:
+        query: The question or prompt to send to Gemini
+        directory: Working directory (required)
+        model: Optional model name (flash, pro, etc.)
+        
+    Returns:
+        Gemini's response
+    """
+    return execute_gemini_simple(query, directory, model)
+
+
+@mcp.tool()
+def consult_gemini_with_files(
+    query: str,
+    directory: str,
+    files: Optional[List[str]] = None,
+    model: Optional[str] = None
+) -> str:
+    """
+    Send a query to Gemini CLI with file attachments.
+    
+    Files are read and concatenated into the prompt. Simple and direct.
+    
+    Args:
+        query: The question or prompt to send to Gemini
+        directory: Working directory (required)
+        files: List of file paths to attach (relative to directory)
+        model: Optional model name (flash, pro, etc.)
+        
+    Returns:
+        Gemini's response with file context
+    """
+    if not files:
+        return "Error: files parameter is required for consult_gemini_with_files"
+    return execute_gemini_with_files(query, directory, files, model)
+
+
+def main():
+    """Entry point for the MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()