Deep Code Reasoning MCP Server

Realiza análise complementar de código combinando Claude Code e a IA Gemini do Google.

GitHub
109

Documentação

Servidor MCP Deep Code Reasoning

License: MIT MCP Compatible Node.js Version

Um servidor MCP que combina o Claude Code com o Gemini AI do Google para análise de código complementar. Este servidor permite um fluxo de trabalho com múltiplos modelos, onde o Claude Code lida com integração estreita com o terminal e refatoração de múltiplos arquivos, enquanto o Gemini aproveita sua janela de contexto massiva (1M de tokens) e capacidades de execução de código para depuração de sistemas distribuídos e análise de rastreamentos longos.

Valor Principal

Tanto o Claude quanto o Gemini podem lidar com raciocínio semântico profundo e bugs em sistemas distribuídos. Este servidor permite uma estratégia de roteamento inteligente onde:

  • Claude Code se destaca em operações de contexto local, patches incrementais e fluxos de trabalho nativos de CLI
  • Gemini 2.5 Pro brilha com varreduras de contexto enorme, execução de testes sintéticos e análise de falhas que abrangem logs + rastreamentos + código

O modelo de "escalonamento" trata os LLMs como microsserviços heterogêneos - roteie para aquele que é mais capaz para cada subtarefa.

Recursos

  • Gemini 2.5 Pro Preview: Usa o modelo mais recente do Google, Gemini 2.5 Pro Preview (05-06), com janela de contexto de 1M de tokens
  • Análise Conversacional: NOVO! Diálogos entre IA e IA entre Claude e Gemini para resolução iterativa de problemas
  • Rastreamento de Fluxo de Execução: Entende o fluxo de dados e transformações de estado, não apenas chamadas de função
  • Análise de Impacto Entre Sistemas: Modela como as mudanças se propagam através das fronteiras de serviço
  • Modelagem de Desempenho: Identifica padrões N+1, vazamentos de memória e gargalos algorítmicos
  • Teste de Hipóteses: Testa teorias sobre o comportamento do código com validação baseada em evidências
  • Suporte a Contexto Longo: Aproveita a janela de contexto de 1M de tokens do Gemini 2.5 Pro Preview para analisar grandes bases de código

Pré-requisitos

  • Node.js 18 ou posterior
  • Uma conta do Google Cloud com acesso à API Gemini
  • Chave da API Gemini do Google AI Studio

Dependências Principais

  • @google/generative-ai: SDK oficial do Google para integração com a API Gemini
  • @modelcontextprotocol/sdk: Implementação do protocolo MCP para integração com Claude
  • zod: Validação de tipos em tempo de execução para parâmetros de ferramentas
  • dotenv: Gerenciamento de variáveis de ambiente

Instalação

Instalação Rápida para Cursor

Install MCP Server

Nota: Após a instalação, você precisará atualizar o caminho do arquivo para o seu diretório de instalação real e definir seu GEMINI_API_KEY.

Instalação Manual

  1. Clone o repositório:
git clone https://github.com/Haasonsaas/deep-code-reasoning-mcp.git
cd deep-code-reasoning-mcp
  1. Instale as dependências:
npm install
  1. Configure sua chave da API Gemini:
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
  1. Compile o projeto:
npm run build

Configuração

Variáveis de Ambiente

  • GEMINI_API_KEY (obrigatório): Sua chave da API Google Gemini

Configuração do Claude Desktop

Adicione à sua configuração do Claude Desktop (~/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"
      }
    }
  }
}

Como Funciona

  1. O Claude Code realiza a análise inicial usando seus pontos fortes em refatoração de múltiplos arquivos e loops orientados a testes
  2. Quando benéfico, o Claude escala para este servidor MCP - particularmente para:
    • Analisar despejos gigantes de logs/rastreamentos que excedem o contexto do Claude
    • Executar testes iterativos de hipóteses com execução de código
    • Correlacionar falhas em muitos microsserviços
  3. O servidor prepara contexto abrangente incluindo código, logs e rastreamentos
  4. O Gemini analisa com seu contexto de 1M de tokens e rastreamentos visíveis de "pensamento"
  5. Os resultados são retornados ao Claude Code para implementação das correções

Ferramentas Disponíveis

Nota: Os parâmetros das ferramentas usam a convenção de nomenclatura snake_case e são validados usando esquemas Zod. A implementação real fornece segurança de tipos mais detalhada do que a mostrada nestes exemplos simplificados. As definições completas de tipos TypeScript estão disponíveis em src/models/types.ts.

