deep-code-reasoning-mcp

# Deep Code Reasoning MCP Server [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.com) [](https://nodejs.org) An MCP server that pairs Claude Code with Google's Gemini AI for complementary code analysis. This server enables a multi-model workflow where Claude Code handles tight terminal integration and multi-file refactoring, while Gemini leverages its massive context window (1M tokens) and code execution capabilities for distributed system debugging and long-trace analysis. ## Core Value Both Claude and Gemini can handle deep semantic reasoning and distributed system bugs. This server enables an intelligent routing strategy where: - **Claude Code** excels at local-context operations, incremental patches, and CLI-native workflows - **Gemini 2.5 Pro** shines with huge-context sweeps, synthetic test execution, and analyzing failures that span logs + traces + code The "escalation" model treats LLMs like heterogeneous microservices - route to the one that's most capable for each sub-task. ## Features - **Gemini 2.5 Pro Preview**: Uses Google's latest Gemini 2.5 Pro Preview (05-06) model with 1M token context window - **Conversational Analysis**: NEW! AI-to-AI dialogues between Claude and Gemini for iterative problem-solving - **Execution Flow Tracing**: Understands data flow and state transformations, not just function calls - **Cross-System Impact Analysis**: Models how changes propagate across service boundaries - **Performance Modeling**: Identifies N+1 patterns, memory leaks, and algorithmic bottlenecks - **Hypothesis Testing**: Tests theories about code behavior with evidence-based validation - **Long Context Support**: Leverages Gemini 2.5 Pro Preview's 1M token context for analyzing large codebases ## Prerequisites - Node.js 18 or later - A Google Cloud account with Gemini API access - Gemini API key from [Google AI Studio](https://makersuite.google.com/app/apikey) ## 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 [](https://cursor.com/install-mcp?name=deep-code-reasoning&config=eyJjb21tYW5kIjoibm9kZSIsImFyZ3MiOlsiL3BhdGgvdG8vZGVlcC1jb2RlLXJlYXNvbmluZy1tY3AvZGlzdC9pbmRleC5qcyJdLCJlbnYiOnsiR0VNSU5JX0FQSV9LRVkiOiJ5b3VyLWdlbWluaS1hcGkta2V5In19) *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: ```bash git clone https://github.com/Haasonsaas/deep-code-reasoning-mcp.git cd deep-code-reasoning-mcp ``` 2. Install dependencies: ```bash npm install ``` 3. Set up your Gemini API key: ```bash cp .env.example .env # Edit .env and add your GEMINI_API_KEY ``` 4. Build the project: ```bash 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`): ```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. ```typescript { 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. ```typescript { 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. ```typescript { session_id: string; // Active session ID summary_format: 'detailed' | 'concise' | 'actionable'; } ``` #### get_conversation_status Checks the status and progress of an ongoing conversation. ```typescript { session_id: string; // Session ID to check } ``` ### Traditional Analysis Tools #### escalate_analysis Main tool for handing off complex analysis from Claude Code to Gemini. ```typescript { 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. ```typescript { 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. ```typescript { change_scope: { files: string[]; service_names?: string[]; }; impact_types?: ('breaking' | 'performance' | 'behavioral')[]; } ``` ### performance_bottleneck Deep performance analysis beyond simple profiling. ```typescript { 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. ```typescript { 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: ```javascript // 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: ```javascript // 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: ```javascript // 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 extensive testing: ```javascript // Claude Code: Forms initial hypotheses based on symptoms // Escalate to Gemini when: Need to test 20+ scenarios with synthetic data // Gemini: Uses code execution API to validate each hypothesis systematically ``` ## Development ```bash # Run in development mode npm run dev # Run tests npm test # Lint code npm run lint # Type check npm run typecheck ``` ## Architecture ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Claude Code │────▶│ MCP Server │────▶│ Gemini API │ │ (Fast, Local, │ │ (Router & │ │ (1M Context, │ │ CLI-Native) │◀────│ Orchestrator) │◀────│ Code Exec) │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ Code + Logs + │ │ Traces + Tests │ └──────────────────┘ ``` ## Security Considerations - **API Key**: Store your Gemini API key securely in environment variables - **Code Access**: The server reads local files - ensure proper file permissions - **Data Privacy**: Code is sent to Google's Gemini API - review their data policies ## Troubleshooting ### "GEMINI_API_KEY not found" - Ensure you've set the `GEMINI_API_KEY` in your `.env` file or environment - Check that the `.env` file is in the project root ### "File not found" errors - Verify that file paths passed to the tools are absolute paths - Check file permissions ### Gemini API errors - Verify your API key is valid and has appropriate permissions - Check API quotas and rate limits - Ensure your Google Cloud project has the Gemini API enabled ### Validation errors - The server uses Zod for parameter validation - Ensure all required parameters are provided - Check that parameter names use snake_case (e.g., `claude_context`, not `claudeContext`) - Review error messages for specific validation requirements ## Best Practices for Multi-Model Debugging When debugging distributed systems with this MCP server: 1. **Capture the timeline first** - Use OpenTelemetry/Jaeger traces with request IDs 2. **Start with Claude Code** - Let it handle the initial investigation and quick fixes 3. **Escalate strategically** to Gemini when you need: - Analysis of traces spanning 100s of MB - Correlation across 10+ services - Iterative hypothesis testing with code execution 4. **Combine with traditional tools**: - `go test -race`, ThreadSanitizer for race detection - rr or JFR for deterministic replay - TLA+ or Alloy for formal verification ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests for new functionality 5. Submit a pull request ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Author **Jonathan Haas** - [GitHub Profile](https://github.com/Haasonsaas) ## Acknowledgments - Built for integration with Anthropic's Claude Code - Powered by Google's Gemini AI - Uses the Model Context Protocol (MCP) for communication ## Support If you encounter any issues or have questions: - Open an issue on [GitHub Issues](https://github.com/Haasonsaas/deep-code-reasoning-mcp/issues) - Check the [troubleshooting section](#troubleshooting) above - Review the [MCP documentation](https://modelcontextprotocol.com)