# MCP Protocol Implementation ## Overview The Gemini MCP Server implements the Model Context Protocol (MCP) specification, providing Claude with standardized access to Google's Gemini AI models through a secure, tool-based interface. ## Protocol Specification ### MCP Version - **Implemented Version**: MCP v1.0 - **Transport**: stdio (standard input/output) - **Serialization**: JSON-RPC 2.0 - **Authentication**: Environment-based API key management ### Core Protocol Flow ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } ``` **Response**: ```json { "jsonrpc": "2.0", "id": 1, "result": { "tools": [ { "name": "chat", "description": "Quick questions and general collaboration", "inputSchema": { "type": "object", "properties": { "prompt": {"type": "string"}, "continuation_id": {"type": "string", "optional": true} }, "required": ["prompt"] } } ] } } ``` ## Tool Registration System ### Tool Discovery (`server.py:67`) ```python @server.list_tools() async def list_tools() -> list[types.Tool]: """Dynamic tool discovery and registration""" tools = [] # Scan tools directory for available tools for tool_module in REGISTERED_TOOLS: tool_instance = tool_module() schema = tool_instance.get_schema() tools.append(schema) return tools ``` ### Tool Schema Definition Each tool must implement a standardized schema: ```python def get_schema(self) -> types.Tool: return types.Tool( name="analyze", description="Code exploration and understanding", inputSchema={ "type": "object", "properties": { "files": { "type": "array", "items": {"type": "string"}, "description": "Files or directories to analyze" }, "question": { "type": "string", "description": "What to analyze or look for" }, "analysis_type": { "type": "string", "enum": ["architecture", "performance", "security", "quality", "general"], "default": "general" }, "thinking_mode": { "type": "string", "enum": ["minimal", "low", "medium", "high", "max"], "default": "medium" }, "continuation_id": { "type": "string", "description": "Thread continuation ID for multi-turn conversations" } }, "required": ["files", "question"] } ) ``` ## Tool Execution Protocol ### Request Processing (`server.py:89`) ```python @server.call_tool() async def call_tool(name: str, arguments: dict) -> list[types.TextContent]: """Tool execution with comprehensive error handling""" try: # 1. Tool validation tool_class = TOOL_REGISTRY.get(name) if not tool_class: raise ToolNotFoundError(f"Tool '{name}' not found") # 2. Parameter validation tool_instance = tool_class() validated_args = tool_instance.validate_parameters(arguments) # 3. Security validation if 'files' in validated_args: validated_args['files'] = validate_file_paths(validated_args['files']) # 4. Tool execution result = await tool_instance.execute(validated_args) # 5. Response formatting return [types.TextContent( type="text", text=result.content )] except Exception as e: # Error response with context error_response = format_error_response(e, name, arguments) return [types.TextContent( type="text", text=error_response )] ``` ### Response Standardization All tools return standardized `ToolOutput` objects: ```python @dataclass class ToolOutput: content: str metadata: Dict[str, Any] continuation_id: Optional[str] = None files_processed: List[str] = field(default_factory=list) thinking_tokens_used: int = 0 status: str = "success" # success, partial, error def to_mcp_response(self) -> str: """Convert to MCP-compatible response format""" response_parts = [self.content] if self.metadata: response_parts.append("\n## Metadata") for key, value in self.metadata.items(): response_parts.append(f"- {key}: {value}") if self.files_processed: response_parts.append("\n## Files Processed") for file_path in self.files_processed: response_parts.append(f"- {file_path}") if self.continuation_id: response_parts.append(f"\n## Continuation ID: {self.continuation_id}") return '\n'.join(response_parts) ``` ## Individual Tool APIs ### 1. Chat Tool **Purpose**: Quick questions, brainstorming, general discussion **API Specification**: ```json { "name": "chat", "parameters": { "prompt": "string (required)", "continuation_id": "string (optional)", "temperature": "number (optional, 0.0-1.0, default: 0.5)", "thinking_mode": "string (optional, default: 'medium')" } } ``` **Example Request**: ```json { "method": "tools/call", "params": { "name": "chat", "arguments": { "prompt": "Explain the benefits of using MCP protocol", "thinking_mode": "low" } } } ``` **Response Format**: ```json { "result": [{ "type": "text", "text": "The Model Context Protocol (MCP) provides several key benefits:\n\n1. **Standardization**: Unified interface across different AI tools...\n\n## Metadata\n- thinking_mode: low\n- tokens_used: 156\n- response_time: 1.2s" }] } ``` ### 2. ThinkDeep Tool **Purpose**: Complex architecture, system design, strategic planning **API Specification**: ```json { "name": "thinkdeep", "parameters": { "current_analysis": "string (required)", "problem_context": "string (optional)", "focus_areas": "array of strings (optional)", "thinking_mode": "string (optional, default: 'high')", "files": "array of strings (optional)", "continuation_id": "string (optional)" } } ``` **Example Request**: ```json { "method": "tools/call", "params": { "name": "thinkdeep", "arguments": { "current_analysis": "We have an MCP server with 6 specialized tools", "problem_context": "Need to scale to handle 100+ concurrent Claude sessions", "focus_areas": ["performance", "architecture", "resource_management"], "thinking_mode": "max" } } } ``` ### 3. Analyze Tool **Purpose**: Code exploration, understanding existing systems **API Specification**: ```json { "name": "analyze", "parameters": { "files": "array of strings (required)", "question": "string (required)", "analysis_type": "enum: architecture|performance|security|quality|general", "thinking_mode": "string (optional, default: 'medium')", "continuation_id": "string (optional)" } } ``` **File Processing Behavior**: - **Directories**: Recursively scanned for relevant files - **Token Budget**: Allocated based on file priority (source code > docs > logs) - **Security**: All paths validated and sandboxed to PROJECT_ROOT - **Formatting**: Line numbers added for precise code references ### 4. CodeReview Tool **Purpose**: Code quality, security, bug detection **API Specification**: ```json { "name": "codereview", "parameters": { "files": "array of strings (required)", "context": "string (required)", "review_type": "enum: full|security|performance|quick (default: full)", "severity_filter": "enum: critical|high|medium|all (default: all)", "standards": "string (optional)", "thinking_mode": "string (optional, default: 'medium')" } } ``` **Response Includes**: - **Issue Categorization**: Critical → High → Medium → Low - **Specific Fixes**: Concrete code suggestions with line numbers - **Security Assessment**: Vulnerability detection and mitigation - **Performance Analysis**: Optimization opportunities ### 5. Debug Tool **Purpose**: Root cause analysis, error investigation **API Specification**: ```json { "name": "debug", "parameters": { "error_description": "string (required)", "error_context": "string (optional)", "files": "array of strings (optional)", "previous_attempts": "string (optional)", "runtime_info": "string (optional)", "thinking_mode": "string (optional, default: 'medium')" } } ``` **Diagnostic Capabilities**: - **Stack Trace Analysis**: Multi-language error parsing - **Root Cause Identification**: Systematic error investigation - **Reproduction Steps**: Detailed debugging procedures - **Fix Recommendations**: Prioritized solution approaches ### 6. Precommit Tool **Purpose**: Automated quality gates, validation before commits **API Specification**: ```json { "name": "precommit", "parameters": { "path": "string (required, git repository root)", "include_staged": "boolean (default: true)", "include_unstaged": "boolean (default: true)", "review_type": "enum: full|security|performance|quick (default: full)", "original_request": "string (optional, user's intent)", "thinking_mode": "string (optional, default: 'medium')" } } ``` **Validation Process**: 1. **Git Analysis**: Staged/unstaged changes detection 2. **Quality Review**: Comprehensive code analysis 3. **Security Scan**: Vulnerability and secret detection 4. **Documentation Check**: Ensures docs match code changes 5. **Test Validation**: Recommends testing strategies 6. **Commit Readiness**: Go/no-go recommendation ## Error Handling & Status Codes ### Standard Error Responses ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params", "data": { "validation_errors": [ { "field": "files", "error": "Path outside sandbox: /etc/passwd" } ] } } } ``` ### Error Categories **Security Errors** (Code: -32001): - Path traversal attempts - Unauthorized file access - Sandbox boundary violations **Validation Errors** (Code: -32602): - Missing required parameters - Invalid parameter types - Schema validation failures **Tool Errors** (Code: -32603): - Tool execution failures - Gemini API errors - Resource exhaustion **System Errors** (Code: -32000): - Redis connection failures - File system errors - Configuration issues ## Performance & Limits ### Request Limits - **Maximum File Size**: 10MB per file - **Maximum Files**: 50 files per request - **Token Budget**: 1M tokens total context - **Thinking Tokens**: 32K maximum per tool - **Request Timeout**: 300 seconds ### Rate Limiting ```python # Per-client rate limiting (future implementation) RATE_LIMITS = { 'chat': '10/minute', 'analyze': '5/minute', 'thinkdeep': '3/minute', 'codereview': '5/minute', 'debug': '5/minute', 'precommit': '3/minute' } ``` ### Optimization Features - **File Deduplication**: Avoid reprocessing same files across conversation - **Context Caching**: Redis-based conversation persistence - **Priority Processing**: Source code files processed first - **Concurrent Execution**: AsyncIO-based parallel processing ## Security Considerations ### Authentication - **API Key**: Gemini API key via environment variable - **No User Auth**: Runs in trusted Claude Desktop environment - **Local Only**: No network exposure beyond Gemini API ### Data Protection - **Sandbox Enforcement**: PROJECT_ROOT boundary enforcement - **Path Validation**: Multi-layer dangerous path detection - **Response Sanitization**: Automatic sensitive data removal - **Temporary Storage**: Redis with TTL-based cleanup ### Access Controls - **Read-Only Default**: Most operations are read-only - **Explicit Write Gates**: Write operations require explicit confirmation - **Docker Isolation**: Container-based runtime isolation --- This MCP protocol implementation provides a secure, performant, and extensible foundation for AI-assisted development workflows while maintaining compatibility with Claude's expectations and requirements.