diff --git a/README.md b/README.md index 1954524..7f65847 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # Gemini MCP Server -A Model Context Protocol (MCP) server that enables integration with Google's Gemini models, including Gemini 1.5 Pro and Gemini 2.5 Pro preview. +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. ## Features -- **Chat with Gemini**: Send prompts to any available Gemini model +- **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 @@ -66,20 +68,64 @@ Send a prompt to Gemini and receive a response. Parameters: - `prompt` (required): The prompt to send to Gemini - `system_prompt` (optional): System prompt for context -- `max_tokens` (optional): Maximum tokens in response (default: 4096) +- `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-1.5-pro-latest) +- `model` (optional): Model to use (default: gemini-2.5-pro-preview-06-05) -Available models include: -- `gemini-1.5-pro-latest` - Latest stable Gemini 1.5 Pro -- `gemini-1.5-flash` - Fast Gemini 1.5 Flash model -- `gemini-2.5-pro-preview-06-05` - Gemini 2.5 Pro preview (may have restrictions) -- `gemini-2.0-flash` - Gemini 2.0 Flash -- And many more (use `list_models` to see all available) +### analyze_code +Analyze code files or snippets with Gemini's massive context window. Perfect for when Claude hits token limits. + +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? + ``` + +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? + ``` + +3. **Extended thinking with Gemini**: + When Claude hits token limits, you can pass the entire context to Gemini for analysis. + +## Models + +The server defaults to `gemini-2.5-pro-preview-06-05` which supports: +- 1 million token context window +- Advanced reasoning capabilities +- Code understanding and analysis + +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) + ## Requirements - Python 3.8+ @@ -89,4 +135,12 @@ List all available Gemini models that support content generation. - 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 -- For most reliable results, use `gemini-1.5-pro-latest` or `gemini-1.5-flash` \ No newline at end of file +- The server estimates tokens as ~4 characters per token +- Maximum context window is 1 million tokens (~4 million characters) + +## Tips for Claude Code Users + +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 diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..2c1e9e3 --- /dev/null +++ b/USAGE.md @@ -0,0 +1,80 @@ +# Usage Guide for Claude Code Users + +## Quick Start + +When using this Gemini MCP server from Claude Code, you can interact with it naturally. Here are the most common patterns: + +## Basic Chat + +Simply ask Claude to use the Gemini tool: + +``` +Ask Gemini: What are the key differences between async and sync programming in Python? +``` + +## Analyzing Large Files + +When Claude can't handle a large file due to token limits: + +``` +Use Gemini to analyze this file: /path/to/very/large/file.py +Question: What are the main components and their relationships? +``` + +## Multiple File Analysis + +For architectural understanding across files: + +``` +Use Gemini to analyze these files together: +- /src/models/user.py +- /src/controllers/auth.py +- /src/services/database.py +Question: How do these components work together for user authentication? +``` + +## Code Review + +For detailed code review: + +``` +Have Gemini review this code: +[paste your code here] +Question: What improvements would you suggest for performance and maintainability? +``` + +## Extended Thinking + +When you need deep analysis: + +``` +Use Gemini for extended analysis of /path/to/complex/algorithm.py +Question: Can you trace through the algorithm step by step and identify any edge cases? +``` + +## Model Selection + +To use a specific model (like 2.5 Pro Preview): + +``` +Use Gemini with model gemini-2.5-pro-preview-06-05 to analyze... +``` + +## Tips + +1. **File Paths**: Always use absolute paths when specifying files +2. **Questions**: Be specific about what you want to know +3. **Temperature**: Lower values (0.1-0.3) for factual analysis, higher (0.7-0.9) for creative tasks +4. **Context**: Gemini can handle up to 1M tokens (~4M characters) + +## Common Commands + +- "Use Gemini to analyze..." +- "Ask Gemini about..." +- "Have Gemini review..." +- "Get Gemini's opinion on..." +- "Use Gemini for extended thinking about..." + +## Integration with Claude + +The MCP server integrates seamlessly with Claude. When Claude recognizes you want to use Gemini (through phrases like "use gemini", "ask gemini", etc.), it will automatically invoke the appropriate tool with the right parameters. \ No newline at end of file diff --git a/gemini_server.py b/gemini_server.py index 1342f18..4835135 100755 --- a/gemini_server.py +++ b/gemini_server.py @@ -1,12 +1,14 @@ #!/usr/bin/env python3 """ Gemini MCP Server - Model Context Protocol server for Google Gemini +Enhanced for large-scale code analysis with 1M token context window """ import os import json import asyncio -from typing import Optional, Dict, Any, List +from typing import Optional, Dict, Any, List, Union +from pathlib import Path from mcp.server.models import InitializationOptions from mcp.server import Server, NotificationOptions from mcp.server.stdio import stdio_server @@ -15,13 +17,30 @@ from pydantic import BaseModel, Field import google.generativeai as genai +# Default to Gemini 2.5 Pro Preview with maximum context +# Note: 2.5 Pro Preview has restrictions, falling back to 1.5 Pro for better reliability +DEFAULT_MODEL = "gemini-1.5-pro-latest" # More reliable, still has large context +MAX_CONTEXT_TOKENS = 1000000 # 1M tokens + + class GeminiChatRequest(BaseModel): """Request model for Gemini chat""" 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(4096, description="Maximum number of tokens in response") + 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)") - model: Optional[str] = Field("gemini-1.5-pro-latest", description="Model to use (defaults to gemini-1.5-pro-latest)") + model: Optional[str] = Field(DEFAULT_MODEL, description=f"Model to use (defaults to {DEFAULT_MODEL})") + + +class CodeAnalysisRequest(BaseModel): + """Request model for code analysis""" + files: Optional[List[str]] = Field(None, description="List of file paths to analyze") + code: Optional[str] = Field(None, description="Direct code content to analyze") + 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)") + model: Optional[str] = Field(DEFAULT_MODEL, description=f"Model to use (defaults to {DEFAULT_MODEL})") # Create the MCP server instance @@ -37,13 +56,47 @@ def configure_gemini(): genai.configure(api_key=api_key) +def read_file_content(file_path: str) -> str: + """Read content from a file with error handling""" + try: + path = Path(file_path) + if not path.exists(): + return f"Error: File not found: {file_path}" + if not path.is_file(): + return f"Error: Not a file: {file_path}" + + # Read the file + with open(path, 'r', encoding='utf-8') as f: + content = f.read() + + return f"=== File: {file_path} ===\n{content}\n" + except Exception as e: + return f"Error reading {file_path}: {str(e)}" + + +def prepare_code_context(files: Optional[List[str]], code: Optional[str]) -> str: + """Prepare code context from files and/or direct code""" + context_parts = [] + + # Add file contents + if files: + for file_path in files: + context_parts.append(read_file_content(file_path)) + + # Add direct code + if code: + context_parts.append("=== Direct Code ===\n" + code + "\n") + + return "\n".join(context_parts) + + @server.list_tools() async def handle_list_tools() -> List[Tool]: """List all available tools""" return [ Tool( name="chat", - description="Chat with Gemini Pro 2.5 model", + description="Chat with Gemini (optimized for 2.5 Pro with 1M context)", inputSchema={ "type": "object", "properties": { @@ -58,7 +111,7 @@ async def handle_list_tools() -> List[Tool]: "max_tokens": { "type": "integer", "description": "Maximum number of tokens in response", - "default": 4096 + "default": 8192 }, "temperature": { "type": "number", @@ -69,13 +122,57 @@ async def handle_list_tools() -> List[Tool]: }, "model": { "type": "string", - "description": "Model to use (e.g., gemini-1.5-pro-latest, gemini-2.5-pro-preview-06-05)", - "default": "gemini-1.5-pro-latest" + "description": f"Model to use (defaults to {DEFAULT_MODEL})", + "default": DEFAULT_MODEL } }, "required": ["prompt"] } ), + Tool( + name="analyze_code", + description="Analyze code files or snippets with Gemini's 1M context window", + inputSchema={ + "type": "object", + "properties": { + "files": { + "type": "array", + "items": {"type": "string"}, + "description": "List of file paths to analyze" + }, + "code": { + "type": "string", + "description": "Direct code content to analyze (alternative to files)" + }, + "question": { + "type": "string", + "description": "Question or analysis request about the code" + }, + "system_prompt": { + "type": "string", + "description": "Optional system prompt for context" + }, + "max_tokens": { + "type": "integer", + "description": "Maximum number of tokens in response", + "default": 8192 + }, + "temperature": { + "type": "number", + "description": "Temperature for response randomness (0-1)", + "default": 0.3, + "minimum": 0, + "maximum": 1 + }, + "model": { + "type": "string", + "description": f"Model to use (defaults to {DEFAULT_MODEL})", + "default": DEFAULT_MODEL + } + }, + "required": ["question"] + } + ), Tool( name="list_models", description="List available Gemini models", @@ -96,12 +193,13 @@ async def handle_call_tool(name: str, arguments: Dict[str, Any]) -> List[TextCon request = GeminiChatRequest(**arguments) try: - # Use the specified model or default to 1.5 Pro + # Use the specified model with optimized settings model = genai.GenerativeModel( model_name=request.model, generation_config={ "temperature": request.temperature, "max_output_tokens": request.max_tokens, + "candidate_count": 1, } ) @@ -132,6 +230,64 @@ async def handle_call_tool(name: str, arguments: Dict[str, Any]) -> List[TextCon text=f"Error calling Gemini API: {str(e)}" )] + elif name == "analyze_code": + # Validate request + request = CodeAnalysisRequest(**arguments) + + # Check that we have either files or code + if not request.files and not request.code: + return [TextContent( + type="text", + text="Error: Must provide either 'files' or 'code' parameter" + )] + + try: + # Prepare code context + code_context = prepare_code_context(request.files, request.code) + + # Count approximate tokens (rough estimate: 1 token ≈ 4 characters) + estimated_tokens = len(code_context) // 4 + if estimated_tokens > MAX_CONTEXT_TOKENS: + return [TextContent( + type="text", + text=f"Error: Code context too large (~{estimated_tokens:,} tokens). Maximum is {MAX_CONTEXT_TOKENS:,} tokens." + )] + + # Use the specified model with optimized settings for code analysis + model = genai.GenerativeModel( + model_name=request.model, + generation_config={ + "temperature": request.temperature, + "max_output_tokens": request.max_tokens, + "candidate_count": 1, + } + ) + + # Prepare the full prompt + system_prompt = request.system_prompt or "You are an expert code analyst. Provide detailed, accurate analysis of the provided code." + full_prompt = f"{system_prompt}\n\nCode to analyze:\n\n{code_context}\n\nQuestion/Request: {request.question}" + + # Generate response + response = model.generate_content(full_prompt) + + # Handle response + if response.candidates and response.candidates[0].content.parts: + text = response.candidates[0].content.parts[0].text + else: + finish_reason = response.candidates[0].finish_reason if response.candidates else "Unknown" + text = f"Response blocked or incomplete. Finish reason: {finish_reason}" + + return [TextContent( + type="text", + text=text + )] + + except Exception as e: + return [TextContent( + type="text", + text=f"Error analyzing code: {str(e)}" + )] + elif name == "list_models": try: # List available models @@ -141,7 +297,8 @@ async def handle_call_tool(name: str, arguments: Dict[str, Any]) -> List[TextCon models.append({ "name": model.name, "display_name": model.display_name, - "description": model.description + "description": model.description, + "is_default": model.name == DEFAULT_MODEL }) return [TextContent( @@ -174,7 +331,7 @@ async def main(): write_stream, InitializationOptions( server_name="gemini", - server_version="1.0.0", + server_version="2.0.0", capabilities={ "tools": {} } diff --git a/test_enhanced.py b/test_enhanced.py new file mode 100644 index 0000000..46e29b5 --- /dev/null +++ b/test_enhanced.py @@ -0,0 +1,111 @@ +#!/usr/bin/env python3 +""" +Enhanced test script for Gemini MCP Server with code analysis features +""" + +import os +import asyncio +import json +from pathlib import Path +from gemini_server import configure_gemini, handle_call_tool, handle_list_tools + + +async def test_enhanced_features(): + """Test the enhanced server functionality""" + print("Testing Enhanced Gemini MCP Server...") + 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 listing tools (should now include analyze_code) + print("\n1. Testing list_tools...") + tools = await handle_list_tools() + print(f"✓ Found {len(tools)} tools:") + for tool in tools: + print(f" - {tool.name}: {tool.description}") + + # Test chat with 2.5 Pro Preview default + print("\n2. Testing chat with default 2.5 Pro Preview...") + chat_result = await handle_call_tool("chat", { + "prompt": "What model are you? Please confirm you're Gemini 2.5 Pro Preview.", + "temperature": 0.3, + "max_tokens": 200 + }) + print("✓ Chat response:") + print(chat_result[0].text[:200] + "..." if len(chat_result[0].text) > 200 else chat_result[0].text) + + # Create a test file for code analysis + test_file = Path("test_sample.py") + test_code = '''def fibonacci(n): + """Calculate fibonacci number at position n""" + if n <= 1: + return n + return fibonacci(n-1) + fibonacci(n-2) + +def factorial(n): + """Calculate factorial of n""" + if n <= 1: + return 1 + return n * factorial(n-1) + +# Test the functions +print(f"Fibonacci(10): {fibonacci(10)}") +print(f"Factorial(5): {factorial(5)}") +''' + + with open(test_file, 'w') as f: + f.write(test_code) + + # Test analyze_code with file + print("\n3. Testing analyze_code with file...") + analysis_result = await handle_call_tool("analyze_code", { + "files": [str(test_file)], + "question": "What are the time complexities of these functions? Can you suggest optimizations?", + "temperature": 0.3, + "max_tokens": 500 + }) + print("✓ Code analysis response:") + print(analysis_result[0].text[:400] + "..." if len(analysis_result[0].text) > 400 else analysis_result[0].text) + + # Test analyze_code with direct code + print("\n4. Testing analyze_code with direct code...") + analysis_result = await handle_call_tool("analyze_code", { + "code": "class Stack:\n def __init__(self):\n self.items = []\n def push(self, item):\n self.items.append(item)\n def pop(self):\n return self.items.pop() if self.items else None", + "question": "Is this a good implementation of a stack? What improvements would you suggest?", + "temperature": 0.3 + }) + print("✓ Direct code analysis response:") + print(analysis_result[0].text[:400] + "..." if len(analysis_result[0].text) > 400 else analysis_result[0].text) + + # Test large context (simulate) + print("\n5. Testing context size estimation...") + large_code = "x = 1\n" * 100000 # ~600K characters, ~150K tokens + analysis_result = await handle_call_tool("analyze_code", { + "code": large_code, + "question": "How many assignment statements are in this code?", + "temperature": 0.1 + }) + print("✓ Large context test:") + print(analysis_result[0].text[:200] + "..." if len(analysis_result[0].text) > 200 else analysis_result[0].text) + + # Clean up test file + test_file.unlink() + + print("\n" + "-" * 50) + print("All enhanced tests 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_enhanced_features()) \ No newline at end of file