{"id":29563293,"url":"https://github.com/haasonsaas/deep-code-reasoning-mcp","last_synced_at":"2025-10-26T07:05:30.997Z","repository":{"id":298429179,"uuid":"999935179","full_name":"haasonsaas/deep-code-reasoning-mcp","owner":"haasonsaas","description":"A Model Context Protocol (MCP) server that provides advanced code analysis and reasoning capabilities powered by Google's Gemini AI","archived":false,"fork":false,"pushed_at":"2025-08-21T01:16:51.000Z","size":176,"stargazers_count":75,"open_issues_count":0,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-21T03:36:03.420Z","etag":null,"topics":["ai","ai-tools","claude","code-analysis","code-intelligence","code-reasoning","debugging","developer-tools","distributed-systems","gemini","hypothesis-testing","llm","mcp","mcp-server","model-context-protocol","multi-model","nodejs","performance-analysis","semantic-analysis","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haasonsaas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-11T02:53:43.000Z","updated_at":"2025-08-21T01:27:44.000Z","dependencies_parsed_at":"2025-06-11T04:25:52.146Z","dependency_job_id":"4a027bb7-1079-4bd2-90f9-6d40c25d9fed","html_url":"https://github.com/haasonsaas/deep-code-reasoning-mcp","commit_stats":null,"previous_names":["haasonsaas/deep-code-reasoning-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/haasonsaas/deep-code-reasoning-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Fdeep-code-reasoning-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Fdeep-code-reasoning-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Fdeep-code-reasoning-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Fdeep-code-reasoning-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haasonsaas","download_url":"https://codeload.github.com/haasonsaas/deep-code-reasoning-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Fdeep-code-reasoning-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275731992,"owners_count":25518090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-tools","claude","code-analysis","code-intelligence","code-reasoning","debugging","developer-tools","distributed-systems","gemini","hypothesis-testing","llm","mcp","mcp-server","model-context-protocol","multi-model","nodejs","performance-analysis","semantic-analysis","typescript"],"created_at":"2025-07-18T18:01:52.308Z","updated_at":"2025-09-18T07:46:17.167Z","avatar_url":"https://github.com/haasonsaas.png","language":"TypeScript","funding_links":[],"categories":["📚 Projects (1974 total)","Coding Agents","カテゴリ","TypeScript"],"sub_categories":["MCP Servers","How to Submit","💻 \u003ca name=\"code--ide\"\u003e\u003c/a\u003eコード・IDE"],"readme":"# Deep Code Reasoning MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.com)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)\n\nAn 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.\n\n## Core Value\n\nBoth Claude and Gemini can handle deep semantic reasoning and distributed system bugs. This server enables an intelligent routing strategy where:\n- **Claude Code** excels at local-context operations, incremental patches, and CLI-native workflows\n- **Gemini 2.5 Pro** shines with huge-context sweeps, synthetic test execution, and analyzing failures that span logs + traces + code\n\nThe \"escalation\" model treats LLMs like heterogeneous microservices - route to the one that's most capable for each sub-task.\n\n## Features\n\n- **Gemini 2.5 Pro Preview**: Uses Google's latest Gemini 2.5 Pro Preview (05-06) model with 1M token context window\n- **Conversational Analysis**: NEW! AI-to-AI dialogues between Claude and Gemini for iterative problem-solving\n- **Execution Flow Tracing**: Understands data flow and state transformations, not just function calls\n- **Cross-System Impact Analysis**: Models how changes propagate across service boundaries\n- **Performance Modeling**: Identifies N+1 patterns, memory leaks, and algorithmic bottlenecks\n- **Hypothesis Testing**: Tests theories about code behavior with evidence-based validation\n- **Long Context Support**: Leverages Gemini 2.5 Pro Preview's 1M token context for analyzing large codebases\n\n## Prerequisites\n\n- Node.js 18 or later\n- A Google Cloud account with Gemini API access\n- Gemini API key from [Google AI Studio](https://makersuite.google.com/app/apikey)\n\n## Key Dependencies\n\n- **@google/generative-ai**: Google's official SDK for Gemini API integration\n- **@modelcontextprotocol/sdk**: MCP protocol implementation for Claude integration\n- **zod**: Runtime type validation for tool parameters\n- **dotenv**: Environment variable management\n\n## Installation\n\n### Quick Install for Cursor\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=deep-code-reasoning\u0026config=eyJjb21tYW5kIjoibm9kZSIsImFyZ3MiOlsiL3BhdGgvdG8vZGVlcC1jb2RlLXJlYXNvbmluZy1tY3AvZGlzdC9pbmRleC5qcyJdLCJlbnYiOnsiR0VNSU5JX0FQSV9LRVkiOiJ5b3VyLWdlbWluaS1hcGkta2V5In19)\n\n*Note: After installation, you'll need to update the file path to your actual installation directory and set your `GEMINI_API_KEY`.*\n\n### Manual Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/Haasonsaas/deep-code-reasoning-mcp.git\ncd deep-code-reasoning-mcp\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Set up your Gemini API key:\n```bash\ncp .env.example .env\n# Edit .env and add your GEMINI_API_KEY\n```\n\n4. Build the project:\n```bash\nnpm run build\n```\n\n## Configuration\n\n### Environment Variables\n\n- `GEMINI_API_KEY` (required): Your Google Gemini API key\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"deep-code-reasoning\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/deep-code-reasoning-mcp/dist/index.js\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-gemini-api-key\"\n      }\n    }\n  }\n}\n```\n\n## How It Works\n\n1. **Claude Code performs initial analysis** using its strengths in multi-file refactoring and test-driven loops\n2. **When beneficial, Claude escalates to this MCP server** - particularly for:\n   - Analyzing gigantic log/trace dumps that exceed Claude's context\n   - Running iterative hypothesis testing with code execution\n   - Correlating failures across many microservices\n3. **Server prepares comprehensive context** including code, logs, and traces\n4. **Gemini analyzes with its 1M-token context** and visible \"thinking\" traces\n5. **Results returned to Claude Code** for implementation of fixes\n\n## Available Tools\n\n**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`.\n\n### Conversational Analysis Tools\n\nThe server now includes AI-to-AI conversational tools that enable Claude and Gemini to engage in multi-turn dialogues for complex analysis:\n\n#### start_conversation\nInitiates a conversational analysis session between Claude and Gemini.\n\n```typescript\n{\n  claude_context: {\n    attempted_approaches: string[];      // What Claude tried\n    partial_findings: any[];            // What Claude found\n    stuck_description: string;          // Where Claude got stuck\n    code_scope: {\n      files: string[];                  // Files to analyze\n      entry_points?: CodeLocation[];    // Starting points\n      service_names?: string[];         // Services involved\n    }\n  };\n  analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test';\n  initial_question?: string;            // Optional opening question\n}\n```\n\n#### continue_conversation\nContinues an active conversation with Claude's response or follow-up question.\n\n```typescript\n{\n  session_id: string;                   // Active session ID\n  message: string;                      // Claude's message to Gemini\n  include_code_snippets?: boolean;      // Enrich with code context\n}\n```\n\n#### finalize_conversation\nCompletes the conversation and generates structured analysis results.\n\n```typescript\n{\n  session_id: string;                   // Active session ID\n  summary_format: 'detailed' | 'concise' | 'actionable';\n}\n```\n\n#### get_conversation_status\nChecks the status and progress of an ongoing conversation.\n\n```typescript\n{\n  session_id: string;                   // Session ID to check\n}\n```\n\n### Traditional Analysis Tools\n\n#### escalate_analysis\nMain tool for handing off complex analysis from Claude Code to Gemini.\n\n```typescript\n{\n  claude_context: {\n    attempted_approaches: string[];      // What Claude tried\n    partial_findings: any[];            // What Claude found\n    stuck_description: string;          // Where Claude got stuck\n    code_scope: {\n      files: string[];                  // Files to analyze\n      entry_points?: CodeLocation[];    // Starting points (file, line, function_name)\n      service_names?: string[];         // Services involved\n    }\n  };\n  analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test';\n  depth_level: 1-5;                     // Analysis depth\n  time_budget_seconds?: number;         // Time limit (default: 60)\n}\n```\n\n### trace_execution_path\nDeep execution analysis with Gemini's semantic understanding.\n\n```typescript\n{\n  entry_point: {\n    file: string;\n    line: number;\n    function_name?: string;\n  };\n  max_depth?: number;              // Default: 10\n  include_data_flow?: boolean;     // Default: true\n}\n```\n\n### cross_system_impact\nAnalyze impacts across service boundaries.\n\n```typescript\n{\n  change_scope: {\n    files: string[];\n    service_names?: string[];\n  };\n  impact_types?: ('breaking' | 'performance' | 'behavioral')[];\n}\n```\n\n### performance_bottleneck\nDeep performance analysis beyond simple profiling.\n\n```typescript\n{\n  code_path: {\n    entry_point: {\n      file: string;\n      line: number;\n      function_name?: string;\n    };\n    suspected_issues?: string[];\n  };\n  profile_depth?: 1-5;              // Default: 3\n}\n```\n\n### hypothesis_test\nTest specific theories about code behavior.\n\n```typescript\n{\n  hypothesis: string;\n  code_scope: {\n    files: string[];\n    entry_points?: CodeLocation[];    // Optional array of {file, line, function_name?}\n  };\n  test_approach: string;\n}\n```\n\n## Example Use Cases\n\n### Conversational Analysis Example\n\nWhen Claude needs deep iterative analysis with Gemini:\n\n```javascript\n// 1. Start conversation\nconst session = await start_conversation({\n  claude_context: {\n    attempted_approaches: [\"Checked for N+1 queries\", \"Profiled database calls\"],\n    partial_findings: [{ type: \"performance\", description: \"Multiple DB queries in loop\" }],\n    stuck_description: \"Can't determine if queries are optimizable\",\n    code_scope: { files: [\"src/services/UserService.ts\"] }\n  },\n  analysis_type: \"performance\",\n  initial_question: \"Are these queries necessary or can they be batched?\"\n});\n\n// 2. Continue with follow-ups\nconst response = await continue_conversation({\n  session_id: session.sessionId,\n  message: \"The queries fetch user preferences. Could we use a join instead?\",\n  include_code_snippets: true\n});\n\n// 3. Finalize when ready\nconst results = await finalize_conversation({\n  session_id: session.sessionId,\n  summary_format: \"actionable\"\n});\n```\n\n### Case 1: Distributed Trace Analysis\n\nWhen a failure signature spans multiple services with GB of logs:\n\n```javascript\n// Claude Code: Identifies the error pattern and suspicious code sections\n// Escalate to Gemini when: Need to correlate 1000s of trace spans across 10+ services\n// Gemini: Processes the full trace timeline, identifies the exact race window\n```\n\n### Case 2: Performance Regression Hunting\n\nWhen performance degrades but the cause isn't obvious:\n\n```javascript\n// Claude Code: Quick profiling, identifies hot paths\n// Escalate to Gemini when: Need to analyze weeks of performance metrics + code changes\n// Gemini: Correlates deployment timeline with perf metrics, pinpoints the exact commit\n```\n\n### Case 3: Hypothesis-Driven Debugging\n\nWhen you have theories but need extensive testing:\n\n```javascript\n// Claude Code: Forms initial hypotheses based on symptoms\n// Escalate to Gemini when: Need to test 20+ scenarios with synthetic data\n// Gemini: Uses code execution API to validate each hypothesis systematically\n```\n\n## Development\n\n```bash\n# Run in development mode\nnpm run dev\n\n# Run tests\nnpm test\n\n# Lint code\nnpm run lint\n\n# Type check\nnpm run typecheck\n```\n\n## Architecture\n\n```\n┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐\n│  Claude Code    │────▶│  MCP Server      │────▶│  Gemini API    │\n│  (Fast, Local, │     │  (Router \u0026       │     │  (1M Context,   │\n│   CLI-Native)  │◀────│   Orchestrator)  │◀────│   Code Exec)    │\n└─────────────────┘     └──────────────────┘     └─────────────────┘\n                               │\n                               ▼\n                        ┌──────────────────┐\n                        │  Code + Logs +   │\n                        │  Traces + Tests  │\n                        └──────────────────┘\n```\n\n## Security Considerations\n\n- **API Key**: Store your Gemini API key securely in environment variables\n- **Code Access**: The server reads local files - ensure proper file permissions\n- **Data Privacy**: Code is sent to Google's Gemini API - review their data policies\n\n## Troubleshooting\n\n### \"GEMINI_API_KEY not found\"\n- Ensure you've set the `GEMINI_API_KEY` in your `.env` file or environment\n- Check that the `.env` file is in the project root\n\n### \"File not found\" errors\n- Verify that file paths passed to the tools are absolute paths\n- Check file permissions\n\n### Gemini API errors\n- Verify your API key is valid and has appropriate permissions\n- Check API quotas and rate limits\n- Ensure your Google Cloud project has the Gemini API enabled\n\n### Validation errors\n- The server uses Zod for parameter validation\n- Ensure all required parameters are provided\n- Check that parameter names use snake_case (e.g., `claude_context`, not `claudeContext`)\n- Review error messages for specific validation requirements\n\n## Best Practices for Multi-Model Debugging\n\nWhen debugging distributed systems with this MCP server:\n\n1. **Capture the timeline first** - Use OpenTelemetry/Jaeger traces with request IDs\n2. **Start with Claude Code** - Let it handle the initial investigation and quick fixes\n3. **Escalate strategically** to Gemini when you need:\n   - Analysis of traces spanning 100s of MB\n   - Correlation across 10+ services\n   - Iterative hypothesis testing with code execution\n4. **Combine with traditional tools**:\n   - `go test -race`, ThreadSanitizer for race detection\n   - rr or JFR for deterministic replay\n   - TLA+ or Alloy for formal verification\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Jonathan Haas** - [GitHub Profile](https://github.com/Haasonsaas)\n\n## Acknowledgments\n\n- Built for integration with Anthropic's Claude Code\n- Powered by Google's Gemini AI\n- Uses the Model Context Protocol (MCP) for communication\n\n## Support\n\nIf you encounter any issues or have questions:\n- Open an issue on [GitHub Issues](https://github.com/Haasonsaas/deep-code-reasoning-mcp/issues)\n- Check the [troubleshooting section](#troubleshooting) above\n- Review the [MCP documentation](https://modelcontextprotocol.com)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaasonsaas%2Fdeep-code-reasoning-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaasonsaas%2Fdeep-code-reasoning-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaasonsaas%2Fdeep-code-reasoning-mcp/lists"}