Deep Code Reasoning MCP Server

Realiza análisis de código complementario combinando Claude Code y la IA Gemini de Google.

GitHub
109
Prueba este MCPPatrocinado

Documentación

Deep Code Reasoning MCP Server

License: MIT MCP Compatible Node.js Version

Un servidor MCP que combina Claude Code con la IA Gemini de Google para un análisis de código complementario. Este servidor permite un flujo de trabajo multimodelo donde Claude Code gestiona la integración estrecha con la terminal y la refactorización de múltiples archivos, mientras que Gemini aprovecha su enorme ventana de contexto (1M de tokens) y sus capacidades de ejecución de código para la depuración de sistemas distribuidos y el análisis de trazas largas.

Valor Principal

Tanto Claude como Gemini pueden manejar razonamiento semántico profundo y errores de sistemas distribuidos. Este servidor habilita una estrategia de enrutamiento inteligente donde:

  • Claude Code sobresale en operaciones de contexto local, parches incrementales y flujos de trabajo nativos de CLI
  • Gemini 2.5 Pro destaca con barridos de contexto masivo, ejecución de pruebas sintéticas y análisis de fallos que abarcan registros + trazas + código

El modelo de «escalado» trata a los LLM como microservicios heterogéneos: enruta hacia el más capaz para cada subtarea.

Características

  • Gemini 2.5 Pro Preview: Utiliza el último modelo Gemini 2.5 Pro Preview (05-06) de Google con una ventana de contexto de 1M de tokens
  • Análisis Conversacional: ¡NUEVO! Diálogos de IA a IA entre Claude y Gemini para la resolución iterativa de problemas
  • Trazado de Flujo de Ejecución: Comprende el flujo de datos y las transformaciones de estado, no solo las llamadas a funciones
  • Análisis de Impacto entre Sistemas: Modela cómo se propagan los cambios a través de los límites de los servicios
  • Modelado de Rendimiento: Identifica patrones N+1, fugas de memoria y cuellos de botella algorítmicos
  • Prueba de Hipótesis: Prueba teorías sobre el comportamiento del código con validación basada en evidencia
  • Soporte de Contexto Largo: Aprovecha el contexto de 1M de tokens de Gemini 2.5 Pro Preview para analizar bases de código grandes

Requisitos Previos

  • Node.js 18 o posterior
  • Una cuenta de Google Cloud con acceso a la API de Gemini
  • Clave de API de Gemini desde Google AI Studio

Dependencias Clave

  • @google/generative-ai: SDK oficial de Google para la integración con la API de Gemini
  • @modelcontextprotocol/sdk: Implementación del protocolo MCP para la integración con Claude
  • zod: Validación de tipos en tiempo de ejecución para los parámetros de las herramientas
  • dotenv: Gestión de variables de entorno

Instalación

Instalación Rápida para Cursor

Install MCP Server

Nota: Después de la instalación, deberás actualizar la ruta del archivo a tu directorio de instalación real y configurar tu GEMINI_API_KEY.

Instalación Manual

  1. Clona el repositorio:
git clone https://github.com/Haasonsaas/deep-code-reasoning-mcp.git
cd deep-code-reasoning-mcp
  1. Instala las dependencias:
npm install
  1. Configura tu clave de API de Gemini:
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
  1. Compila el proyecto:
npm run build

Configuración

Variables de Entorno

  • GEMINI_API_KEY (obligatorio): Tu clave de API de Google Gemini

Configuración de Claude Desktop

Añade a tu configuración de 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"
      }
    }
  }
}

Cómo Funciona

  1. Claude Code realiza el análisis inicial utilizando sus puntos fuertes en la refactorización de múltiples archivos y los bucles de desarrollo guiado por pruebas
  2. Cuando es beneficioso, Claude escala a este servidor MCP, especialmente para:
    • Analizar volcados de registros/trazas gigantes que superan el contexto de Claude
    • Ejecutar pruebas de hipótesis iterativas con ejecución de código
    • Correlacionar fallos entre muchos microservicios
  3. El servidor prepara un contexto completo que incluye código, registros y trazas
  4. Gemini analiza con su contexto de 1M de tokens y trazas de «pensamiento» visibles
  5. Los resultados se devuelven a Claude Code para la implementación de correcciones

Herramientas Disponibles

Nota: Los parámetros de las herramientas utilizan la convención de nomenclatura snake_case y se validan mediante esquemas Zod. La implementación real proporciona una seguridad de tipos más detallada que la mostrada en estos ejemplos simplificados. Las definiciones completas de tipos TypeScript están disponibles en src/models/types.ts.

Herramientas de Análisis Conversacional

El servidor ahora incluye herramientas conversacionales de IA a IA que permiten a Claude y Gemini mantener diálogos de múltiples turnos para análisis complejos:

start_conversation

Inicia una sesión de análisis conversacional entre Claude y 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

Continúa una conversación activa con la respuesta o pregunta de seguimiento de Claude.

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

finalize_conversation

Completa la conversación y genera resultados de análisis estructurados.

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

get_conversation_status

Comprueba el estado y el progreso de una conversación en curso.

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

Herramientas de Análisis Tradicionales

escalate_analysis

Herramienta principal para transferir análisis complejos de Claude Code a 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álisis profundo de ejecución con la comprensión semántica de Gemini.

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

cross_system_impact

Analiza impactos a través de los límites de los servicios.

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

performance_bottleneck

Análisis profundo de rendimiento más allá de la creación de perfiles simple.

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

hypothesis_test

Prueba teorías específicas sobre el comportamiento del código.

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

Casos de Uso de Ejemplo

Ejemplo de Análisis Conversacional

Cuando Claude necesita un análisis iterativo profundo con 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álisis de Trazas Distribuidas

Cuando una firma de fallo abarca múltiples servicios con GB de registros:

// 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: Búsqueda de Regresiones de Rendimiento

Cuando el rendimiento se degrada pero la causa no es evidente:

// 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: Depuración Basada en Hipótesis

Cuando tienes teorías pero necesitas pruebas exhaustivas:

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

Desarrollo

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Type check
npm run typecheck

Arquitectura

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

Consideraciones de Seguridad

  • Clave de API: Almacena tu clave de API de Gemini de forma segura en variables de entorno
  • Acceso al Código: El servidor lee archivos locales: asegúrate de que los permisos de archivo sean adecuados
  • Privacidad de Datos: El código se envía a la API de Gemini de Google: revisa sus políticas de datos

Solución de Problemas

"GEMINI_API_KEY not found"

  • Asegúrate de haber configurado GEMINI_API_KEY en tu archivo .env o en el entorno
  • Comprueba que el archivo .env está en la raíz del proyecto

Errores de "File not found"

  • Verifica que las rutas de archivo pasadas a las herramientas sean rutas absolutas
  • Comprueba los permisos de archivo

Errores de la API de Gemini

  • Verifica que tu clave de API sea válida y tenga los permisos adecuados
  • Comprueba las cuotas de la API y los límites de velocidad
  • Asegúrate de que tu proyecto de Google Cloud tenga habilitada la API de Gemini

Errores de validación

  • El servidor utiliza Zod para la validación de parámetros
  • Asegúrate de que se proporcionen todos los parámetros obligatorios
  • Comprueba que los nombres de los parámetros usen snake_case (por ejemplo, claude_context, no claudeContext)
  • Revisa los mensajes de error para conocer los requisitos de validación específicos

Mejores Prácticas para la Depuración Multimodelo

Al depurar sistemas distribuidos con este servidor MCP:

  1. Captura primero la línea de tiempo: utiliza trazas de OpenTelemetry/Jaeger con IDs de solicitud
  2. Empieza con Claude Code: deja que maneje la investigación inicial y las correcciones rápidas
  3. Escala estratégicamente a Gemini cuando necesites:
    • Análisis de trazas que abarcan cientos de MB
    • Correlación entre más de 10 servicios
    • Pruebas de hipótesis iterativas con ejecución de código
  4. Combina con herramientas tradicionales:
    • go test -race, ThreadSanitizer para la detección de condiciones de carrera
    • rr o JFR para la reproducción determinista
    • TLA+ o Alloy para la verificación formal

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de funcionalidad
  3. Realiza tus cambios
  4. Añade pruebas para la nueva funcionalidad
  5. Envía una solicitud de extracción (pull request)

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

Autor

Jonathan Haas - Perfil de GitHub

Agradecimientos

  • Construido para la integración con Claude Code de Anthropic
  • Impulsado por la IA Gemini de Google
  • Utiliza el Protocolo de Contexto de Modelo (MCP) para la comunicación

Soporte

Si encuentras algún problema o tienes preguntas: