8000 feat: Add web search tool, new Gemini models (flash-lite, 3.1-pro), and modern Python syntax by FojleRabbiRabib · Pull Request #5 · eLyiN/gemini-bridge · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,23 @@ Run commands from the project root to ensure relative paths resolve correctly.
Follow PEP 8 with 4-space indentation and an 88-character target line length. Use descriptive, lowercase `snake_case` for functions and variables, `UPPER_SNAKE_CASE` for constants, and reserve `CamelCase` for classes. Keep functions small, add docstrings describing intent, and include type hints on public interfaces. Prefer expressive log messages over inline comments; only annotate logic that is non-obvious.

## Testing Guidelines
No automated suite ships today, so validate changes by exercising both tools: `python -m src` for the stdio server and `uvx gemini-bridge -- --help` or a sample prompt to confirm CLI wiring. When introducing automated tests, place them under `tests/`, target `pytest`, and mirror module names (e.g., `tests/test_mcp_server.py`). Cover environment-sensitive paths such as `_normalize_model_name` and `_get_timeout`, and document manual test steps in your PR.
Validate changes by exercising all three MCP tools: `consult_gemini`, `consult_gemini_with_files`, and `web_search`. Run `python -m src` for the stdio server and `uvx gemini-bridge -- --help` or a sample prompt to confirm CLI wiring. Automated tests are located under `tests/`, targeting `pytest`, and mirror module names (e.g., `tests/test_mcp_server.py`). Cover environment-sensitive paths such as `_normalize_model_name`, `_get_timeout`, and the new `web_search` function. Document manual test steps in your PR.

## Commit & Pull Request Guidelines
Commit messages follow Conventional Commit prefixes (`feat:`, `fix:`, `chore:`, `docs:`) and should explain the motivation. Keep commits atomic and focused on one concern. Pull requests must include a concise summary, linked issues, and a brief testing log (commands run, expected vs. actual behavior). Request a review once CI (when available) passes and respond to feedback with follow-up commits rather than force-pushes.

## Security & Configuration Tips
Authenticate the Gemini CLI (`gemini auth login`) before running tools and avoid hard-coding credentials. Use the `GEMINI_BRIDGE_TIMEOUT` environment variable for tuning, but never commit `.env` files or shell history containing secrets. Validate file paths carefully when adding features that read from disk to preserve the server’s minimal, secure surface area.

## Model Support
The server supports multiple Gemini models through aliases:
- `flash`, `2.5-flash` → `gemini-2.5-flash` (default)
- `pro`, `2.5-pro` → `gemini-2.5-pro`
- `flash-lite`, `2.5-flash-lite`, `2.5-lite` → `gemini-2.5-flash-lite`
- `3-pro` → `gemini-3-pro-preview`
- `3-flash` → `gemini-3-flash-preview`
- `3.1-pro` → `gemini-3.1-pro-preview`
- `3.1-flash-lite` → `gemini-3.1-flash-lite-preview`
- `auto` → lets CLI choose optimal model

Custom models prefixed with `gemini-` are passed through directly.
29 changes: 28 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.3.0] - 2026-03-03

### Added
- **Web search tool**: New `web_search` MCP tool that leverages Gemini CLI's built-in web search capabilities for querying current information
- **Gemini 2.5 Flash Lite**: New alias `flash-lite` for the cost-effective `gemini-2.5-flash-lite` model
- **Gemini 3.1 Pro Preview**: New alias `3.1-pro` for the latest `gemini-3.1-pro-preview` model
- **Gemini 3.1 Flash Lite**: New alias `3.1-flash-lite` for the latest `gemini-3.1-flash-lite-preview` model
- **Extended model aliases**: Full list now includes flash, pro, flash-lite, 2.5-lite, 3-pro, 3-flash, 3.1-pro, 3.1-flash-lite, and auto router

### Changed
- **Modern Python syntax**: Migrated to Python 3.10+ type hints (`str | None`, `list[str]`) throughout codebase
- **Path handling**: Replaced `os.path` with `pathlib.Path` for better cross-platform compatibility
- **Documentation updates**: README.md and CLAUDE.md updated with new tools and model options

