Gemini Researcher

Un servidor MCP (Model Context Protocol) ligero y sin estado que permite a los agentes de desarrollo (Claude Code, GitHub Copilot) delegar el análisis profundo de repositorios a la CLI de Gemini. El servidor es de solo lectura, devuelve JSON estructurado (como contenido de texto) y está diseñado para reducir el contexto y el uso del modelo del agente que realiza la llamada.

Estado: v1 completada. Las funciones principales son estables, pero aún estamos en una etapa temprana. ¡Los comentarios son bienvenidos!

Si esto te ha ahorrado tokens, ⭐ ¡por favor considera darle una estrella! :)

Los objetivos principales:

• Reducir el uso del contexto del agente permitiendo que la CLI de Gemini lea grandes bases de código localmente y realice su propia investigación

• Reducir el uso del modelo del agente que realiza la llamada delegando el análisis pesado a Gemini

• Mantener el servidor sin estado y de solo lectura por seguridad

¿Por qué usar esto?

En lugar de copiar archivos enteros en el contexto de tu agente (quemando tokens y saturando la conversación), este servidor permite que la CLI de Gemini lea archivos directamente desde tu proyecto. Tu agente envía una consulta de investigación, Gemini lee y sintetiza utilizando su gran ventana de contexto, y devuelve resultados estructurados. Ahorras tokens, tu agente se mantiene enfocado y el análisis complejo de la base de código se vuelve práctico.

Clientes verificados: Claude Code, Cursor, VS Code (GitHub Copilot)

Tabla de contenidos

• Gemini Researcher

  • Descripción general

  • Requisitos previos

  • Inicio rápido

    • Paso 1: Validar el entorno

    • Paso 2: Configurar tu cliente MCP

    • Paso 3: Reiniciar tu cliente MCP

    • Paso 4: Probarlo

  • Herramientas

    • Flujos de trabajo de ejemplo

  • Docker

  • Solución de problemas (problemas comunes)

  • Contribución

  • Licencia

Descripción general

Gemini Researcher acepta consultas de estilo de investigación a través del protocolo MCP y lanza la CLI de Gemini en modo headless para analizar archivos locales referenciados con @path. Los resultados se devuelven como cadenas JSON formateadas para los clientes agentes.

Contrato de seguridad en tiempo de ejecución

La semántica canónica de tiempo de ejecución se mantiene en docs/runtime-contract.md.

Gemini Researcher aplica este contrato de invocación para las solicitudes de análisis:

gemini [ -m <model> ] --output-format json --approval-mode default [--admin-policy <path>] -p "<prompt>"

• El servidor utiliza -p/--prompt para una ejecución explícita no interactiva y headless.

• El servidor no utiliza -y/--yolo en los argumentos generados por el servidor.

• El comportamiento de solo lectura se aplica mediante una política de administración incluida por defecto.

• La aplicación estricta de la política de administración puede relajarse con GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0 (o false|no|off).

Comportamiento de la política de solo lectura

• El modo predeterminado es la aplicación estricta de fallo cerrado.

• La política incluida deniega herramientas de mutación conocidas (por ejemplo: write_file, replace, run_shell_command).

• La política se basa en una lista de denegación. Si Gemini introduce nuevos nombres de herramientas de mutación en futuras versiones, es posible que se requieran actualizaciones de la política.

• Las extensiones permanecen habilitadas por diseño. Esto es conveniente, pero significa que la aplicación de la política debe permanecer habilitada en producción.

Semántica de autenticación y salud

Cuando ejecutas health_check con includeDiagnostics: true, los diagnósticos incluyen el estado de autenticación y el estado de aplicación de la política.

health_check.status es:

• ok solo cuando Gemini está disponible, la autenticación está configurada y se cumple la aplicación estricta de solo lectura (o se relaja intencionalmente mediante el interruptor de entorno).

• degraded para todas las rutas de incertidumbre de configuración/seguridad/autenticación.

Requisitos previos

• Node.js 18+ instalado

• CLI de Gemini instalada: npm install -g @google/gemini-cli

• CLI de Gemini autenticada (recomendado: gemini → Iniciar sesión con Google) o establecer GEMINI_API_KEY

Verificaciones rápidas:

node --version
gemini --version

Inicio rápido

Paso 1: Validar el entorno

Ejecuta el asistente de configuración para verificar que la CLI de Gemini esté instalada y autenticada:

npx gemini-researcher init

Paso 2: Configurar tu cliente MCP

La configuración estándar funciona en la mayoría de las herramientas:

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

Agrégalo a tu configuración de MCP de VS Code (crea .vscode/mcp.json si es necesario):

