Prerequisites

• Node.js 18 or later
• A Google Cloud account with Gemini API access
• Gemini API key from Google AI Studio

Key Dependencies

• @google/generative-ai: Google's official SDK for Gemini API integration
• @modelcontextprotocol/sdk: MCP protocol implementation for Claude integration
• zod: Runtime type validation for tool parameters
• dotenv: Environment variable management

Installation

Quick Install for Cursor

Note: After installation, you'll need to update the file path to your actual installation directory and set your GEMINI_API_KEY.

Manual Installation

1. Clone the repository:

git clone https://github.com/Haasonsaas/deep-code-reasoning-mcp.git
cd deep-code-reasoning-mcp

2. Install dependencies:

npm install

3. Set up your Gemini API key:

cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

4. Build the project:

npm run build

Configuration

Environment Variables

• GEMINI_API_KEY (required): Your Google Gemini API key

Claude Desktop Configuration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "deep-code-reasoning": {
      "command": "node",
      "args": ["/path/to/deep-code-reasoning-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

How It Works

1. Claude Code performs initial analysis using its strengths in multi-file refactoring and test-driven loops
2. When beneficial, Claude escalates to this MCP server - particularly for:
   • Analyzing gigantic log/trace dumps that exceed Claude's context
   • Running iterative hypothesis testing with code execution
   • Correlating failures across many microservices
3. Server prepares comprehensive context including code, logs, and traces
4. Gemini analyzes with its 1M-token context and visible "thinking" traces
5. Results returned to Claude Code for implementation of fixes

Available Tools

Note: The tool parameters use snake_case naming convention and are validated using Zod schemas. The actual implementation provides more detailed type safety than shown in these simplified examples. Full TypeScript type definitions are available in src/models/types.ts.

Conversational Analysis Tools

The server now includes AI-to-AI conversational tools that enable Claude and Gemini to engage in multi-turn dialogues for complex analysis:

start_conversation

Initiates a conversational analysis session between Claude and Gemini.

{
  claude_context: {
    attempted_approaches: string[];      // What Claude tried
    partial_findings: any[];            // What Claude found
    stuck_description: string;          // Where Claude got stuck
    code_scope: {
      files: string[];                  // Files to analyze
      entry_points?: CodeLocation[];    // Starting points
      service_names?: string[];         // Services involved
    }
  };
  analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test';
  initial_question?: string;            // Optional opening question
}

continue_conversation

Continues an active conversation with Claude's response or follow-up question.

{
  session_id: string;                   // Active session ID
  message: string;                      // Claude's message to Gemini
  include_code_snippets?: boolean;      // Enrich with code context
}

finalize_conversation

Completes the conversation and generates structured analysis results.

{
  session_id: string;                   // Active session ID
  summary_format: 'detailed' | 'concise' | 'actionable';
}

get_conversation_status

Checks the status and progress of an ongoing conversation.

{
  session_id: string;                   // Session ID to check
}

Traditional Analysis Tools

escalate_analysis

Main tool for handing off complex analysis from Claude Code to Gemini.

{
  claude_context: {
    attempted_approaches: string[];      // What Claude tried
    partial_findings: any[];            // What Claude found
    stuck_description: string;          // Where Claude got stuck
    code_scope: {
      files: string[];                  // Files to analyze
      entry_points?: CodeLocation[];    // Starting points (file, line, function_name)
      service_names?: string[];         // Services involved
    }
  };
  analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test';
  depth_level: 1-5;                     // Analysis depth
  time_budget_seconds?: number;         // Time limit (default: 60)
}

trace_execution_path

Deep execution analysis with Gemini's semantic understanding.

{
  entry_point: {
    file: string;
    line: number;
    function_name?: string;
  };
  max_depth?: number;              // Default: 10
  include_data_flow?: boolean;     // Default: true
}

cross_system_impact

Analyze impacts across service boundaries.

{
  change_scope: {
    files: string[];
    service_names?: string[];
  };
  impact_types?: ('breaking' | 'performance' | 'behavioral')[];
}

performance_bottleneck

Deep performance analysis beyond simple profiling.

{
  code_path: {
    entry_point: {
      file: string;
      line: number;
      function_name?: string;
    };
    suspected_issues?: string[];
  };
  profile_depth?: 1-5;              // Default: 3
}

hypothesis_test

Test specific theories about code behavior.

{
  hypothesis: string;
  code_scope: {
    files: string[];
    entry_points?: CodeLocation[];    // Optional array of {file, line, function_name?}
  };
  test_approach: string;
}

Example Use Cases

Conversational Analysis Example

When Claude needs deep iterative analysis with Gemini:

// 1. Start conversation
const session = await start_conversation({
  claude_context: {
    attempted_approaches: ["Checked for N+1 queries", "Profiled database calls"],
    partial_findings: [{ type: "performance", description: "Multiple DB queries in loop" }],
    stuck_description: "Can't determine if queries are optimizable",
    code_scope: { files: ["src/services/UserService.ts"] }
  },
  analysis_type: "performance",
  initial_question: "Are these queries necessary or can they be batched?"
});

// 2. Continue with follow-ups
const response = await continue_conversation({
  session_id: session.sessionId,
  message: "The queries fetch user preferences. Could we use a join instead?",
  include_code_snippets: true
});

// 3. Finalize when ready
const results = await finalize_conversation({
  session_id: session.sessionId,
  summary_format: "actionable"
});

Case 1: Distributed Trace Analysis

When a failure signature spans multiple services with GB of logs:

// Claude Code: Identifies the error pattern and suspicious code sections
// Escalate to Gemini when: Need to correlate 1000s of trace spans across 10+ services
// Gemini: Processes the full trace timeline, identifies the exact race window

Case 2: Performance Regression Hunting

When performance degrades but the cause isn't obvious:

// Claude Code: Quick profiling, identifies hot paths
// Escalate to Gemini when: Need to analyze weeks of performance metrics + code changes
// Gemini: Correlates deployment timeline with perf metrics, pinpoints the exact commit

Case 3: Hypothesis-Driven Debugging

When you have theories but need exte