claude-gemini-mcp-server: Instructions file for Claude Code

Claude Development Context

This file contains important context for Claude when working on this project.

Project Overview

This is a Model Context Protocol (MCP) server that enables Claude CLI to leverage Google's Gemini CLI for code review and analysis. It's a unique dual-AI collaboration tool where Claude handles implementation and Gemini provides specialized code analysis.

Architecture

Core Components

• MCP Server: Node.js server implementing the Model Context Protocol
• Gemini Integration: Spawns gemini CLI processes for AI analysis
• Security Layer: Input validation, path traversal protection, binary file detection
• Session Tracking: Maintains operation history and context

Available Tools

1. gemini_code_review - Comprehensive code review with severity ratings
2. gemini_analyze_code - Deep code analysis and explanation
3. gemini_suggest_improvements - Specific improvement recommendations
4. gemini_validate_architecture - Architecture and design pattern validation
5. gemini_propose_plan - Generate implementation plans for Claude execution
6. get_review_history - Session history and tracking

Critical Technical Decisions

MCP Protocol Compliance (v2.1.1)

• Issue: Original implementation returned tool_use objects in content arrays, violating MCP protocol
• Solution: Replaced with markdown-formatted text responses
• Impact: Manual copy/paste workflow instead of automated code replacement
• Files Modified: server.js (geminiCodeReview, geminiSuggestImprovements functions)

Response Format

// CORRECT (MCP compliant)
return {
    content: [{
        type: 'text',
        text: `**Rationale:**\n${explanation}\n\n**Suggested Code Change:**\n\nOld Code:\n\`\`\`${language}\n${oldCode}\n\`\`\`\n\nNew Code:\n\`\`\`${language}\n${newCode}\n\`\`\``
    }]
};

// INCORRECT (violates MCP protocol)
return {
    content: [
        { type: 'text', text: explanation },
        { type: 'tool_use', name: 'replace', arguments: {...} }  // ❌ Not allowed
    ]
};