### Fixed
- **Model alias fixes**: Fixed `2.5-lite` to correctly map to `gemini-2.5-flash-lite`
- **Error messaging**: Improved error messages with helpful suggestions for model availability, authentication, timeout, and missing CLI
- **Documentation accuracy**: Fixed Python version requirement (3.10+ instead of 3.9+ throughout docs)
- **Web search honesty**: Updated web_search description to reflect best-effort automatic nature

### Technical Details
- Removed old typing imports (`Optional`, `List`, `Tuple`)
- Added `from pathlib import Path` for all path operations
- Updated `_normalize_model_name()` function with new model aliases (3.1-flash-lite, 2.5-lite)
- Enhanced error handling with actionable user guidance
- All 34 tests pass including 7 new tests for models, web_search, and error handling

## [1.2.0] - 2025-12-28

### Added
Expand Down Expand Up @@ -75,7 +102,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
#### Dependencies
- **Required**: `mcp>=1.0.0`
- **External**: Gemini CLI (npm package `@google/gemini-cli`)
- **Python**: Compatible with Python 3.9+
- **Python**: Compatible with Python 3.10+

#### File Structure
```
Expand Down
25 changes: 21 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,14 @@ python -c "import src; print('Package works!')"

**Model Support:**
- Default: `gemini-2.5-flash` (optimal performance/cost)
- Available: `flash`, `pro` (auto-normalized to full names)
- Available aliases:
- `flash`, `2.5-flash` → `gemini-2.5-flash`
- `pro`, `2.5-pro` → `gemini-2.5-pro`
- `flash-lite`, `2.5-flash-lite` → `gemini-2.5-flash-lite`
- `3-pro` → `gemini-3-pro-preview`
- `3-flash` → `gemini-3-flash-preview`
- `3.1-pro` → `gemini-3.1-pro-preview`
- `auto` → lets CLI choose optimal model
- Custom models accepted if prefixed with `gemini-`

### File Structure
Expand Down Expand Up @@ -131,11 +138,11 @@ gemini-bridge/
- **Use Case**: General questions, code analysis without file attachments
- **Example**: General programming questions, code explanations

### `consult_gemini_with_files`
### `consult_gemini_with_files`
- **Purpose**: CLI bridge with file attachments for detailed analysis
- **Parameters**:
- **Parameters**:
- `query` (required): The question or prompt to send to Gemini
- `directory` (required): Working directory for the query
- `directory` (required): Working directory for the query
- `files` (required list): List of file paths to attach
- `model` (optional): Model name (flash, pro, or custom)
- `timeout_seconds` (optional): Override execution timeout for this call
Expand All @@ -144,6 +151,16 @@ gemini-bridge/
- **File Handling**: Inline mode streams truncated snippets with warnings; `at_command` mode passes `@` directives for Gemini CLI to resolve
- **Example**: Code reviews, debugging specific files, analyzing project structure

### `web_search`
- **Purpose**: Ask Gemini queries with web search context. Uses Gemini CLI's automatic web search when the model determines it's needed. Best-effort functionality - not guaranteed for every query.
- **Parameters**:
- `query` (required): Search query or question to look up on the web
- `directory` (required): Working directory for command execution
- `model` (optional): Model name (flash, pro, or custom)
- `timeout_seconds` (optional): Override execution timeout for this call
- **Use Case**: Getting current information, latest news, recent documentation
- **Example**: "latest Python version", "current React best practices"

## Error Handling & Troubleshooting

### Common Error Patterns
Expand Down
21 changes: 10 additions & 11 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,26 +73,24 @@ Before contributing, make sure you have:

### Example code style:
```python
from typing import Optional, List
import subprocess
import json

def consult_gemini(
query: str,
directory: str = ".",
model: Optional[str] = None
query: str,
directory: str = ".",
model: str | None = None
) -> str:
"""
Send a query to Gemini CLI.

Args:
query: The question or prompt to send
directory: Working directory for the query
model: Optional model name (flash, pro)
model: Optional model name (flash, pro, flash-lite, 3-pro, etc.)

Returns:
Gemini's response as a string

Raises:
RuntimeError: If CLI is not available or query fails
"""
Expand Down Expand Up @@ -209,6 +207,7 @@ Before submitting, verify:
- [ ] MCP server starts without errors
- [ ] `consult_gemini` tool works with basic queries
- [ ] `consult_gemini_with_files` tool works with file attachments
- [ ] `web_search` tool works for web queries
- [ ] Error handling works properly (try invalid queries)
- [ ] Both `start_server_dev.sh` and `start_server_uvx.sh` work
- [ ] Documentation is updated and accurate
Expand All @@ -217,8 +216,8 @@ Before submitting, verify:

If possible, test with:
- Claude Code integration
- Different Python versions (3.9, 3.10, 3.11, 3.12)
- Various Gemini models (flash, pro)
- Different Python versions (3.10, 3.11, 3.12)
- Various Gemini models (flash, pro, flash-lite, 3-pro, 3-flash, 3.1-pro, auto)

## 🆘 Getting Help

Expand Down
35 changes: 31 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,13 @@ A lightweight MCP (Model Context Protocol) server that enables AI coding assista
## ✨ Features

- **Direct Gemini CLI Integration**: Zero API costs using official Gemini CLI
- **Simple MCP Tools**: Two core functions for basic queries and file analysis
- **Three MCP Tools**: Basic queries, file analysis, and web search capabilities
- **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
- **Universal MCP Compatibility**: Works with any MCP-compatible AI coding assistant
- **Modern Python**: Uses pathlib and modern type hints (Python 3.10+)

## 🚀 Quick Start

Expand Down Expand Up @@ -389,8 +390,8 @@ 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")
- `directory` (string): Working directory for the query
- `model` (string, optional): Model to use - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", or "auto" (default: "flash")
- `timeout_seconds` (int, optional): Override the execution timeout for this request

**Example:**
Expand All @@ -409,7 +410,7 @@ CLI bridge with file attachments for detailed analysis.
- `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")
- `model` (string, optional): Model to use - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", or "auto" (default: "flash")
- `timeout_seconds` (int, optional): Override the execution timeout for this request
- `mode` (string, optional): Either `"inline"` (default) to stream file contents or `"at_command"` to let Gemini CLI resolve `@path` references itself

Expand All @@ -426,6 +427,23 @@ consult_gemini_with_files(

**Tip:** When scanning large trees, switch to `mode="at_command"` so the Gemini CLI handles file globbing and truncation natively.

### `web_search`
Ask Gemini queries with web search context. Uses Gemini CLI's automatic web search when the model determines it's needed. Best-effort functionality - not guaranteed for every query.

**Parameters:**
- `query` (string): Search query or question to look up on the web
- `directory` (string): Working directory for command execution
- `model` (string, optional): Model to use - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", or "auto" (default: "flash")
- `timeout_seconds` (int, optional): Override the execution timeout for this request

**Example:**
```python
web_search(
query="latest Python version and new features",
model="flash"
)
```

## 📋 Usage Examples

### Basic Code Analysis
Expand Down Expand Up @@ -459,6 +477,15 @@ consult_gemini_with_files(
)
```

### Web Search
```python
# Get current information from the web
web_search(
query="latest Python version and new features in 3.13",
model="flash"
)
```

### Large File Safeguards
- Inline transfers cap at ~256 KB per file and ~512 KB per request to avoid hangs.
- Oversized files are truncated to head/tail snippets with a warning in the MCP response.
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ We follow responsible disclosure practices:

### System Dependencies

- **Python**: Use supported Python versions (3.9+)
- **Python**: Use supported Python versions (3.10+)
- **Operating System**: Keep OS updated for subprocess security
- **Network**: Secure network configuration recommended

Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "gemini-bridge"
version = "1.2.0"
version = "1.3.0"
description = "Lightweight MCP server bridging Claude Code to Google's Gemini AI via official CLI"
readme = "README.md"
license = "MIT"
Expand Down
2 changes: 1 addition & 1 deletion src/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@

from .mcp_server import main

__version__ = "1.2.0"
__version__ = "1.3.0"
__all__ = ["main"]
Loading
Loading
0