Skip to content
Back to search

deep-code-reasoning-mcp

A Model Context Protocol (MCP) server that provides advanced code analysis and reasoning capabilities powered by Google's Gemini AI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dx-corp/deep-code-reasoning-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dx-corp/deep-code-reasoning-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dx-corp--deep-code-reasoning-mcp/badge.svg)](/listings/dx-corp--deep-code-reasoning-mcp)

HTML

<a href="/listings/dx-corp--deep-code-reasoning-mcp"><img src="/api/listings/dx-corp--deep-code-reasoning-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 411 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Deep Code Reasoning MCP Server
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.com)
  4. [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
  5. 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.
  6. ## Core Value
  7. Both Claude and Gemini can handle deep semantic reasoning and distributed system bugs. This server enables an intelligent routing strategy where:
  8. - **Claude Code** excels at local-context operations, incremental patches, and CLI-native workflows
  9. - **Gemini 2.5 Pro** shines with huge-context sweeps, synthetic test execution, and analyzing failures that span logs + traces + code
  10. The "escalation" model treats LLMs like heterogeneous microservices - route to the one that's most capable for each sub-task.
  11. ## Features
  12. - **Gemini 2.5 Pro Preview**: Uses Google's latest Gemini 2.5 Pro Preview (05-06) model with 1M token context window
  13. - **Conversational Analysis**: NEW! AI-to-AI dialogues between Claude and Gemini for iterative problem-solving
  14. - **Execution Flow Tracing**: Understands data flow and state transformations, not just function calls
  15. - **Cross-System Impact Analysis**: Models how changes propagate across service boundaries
  16. - **Performance Modeling**: Identifies N+1 patterns, memory leaks, and algorithmic bottlenecks
  17. - **Hypothesis Testing**: Tests theories about code behavior with evidence-based validation
  18. - **Long Context Support**: Leverages Gemini 2.5 Pro Preview's 1M token context for analyzing large codebases
  19. ## Prerequisites
  20. - Node.js 18 or later
  21. - A Google Cloud account with Gemini API access
  22. - Gemini API key from [Google AI Studio](https://makersuite.google.com/app/apikey)
  23. ## Key Dependencies
  24. - **@google/generative-ai**: Google's official SDK for Gemini API integration
  25. - **@modelcontextprotocol/sdk**: MCP protocol implementation for Claude integration
  26. - **zod**: Runtime type validation for tool parameters
  27. - **dotenv**: Environment variable management
  28. ## Installation
  29. ### Quick Install for Cursor
  30. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=deep-code-reasoning&config=eyJjb21tYW5kIjoibm9kZSIsImFyZ3MiOlsiL3BhdGgvdG8vZGVlcC1jb2RlLXJlYXNvbmluZy1tY3AvZGlzdC9pbmRleC5qcyJdLCJlbnYiOnsiR0VNSU5JX0FQSV9LRVkiOiJ5b3VyLWdlbWluaS1hcGkta2V5In19)
  31. *Note: After installation, you'll need to update the file path to your actual installation directory and set your `GEMINI_API_KEY`.*
  32. ### Manual Installation
  33. 1. Clone the repository:
  34. ```bash
  35. git clone https://github.com/Haasonsaas/deep-code-reasoning-mcp.git
  36. cd deep-code-reasoning-mcp
  37. ```
  38. 2. Install dependencies:
  39. ```bash
  40. npm install
  41. ```
  42. 3. Set up your Gemini API key:
  43. ```bash
  44. cp .env.example .env
  45. # Edit .env and add your GEMINI_API_KEY
  46. ```
  47. 4. Build the project:
  48. ```bash
  49. npm run build
  50. ```
  51. ## Configuration
  52. ### Environment Variables
  53. - `GEMINI_API_KEY` (required): Your Google Gemini API key
  54. ### Claude Desktop Configuration
  55. Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  56. ```json
  57. {
  58. "mcpServers": {
  59. "deep-code-reasoning": {
  60. "command": "node",
  61. "args": ["/path/to/deep-code-reasoning-mcp/dist/index.js"],
  62. "env": {
  63. "GEMINI_API_KEY": "your-gemini-api-key"
  64. }
  65. }
  66. }
  67. }
  68. ```
  69. ## How It Works
  70. 1. **Claude Code performs initial analysis** using its strengths in multi-file refactoring and test-driven loops
  71. 2. **When beneficial, Claude escalates to this MCP server** - particularly for:
  72. - Analyzing gigantic log/trace dumps that exceed Claude's context
  73. - Running iterative hypothesis testing with code execution
  74. - Correlating failures across many microservices
  75. 3. **Server prepares comprehensive context** including code, logs, and traces
  76. 4. **Gemini analyzes with its 1M-token context** and visible "thinking" traces
  77. 5. **Results returned to Claude Code** for implementation of fixes
  78. ## Available Tools
  79. **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`.
  80. ### Conversational Analysis Tools
  81. The server now includes AI-to-AI conversational tools that enable Claude and Gemini to engage in multi-turn dialogues for complex analysis:
  82. #### start_conversation
  83. Initiates a conversational analysis session between Claude and Gemini.
  84. ```typescript
  85. {
  86. claude_context: {
  87. attempted_approaches: string[]; // What Claude tried
  88. partial_findings: any[]; // What Claude found
  89. stuck_description: string; // Where Claude got stuck
  90. code_scope: {
  91. files: string[]; // Files to analyze
  92. entry_points?: CodeLocation[]; // Starting points
  93. service_names?: string[]; // Services involved
  94. }
  95. };
  96. analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test';
  97. initial_question?: string; // Optional opening question
  98. }
  99. ```
  100. #### continue_conversation
  101. Continues an active conversation with Claude's response or follow-up question.
  102. ```typescript
  103. {
  104. session_id: string; // Active session ID
  105. message: string; // Claude's message to Gemini
  106. include_code_snippets?: boolean; // Enrich with code context
  107. }
  108. ```
  109. #### finalize_conversation
  110. Completes the conversation and generates structured analysis results.
  111. ```typescript
  112. {
  113. session_id: string; // Active session ID
  114. summary_format: 'detailed' | 'concise' | 'actionable';
  115. }
  116. ```
  117. #### get_conversation_status
  118. Checks the status and progress of an ongoing conversation.
  119. ```typescript
  120. {
  121. session_id: string; // Session ID to check
  122. }
  123. ```
  124. ### Traditional Analysis Tools
  125. #### escalate_analysis
  126. Main tool for handing off complex analysis from Claude Code to Gemini.
  127. ```typescript
  128. {
  129. claude_context: {
  130. attempted_approaches: string[]; // What Claude tried
  131. partial_findings: any[]; // What Claude found
  132. stuck_description: string; // Where Claude got stuck
  133. code_scope: {
  134. files: string[]; // Files to analyze
  135. entry_points?: CodeLocation[]; // Starting points (file, line, function_name)
  136. service_names?: string[]; // Services involved
  137. }
  138. };
  139. analysis_type: 'execution_trace' | 'cross_system' | 'performance' | 'hypothesis_test';
  140. depth_level: 1-5; // Analysis depth
  141. time_budget_seconds?: number; // Time limit (default: 60)
  142. }
  143. ```
  144. ### trace_execution_path
  145. Deep execution analysis with Gemini's semantic understanding.
  146. ```typescript
  147. {
  148. entry_point: {
  149. file: string;
  150. line: number;
  151. function_name?: string;
  152. };
  153. max_depth?: number; // Default: 10
  154. include_data_flow?: boolean; // Default: true
  155. }
  156. ```
  157. ### cross_system_impact
  158. Analyze impacts across service boundaries.
  159. ```typescript
  160. {
  161. change_scope: {
  162. files: string[];
  163. service_names?: string[];
  164. };
  165. impact_types?: ('breaking' | 'performance' | 'behavioral')[];
  166. }
  167. ```
  168. ### performance_bottleneck
  169. Deep performance analysis beyond simple profiling.
  170. ```typescript
  171. {
  172. code_path: {
  173. entry_point: {
  174. file: string;
  175. line: number;
  176. function_name?: string;
  177. };
  178. suspected_issues?: string[];
  179. };
  180. profile_depth?: 1-5; // Default: 3
  181. }
  182. ```
  183. ### hypothesis_test
  184. Test specific theories about code behavior.
  185. ```typescript
  186. {
  187. hypothesis: string;
  188. code_scope: {
  189. files: string[];
  190. entry_points?: CodeLocation[]; // Optional array of {file, line, function_name?}
  191. };
  192. test_approach: string;
  193. }
  194. ```
  195. ## Example Use Cases
  196. ### Conversational Analysis Example
  197. When Claude needs deep iterative analysis with Gemini:
  198. ```javascript
  199. // 1. Start conversation
  200. const session = await start_conversation({
  201. claude_context: {
  202. attempted_approaches: ["Checked for N+1 queries", "Profiled database calls"],
  203. partial_findings: [{ type: "performance", description: "Multiple DB queries in loop" }],
  204. stuck_description: "Can't determine if queries are optimizable",
  205. code_scope: { files: ["src/services/UserService.ts"] }
  206. },
  207. analysis_type: "performance",
  208. initial_question: "Are these queries necessary or can they be batched?"
  209. });
  210. // 2. Continue with follow-ups
  211. const response = await continue_conversation({
  212. session_id: session.sessionId,
  213. message: "The queries fetch user preferences. Could we use a join instead?",
  214. include_code_snippets: true
  215. });
  216. // 3. Finalize when ready
  217. const results = await finalize_conversation({
  218. session_id: session.sessionId,
  219. summary_format: "actionable"
  220. });
  221. ```
  222. ### Case 1: Distributed Trace Analysis
  223. When a failure signature spans multiple services with GB of logs:
  224. ```javascript
  225. // Claude Code: Identifies the error pattern and suspicious code sections
  226. // Escalate to Gemini when: Need to correlate 1000s of trace spans across 10+ services
  227. // Gemini: Processes the full trace timeline, identifies the exact race window
  228. ```
  229. ### Case 2: Performance Regression Hunting
  230. When performance degrades but the cause isn't obvious:
  231. ```javascript
  232. // Claude Code: Quick profiling, identifies hot paths
  233. // Escalate to Gemini when: Need to analyze weeks of performance metrics + code changes
  234. // Gemini: Correlates deployment timeline with perf metrics, pinpoints the exact commit
  235. ```
  236. ### Case 3: Hypothesis-Driven Debugging
  237. When you have theories but need extensive testing:
  238. ```javascript
  239. // Claude Code: Forms initial hypotheses based on symptoms
  240. // Escalate to Gemini when: Need to test 20+ scenarios with synthetic data
  241. // Gemini: Uses code execution API to validate each hypothesis systematically
  242. ```
  243. ## Development
  244. ```bash
  245. # Run in development mode
  246. npm run dev
  247. # Run tests
  248. npm test
  249. # Lint code
  250. npm run lint
  251. # Type check
  252. npm run typecheck
  253. ```
  254. ## Architecture
  255. ```
  256. ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
  257. │ Claude Code │────▶│ MCP Server │────▶│ Gemini API │
  258. │ (Fast, Local, │ │ (Router & │ │ (1M Context, │
  259. │ CLI-Native) │◀────│ Orchestrator) │◀────│ Code Exec) │
  260. └─────────────────┘ └──────────────────┘ └─────────────────┘
  261. │
  262. ▼
  263. ┌──────────────────┐
  264. │ Code + Logs + │
  265. │ Traces + Tests │
  266. └──────────────────┘
  267. ```
  268. ## Security Considerations
  269. - **API Key**: Store your Gemini API key securely in environment variables
  270. - **Code Access**: The server reads local files - ensure proper file permissions
  271. - **Data Privacy**: Code is sent to Google's Gemini API - review their data policies
  272. ## Troubleshooting
  273. ### "GEMINI_API_KEY not found"
  274. - Ensure you've set the `GEMINI_API_KEY` in your `.env` file or environment
  275. - Check that the `.env` file is in the project root
  276. ### "File not found" errors
  277. - Verify that file paths passed to the tools are absolute paths
  278. - Check file permissions
  279. ### Gemini API errors
  280. - Verify your API key is valid and has appropriate permissions
  281. - Check API quotas and rate limits
  282. - Ensure your Google Cloud project has the Gemini API enabled
  283. ### Validation errors
  284. - The server uses Zod for parameter validation
  285. - Ensure all required parameters are provided
  286. - Check that parameter names use snake_case (e.g., `claude_context`, not `claudeContext`)
  287. - Review error messages for specific validation requirements
  288. ## Best Practices for Multi-Model Debugging
  289. When debugging distributed systems with this MCP server:
  290. 1. **Capture the timeline first** - Use OpenTelemetry/Jaeger traces with request IDs
  291. 2. **Start with Claude Code** - Let it handle the initial investigation and quick fixes
  292. 3. **Escalate strategically** to Gemini when you need:
  293. - Analysis of traces spanning 100s of MB
  294. - Correlation across 10+ services
  295. - Iterative hypothesis testing with code execution
  296. 4. **Combine with traditional tools**:
  297. - `go test -race`, ThreadSanitizer for race detection
  298. - rr or JFR for deterministic replay
  299. - TLA+ or Alloy for formal verification
  300. ## Contributing
  301. 1. Fork the repository
  302. 2. Create a feature branch
  303. 3. Make your changes
  304. 4. Add tests for new functionality
  305. 5. Submit a pull request
  306. ## License
  307. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  308. ## Author
  309. **Jonathan Haas** - [GitHub Profile](https://github.com/Haasonsaas)
  310. ## Acknowledgments
  311. - Built for integration with Anthropic's Claude Code
  312. - Powered by Google's Gemini AI
  313. - Uses the Model Context Protocol (MCP) for communication
  314. ## Support
  315. If you encounter any issues or have questions:
  316. - Open an issue on [GitHub Issues](https://github.com/Haasonsaas/deep-code-reasoning-mcp/issues)
  317. - Check the [troubleshooting section](#troubleshooting) above
  318. - Review the [MCP documentation](https://modelcontextprotocol.com)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.