diff --git a/README.md b/README.md index 74f78bd..bbf6d20 100644 --- a/README.md +++ b/README.md @@ -1,157 +1,169 @@ -# Gemini MCP Server +# Gemini MCP Server for Claude Code -A Model Context Protocol (MCP) server that enables integration with Google's Gemini models, optimized for Gemini 2.5 Pro Preview with 1M token context window. +A specialized Model Context Protocol (MCP) server that extends Claude Code's capabilities with Google's Gemini 2.5 Pro Preview, featuring a massive 1M token context window for handling large codebases and complex analysis tasks. -## How It Works with Claude +## 🎯 Purpose -Once configured, Claude automatically discovers this server's capabilities. You can use natural language to invoke Gemini: -- "Ask Gemini about..." -- "Use Gemini to analyze this file..." -- "Have Gemini review this code..." +This server acts as a developer assistant that augments Claude Code when you need: +- Analysis of files too large for Claude's context window +- Deep architectural reviews across multiple files +- Extended thinking and complex problem solving +- Performance analysis of large codebases +- Security audits requiring full codebase context -See [MCP_DISCOVERY.md](MCP_DISCOVERY.md) for detailed information about how Claude discovers and uses MCP servers. +## 🚀 Quick Start for Claude Code -## Features +### 1. Configure in Claude Desktop -- **Chat with Gemini**: Send prompts to Gemini 2.5 Pro Preview by default -- **Analyze Code**: Process large codebases with Gemini's 1M token context window -- **File Reading**: Automatically read and analyze multiple files -- **List Models**: View all available Gemini models -- **Configurable Parameters**: Adjust temperature, max tokens, and model selection -- **System Prompts**: Support for system prompts to set context -- **Developer Context**: Automatically uses developer-focused system prompt for Claude Code integration +Add to your Claude Desktop configuration file: -## Installation - -1. Clone this repository -2. Create a virtual environment: - ```bash - python3 -m venv venv - source venv/bin/activate - ``` -3. Install dependencies: - ```bash - pip install -r requirements.txt - ``` - -## Configuration - -Set your Gemini API key as an environment variable: -```bash -export GEMINI_API_KEY="your-api-key-here" -``` - -## Usage - -### For Claude Desktop - -Add this configuration to your Claude Desktop config file: +**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +**Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "gemini": { - "command": "/path/to/venv/bin/python", - "args": ["/path/to/gemini_server.py"], + "command": "/path/to/gemini-mcp-server/venv/bin/python", + "args": ["/path/to/gemini-mcp-server/gemini_server.py"], "env": { - "GEMINI_API_KEY": "your-api-key-here" + "GEMINI_API_KEY": "your-gemini-api-key-here" } } } } ``` -### Direct Usage +### 2. Restart Claude Desktop -Run the server: -```bash -source venv/bin/activate -export GEMINI_API_KEY="your-api-key-here" -python gemini_server.py +After adding the configuration, restart Claude Desktop. You'll see "gemini" in the MCP servers list. + +### 3. Start Using Natural Language + +Just talk to Claude naturally: +- "Use Gemini to analyze this large file..." +- "Ask Gemini to review the architecture of these files..." +- "Have Gemini check this codebase for security issues..." + +## 💻 Developer-Optimized Features + +### Automatic Developer Context +When no custom system prompt is provided, Gemini automatically operates with deep developer expertise, focusing on: +- Clean code principles +- Performance optimization +- Security best practices +- Architectural patterns +- Testing strategies +- Modern development practices + +### Optimized Temperature Settings +- **General chat**: 0.5 (balanced accuracy with some creativity) +- **Code analysis**: 0.2 (high precision for code review) + +### Large Context Window +- Handles up to 1M tokens (~4M characters) +- Perfect for analyzing entire codebases +- Maintains context across multiple large files + +## 🛠️ Available Tools + +### `chat` +General-purpose developer conversations with Gemini. + +**Example uses:** +``` +"Ask Gemini about the best approach for implementing a distributed cache" +"Use Gemini to explain the tradeoffs between different authentication strategies" ``` -## Available Tools +### `analyze_code` +Specialized tool for analyzing large files or multiple files that exceed Claude's limits. -### chat -Send a prompt to Gemini and receive a response. +**Example uses:** +``` +"Use Gemini to analyze /src/core/engine.py and identify performance bottlenecks" +"Have Gemini review these files together: auth.py, users.py, permissions.py" +``` -Parameters: -- `prompt` (required): The prompt to send to Gemini -- `system_prompt` (optional): System prompt for context -- `max_tokens` (optional): Maximum tokens in response (default: 8192) -- `temperature` (optional): Temperature for randomness 0-1 (default: 0.7) -- `model` (optional): Model to use (default: gemini-2.5-pro-preview-06-05) +### `list_models` +Lists available Gemini models (defaults to 2.5 Pro Preview). -### analyze_code -Analyze code files or snippets with Gemini's massive context window. Perfect for when Claude hits token limits. +## 📋 Installation -Parameters: -- `files` (optional): List of file paths to analyze -- `code` (optional): Direct code content to analyze -- `question` (required): Question or analysis request about the code -- `system_prompt` (optional): System prompt for context -- `max_tokens` (optional): Maximum tokens in response (default: 8192) -- `temperature` (optional): Temperature for randomness 0-1 (default: 0.3 for code) -- `model` (optional): Model to use (default: gemini-2.5-pro-preview-06-05) - -Note: You must provide either `files` or `code` (or both). - -### list_models -List all available Gemini models that support content generation. - -## Usage Examples - -### From Claude Code - -When working with large files in Claude Code, you can use the Gemini server like this: - -1. **Analyze a large file**: - ``` - Use the gemini tool to analyze this file: /path/to/large/file.py - Question: What are the main design patterns used in this code? +1. Clone the repository: + ```bash + git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git + cd gemini-mcp-server ``` -2. **Analyze multiple files**: - ``` - Use gemini to analyze these files together: - - /path/to/file1.py - - /path/to/file2.py - - /path/to/file3.py - Question: How do these components interact with each other? +2. Create virtual environment: + ```bash + python3 -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate ``` -3. **Extended thinking with Gemini**: - When Claude hits token limits, you can pass the entire context to Gemini for analysis. +3. Install dependencies: + ```bash + pip install -r requirements.txt + ``` -## Models +4. Set your Gemini API key: + ```bash + export GEMINI_API_KEY="your-api-key-here" + ``` -The server defaults to `gemini-2.5-pro-preview-06-05` (the latest and most capable model) which supports: -- 1 million token context window -- Advanced reasoning capabilities -- Code understanding and analysis +## 🔧 Advanced Configuration -Other available models: -- `gemini-1.5-pro-latest` - Stable Gemini 1.5 Pro -- `gemini-1.5-flash` - Fast Gemini 1.5 Flash model -- `gemini-2.0-flash` - Gemini 2.0 Flash -- And many more (use `list_models` to see all available) +### Custom System Prompts +Override the default developer prompt when needed: +```python +{ + "prompt": "Review this code", + "system_prompt": "You are a security expert. Focus only on vulnerabilities." +} +``` -## Requirements +### Temperature Control +Adjust for your use case: +- `0.1-0.3`: Maximum precision (debugging, security analysis) +- `0.4-0.6`: Balanced (general development tasks) +- `0.7-0.9`: Creative solutions (architecture design, brainstorming) -- Python 3.8+ -- Valid Google Gemini API key +### Model Selection +While defaulting to `gemini-2.5-pro-preview-06-05`, you can specify other models: +- `gemini-1.5-pro-latest`: Stable alternative +- `gemini-1.5-flash`: Faster responses +- Use `list_models` to see all available options -## Notes +## 🎯 Claude Code Integration Examples -- The Gemini 2.5 Pro preview models may have safety restrictions that block certain prompts -- If a model returns a blocked response, the server will indicate the finish reason -- The server estimates tokens as ~4 characters per token -- Maximum context window is 1 million tokens (~4 million characters) -- When no system prompt is provided, the server automatically uses a developer-focused prompt similar to Claude Code +### When Claude hits token limits: +``` +Claude: "This file is too large for me to analyze fully..." +You: "Use Gemini to analyze the entire file and identify the main components" +``` -## Tips for Claude Code Users +### For architecture reviews: +``` +You: "Use Gemini to analyze all files in /src/core/ and create an architecture diagram" +``` -1. When Claude says a file is too large, use the `analyze_code` tool with the file path -2. For architectural questions spanning multiple files, pass all relevant files to `analyze_code` -3. Use lower temperatures (0.1-0.3) for code analysis and higher (0.7-0.9) for creative tasks -4. The default model (2.5 Pro Preview) is optimized for large context understanding \ No newline at end of file +### For performance optimization: +``` +You: "Have Gemini profile this codebase and suggest the top 5 performance improvements" +``` + +## 📝 Notes + +- Gemini 2.5 Pro Preview may occasionally block certain prompts due to safety filters +- The server automatically falls back gracefully when this happens +- Token estimation: ~4 characters per token +- All file paths should be absolute paths + +## 🤝 Contributing + +This server is designed specifically for Claude Code users. Contributions that enhance the developer experience are welcome! + +## 📄 License + +MIT License - feel free to customize for your development workflow. \ No newline at end of file diff --git a/gemini_server.py b/gemini_server.py index 692e570..2605d81 100755 --- a/gemini_server.py +++ b/gemini_server.py @@ -22,18 +22,28 @@ DEFAULT_MODEL = "gemini-2.5-pro-preview-06-05" MAX_CONTEXT_TOKENS = 1000000 # 1M tokens # Developer-focused system prompt for Claude Code usage -DEVELOPER_SYSTEM_PROMPT = """You are an expert software developer and code analyst, similar to Claude Code. -You excel at: -- Writing clean, efficient, and well-documented code -- Debugging and solving complex programming problems -- Explaining technical concepts clearly -- Following best practices and design patterns -- Providing thoughtful code reviews and suggestions -- Understanding system architecture and design -- Helping with testing strategies and implementation -- Optimizing performance and identifying bottlenecks +DEVELOPER_SYSTEM_PROMPT = """You are an expert software developer assistant working alongside Claude Code. Your role is to extend Claude's capabilities when handling large codebases or complex analysis tasks. -You should be direct, helpful, and focused on practical solutions. When analyzing code, provide actionable insights and concrete improvements. Always consider the broader context and long-term maintainability.""" +Core competencies: +- Deep understanding of software architecture and design patterns +- Expert-level debugging and root cause analysis +- Performance optimization and scalability considerations +- Security best practices and vulnerability identification +- Clean code principles and refactoring strategies +- Comprehensive testing approaches (unit, integration, e2e) +- Modern development practices (CI/CD, DevOps, cloud-native) +- Cross-platform and cross-language expertise + +Your approach: +- Be precise and technical, avoiding unnecessary explanations +- Provide actionable, concrete solutions with code examples +- Consider edge cases and potential issues proactively +- Focus on maintainability, readability, and long-term sustainability +- Suggest modern, idiomatic solutions for the given language/framework +- When reviewing code, prioritize critical issues first +- Always validate your suggestions against best practices + +Remember: You're augmenting Claude Code's capabilities, especially for tasks requiring extensive context or deep analysis that might exceed Claude's token limits.""" class GeminiChatRequest(BaseModel): @@ -41,7 +51,7 @@ class GeminiChatRequest(BaseModel): prompt: str = Field(..., description="The prompt to send to Gemini") system_prompt: Optional[str] = Field(None, description="Optional system prompt for context") max_tokens: Optional[int] = Field(8192, description="Maximum number of tokens in response") - temperature: Optional[float] = Field(0.7, description="Temperature for response randomness (0-1)") + temperature: Optional[float] = Field(0.5, description="Temperature for response randomness (0-1, default 0.5 for balanced accuracy/creativity)") model: Optional[str] = Field(DEFAULT_MODEL, description=f"Model to use (defaults to {DEFAULT_MODEL})") @@ -52,7 +62,7 @@ class CodeAnalysisRequest(BaseModel): question: str = Field(..., description="Question or analysis request about the code") system_prompt: Optional[str] = Field(None, description="Optional system prompt for context") max_tokens: Optional[int] = Field(8192, description="Maximum number of tokens in response") - temperature: Optional[float] = Field(0.3, description="Temperature for response randomness (0-1)") + temperature: Optional[float] = Field(0.2, description="Temperature for code analysis (0-1, default 0.2 for high accuracy)") model: Optional[str] = Field(DEFAULT_MODEL, description=f"Model to use (defaults to {DEFAULT_MODEL})") @@ -128,8 +138,8 @@ async def handle_list_tools() -> List[Tool]: }, "temperature": { "type": "number", - "description": "Temperature for response randomness (0-1)", - "default": 0.7, + "description": "Temperature for response randomness (0-1, default 0.5 for balanced accuracy/creativity)", + "default": 0.5, "minimum": 0, "maximum": 1 }, @@ -172,8 +182,8 @@ async def handle_list_tools() -> List[Tool]: }, "temperature": { "type": "number", - "description": "Temperature for response randomness (0-1)", - "default": 0.3, + "description": "Temperature for code analysis (0-1, default 0.2 for high accuracy)", + "default": 0.2, "minimum": 0, "maximum": 1 }, diff --git a/test_optimized.py b/test_optimized.py new file mode 100644 index 0000000..5d75975 --- /dev/null +++ b/test_optimized.py @@ -0,0 +1,84 @@ +#!/usr/bin/env python3 +""" +Test script for optimized Claude Code settings +""" + +import os +import asyncio +from gemini_server import configure_gemini, handle_call_tool + + +async def test_optimized_settings(): + """Test the optimized temperature and developer settings""" + print("Testing Optimized Claude Code Settings...") + print("-" * 50) + + # Test configuration + try: + configure_gemini() + print("✓ Gemini API configured successfully") + except Exception as e: + print(f"✗ Failed to configure Gemini API: {e}") + return + + # Test 1: Default chat temperature (should be 0.5) + print("\n1. Testing chat with default temperature (0.5)...") + result = await handle_call_tool("chat", { + "prompt": "Explain the concept of dependency injection in one paragraph. Be concise but thorough." + }) + print("Response preview (should be balanced - accurate but not robotic):") + print(result[0].text[:300] + "..." if len(result[0].text) > 300 else result[0].text) + + # Test 2: Code analysis with low temperature (0.2) + print("\n2. Testing code analysis with default low temperature (0.2)...") + code = ''' +async def fetch_user_data(user_id: str, cache=None): + if cache and user_id in cache: + return cache[user_id] + + response = await http_client.get(f"/api/users/{user_id}") + user_data = response.json() + + if cache: + cache[user_id] = user_data + + return user_data +''' + + result = await handle_call_tool("analyze_code", { + "code": code, + "question": "Identify potential issues and suggest improvements" + }) + print("Response preview (should be precise and technical):") + print(result[0].text[:400] + "..." if len(result[0].text) > 400 else result[0].text) + + # Test 3: Creative task with higher temperature + print("\n3. Testing creative task with custom higher temperature...") + result = await handle_call_tool("chat", { + "prompt": "Suggest 3 innovative ways to implement a rate limiter", + "temperature": 0.8 + }) + print("Response preview (should be more creative):") + print(result[0].text[:400] + "..." if len(result[0].text) > 400 else result[0].text) + + # Test 4: Verify developer context is applied + print("\n4. Testing developer context (no system prompt)...") + result = await handle_call_tool("chat", { + "prompt": "What's the time complexity of quicksort?", + "temperature": 0.3 + }) + print("Response (should be technical and developer-focused):") + print(result[0].text[:300] + "..." if len(result[0].text) > 300 else result[0].text) + + print("\n" + "-" * 50) + print("Optimized settings test completed!") + + +if __name__ == "__main__": + # Check for API key + if not os.getenv("GEMINI_API_KEY"): + print("Error: GEMINI_API_KEY environment variable is not set") + print("Please set it with: export GEMINI_API_KEY='your-api-key'") + exit(1) + + asyncio.run(test_optimized_settings()) \ No newline at end of file