Ferramentas de Análise Conversacional

O servidor agora inclui ferramentas conversacionais entre IA e IA que permitem que Claude e Gemini se envolvam em diálogos de múltiplas etapas para análises complexas:

start_conversation

Inicia uma sessão de análise conversacional entre Claude e 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

Continua uma conversa ativa com a resposta do Claude ou pergunta de acompanhamento.

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

finalize_conversation

Conclui a conversa e gera resultados de análise estruturados.

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

get_conversation_status

Verifica o status e o progresso de uma conversa em andamento.

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

Ferramentas de Análise Tradicionais

escalate_analysis

Ferramenta principal para transferir análises complexas do Claude Code para o 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

Análise profunda de execução com a compreensão semântica do Gemini.

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

cross_system_impact

Analisa impactos através das fronteiras de serviço.

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

performance_bottleneck

Análise profunda de desempenho além da criação de perfis simples.

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

hypothesis_test

Testa teorias específicas sobre o comportamento do código.

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

Exemplos de Casos de Uso

Exemplo de Análise Conversacional

Quando o Claude precisa de análise iterativa profunda com o 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"
});

Caso 1: Análise de Rastreamento Distribuído

Quando uma assinatura de falha abrange múltiplos serviços com GB de 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

Caso 2: Busca de Regressão de Desempenho

Quando o desempenho degrada, mas a causa não é óbvia:

// 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

Caso 3: Depuração Orientada por Hipóteses

Quando você tem teorias, mas precisa de testes extensivos:

// 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

Desenvolvimento

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Type check
npm run typecheck

Arquitetura

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude Code    │────▶│  MCP Server      │────▶│  Gemini API    │
│  (Fast, Local, │     │  (Router &       │     │  (1M Context,   │
│   CLI-Native)  │◀────│   Orchestrator)  │◀────│   Code Exec)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  Code + Logs +   │
                        │  Traces + Tests  │
                        └──────────────────┘

Considerações de Segurança

  • Chave da API: Armazene sua chave da API Gemini com segurança em variáveis de ambiente
  • Acesso ao Código: O servidor lê arquivos locais - garanta permissões de arquivo adequadas
  • Privacidade dos Dados: O código é enviado à API Gemini do Google - revise as políticas de dados deles

Solução de Problemas

"GEMINI_API_KEY não encontrada"

  • Certifique-se de ter definido o GEMINI_API_KEY no seu arquivo .env ou no ambiente
  • Verifique se o arquivo .env está na raiz do projeto

Erros de "Arquivo não encontrado"

  • Verifique se os caminhos de arquivo passados às ferramentas são caminhos absolutos
  • Verifique as permissões dos arquivos

Erros da API Gemini

  • Verifique se sua chave da API é válida e tem as permissões apropriadas
  • Verifique cotas e limites de taxa da API
  • Certifique-se de que seu projeto do Google Cloud tenha a API Gemini habilitada

Erros de Validação

  • O servidor usa Zod para validação de parâmetros
  • Certifique-se de que todos os parâmetros obrigatórios sejam fornecidos
  • Verifique se os nomes dos parâmetros usam snake_case (por exemplo, claude_context, não claudeContext)
  • Revise as mensagens de erro para requisitos específicos de validação

Melhores Práticas para Depuração com Múltiplos Modelos

Ao depurar sistemas distribuídos com este servidor MCP:

  1. Capture a linha do tempo primeiro - Use rastreamentos OpenTelemetry/Jaeger com IDs de requisição
  2. Comece com o Claude Code - Deixe-o lidar com a investigação inicial e correções rápidas
  3. Escalone estrategicamente para o Gemini quando precisar de:
    • Análise de rastreamentos que abrangem centenas de MB
    • Correlação entre 10+ serviços
    • Testes iterativos de hipóteses com execução de código
  4. Combine com ferramentas tradicionais:
    • go test -race, ThreadSanitizer para detecção de corridas
    • rr ou JFR para reprodução determinística
    • TLA+ ou Alloy para verificação formal

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Faça suas alterações
  4. Adicione testes para novas funcionalidades
  5. Envie um pull request

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Autor

Jonathan Haas - Perfil no GitHub

Agradecimentos

  • Construído para integração com o Claude Code da Anthropic
  • Alimentado pelo Gemini AI do Google
  • Usa o Protocolo de Contexto de Modelo (MCP) para comunicação

Suporte

Se você encontrar problemas ou tiver dúvidas: