# Deep Code Reasoning Mcp

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-evalops-deep-code-reasoning-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [evalops](https://agentstack.voostack.com/s/evalops)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [evalops](https://github.com/evalops)
- **Source:** https://github.com/evalops/deep-code-reasoning-mcp

## Install

```sh
agentstack add mcp-evalops-deep-code-reasoning-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [evalops](https://github.com/evalops)
- **Source:** [evalops/deep-code-reasoning-mcp](https://github.com/evalops/deep-code-reasoning-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-evalops-deep-code-reasoning-mcp
- Seller: https://agentstack.voostack.com/s/evalops
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.