{
  "servers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

Opción 1: Línea de comandos (recomendado)

Ámbito local (para todo el usuario)

# Add the MCP server via CLI
claude mcp add --transport stdio gemini-researcher -- npx gemini-researcher 

# Verify it was added
claude mcp list

Ámbito del proyecto

Navega al directorio de tu proyecto y luego ejecuta:

# Add the MCP server via CLI
claude mcp add --scope project --transport stdio gemini-researcher -- npx gemini-researcher

# Verify it was added
claude mcp list

Opción 2: Configuración manual

Agrégalo a .mcp.json en la raíz de tu proyecto (ámbito del proyecto):

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

O agrégalo a ~/.claude/settings.json para el ámbito local.

Después de agregar el servidor, reinicia Claude Code y usa /mcp para verificar la conexión.

Ve a Cursor Settings -> Tools & MCP -> Add a Custom MCP Server. Agrega la siguiente configuración:

{
  "mcpServers": {
    "gemini-researcher": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

Ejemplo

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Paso 3: Reiniciar tu cliente MCP

Paso 4: Probarlo

Pregúntale a tu agente: "Use gemini-researcher to analyze the project."

Herramientas

Todas las herramientas devuelven JSON estructurado (como contenido de texto MCP). Las respuestas grandes se dividen en fragmentos (~10KB por fragmento) y se almacenan en caché durante 1 hora.

Flujos de trabajo de ejemplo

Comprender una vulnerabilidad de seguridad:

Agent: Use deep_research to analyze authentication flow across @src/auth and @src/middleware, focusing on security

Explicación rápida de código:

Agent: Use quick_query to explain the login flow in @src/auth.ts, be concise

Mapear una base de código desconocida:

Agent: Use analyze_directory on src/ with depth 3 to understand the project structure

quick_query

{
  "prompt": "Explain @src/auth.ts login flow",
  "focus": "security",
  "responseStyle": "concise"
}

deep_research

{
  "prompt": "Analyze authentication across @src/auth and @src/middleware",
  "focus": "architecture",
  "citationMode": "paths_only"
}

analyze_directory

{
  "path": "src",
  "depth": 3,
  "maxFiles": 200
}

validate_paths

{
  "paths": ["src/auth.ts", "README.md"]
}

health_check

{
  "includeDiagnostics": true
}

fetch_chunk

{
  "cacheKey": "cache_abc123",
  "chunkIndex": 2
}

Docker

Una imagen de Docker multiplataforma preconstruida está disponible en Docker Hub:

# Pull the image (works on Intel/AMD and Apple Silicon)
docker pull capybearista/gemini-researcher:latest

# Run the server (mount your project and provide API key)
docker run -i --rm \
  -e GEMINI_API_KEY="your-api-key" \
  -v /path/to/your/project:/workspace \
  capybearista/gemini-researcher:latest

Para la configuración del cliente MCP con Docker:

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GEMINI_API_KEY",
        "-v", "/path/to/your/project:/workspace",
        "capybearista/gemini-researcher:latest"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Solución de problemas (problemas comunes)

• GEMINI_CLI_NOT_FOUND: Instala la CLI de Gemini: npm install -g @google/gemini-cli

• AUTH_MISSING: Ejecuta gemini y autentícate o establece GEMINI_API_KEY

• AUTH_UNKNOWN: No se pudo confirmar la autenticación (a menudo fallo de red/prueba de CLI). Verifica que gemini funcione de forma interactiva y luego vuelve a intentarlo.

• ADMIN_POLICY_MISSING: Reinstala el paquete o verifica que policies/read-only-enforcement.toml exista en el paquete instalado.

• ADMIN_POLICY_UNSUPPORTED: Actualiza la CLI de Gemini a v0.36.0+ (gemini --help debería incluir --admin-policy).

• GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0: Desactiva la aplicación estricta de la política de fallo duro al inicio. Esto debilita las garantías de fallo cerrado.

• .gitignore bloqueando archivos: Gemini respeta .gitignore por defecto; alterna fileFiltering.respectGitIgnore en gemini /settings si deseas intencionalmente que se incluyan archivos ignorados (nota: esto cambia el comportamiento de Gemini globalmente)

• PATH_NOT_ALLOWED: Todas las referencias @path deben resolverse dentro de la raíz del proyecto configurada (process.cwd() por defecto). Usa validate_paths para pre-verificar las rutas.

• QUOTA_EXCEEDED: El servidor reintenta con modelos de respaldo; si todos los niveles están agotados, reduce el alcance (usa quick_query) o espera a que se restablezca la cuota.

Contribución

Lee la Guía de contribución para comenzar.

Enlaces rápidos:

• Configuración de desarrollo

• Ejecución de pruebas

• Directrices de código

• Envío de cambios

Licencia

Licencia BSD-3-Clause