11. Herramientas integradas

Objetivo del tema

Explorar las herramientas que vienen incluidas en Gemini CLI: desde operaciones de archivos hasta ejecución de comandos, obtención de datos web, administración de contextos y extensiones mediante servidores MCP.

Conocer sus parámetros y flujos de aprobación te permitirá sacar provecho a las tareas automatizadas sin perder seguridad.

11.1 Resumen de herramientas disponibles

El core expone un conjunto de herramientas base:

Nombre Uso principal Instancias típicas
read_file / write_file / replace Leer, crear, modificar archivos de texto. Auditar código, generar snippets, aplicar diffs propuestos.
read_many_files Leer lotes de archivos con patrones y exclusiones. Resumir proyectos, analizar varios módulos a la vez, recopilar evidencias.
run_shell_command Ejecutar comandos del sistema con aprobación explícita. Consultar git status, correr tests, generar builds.
web_fetch Descargar contenido HTML/JSON binario accesible por URL. Traer documentación externa, APIs públicas, archivos adjuntos.
google_web_search Realizar búsquedas web (cuando está habilitado). Mantenerse al día, buscar referencias, explorar noticias.
save_memory Guardar notas o hallazgos en la memoria de la sesión. Registrar decisiones, checklist de tareas, resumen de reuniones.
Herramientas MCP Exponer servicios personalizados a través de servidores MCP. Integrar bases de datos, APIs internas, repositorios no locales.

11.2 Herramientas de sistema de archivos

11.2.1 read_file

  • Parámetros: path (obligatorio, absoluto), annotate (opcional, resaltar fragmentos).
  • Salida: contenido completo del archivo si es de texto. Si detecta binarios (null bytes) devuelve un aviso.
  • Uso frecuente: inspeccionar código, revisar logs, leer configuraciones.

11.2.2 write_file

  • Parámetros: path, new_content (string), confirmWrite (flag interno).
  • Comportamiento:
    • Solo crea el archivo si no existe previamente.
    • Requiere confirmación interactiva mostrando un diff.
    • Falla si el archivo ya existe para evitar sobrescrituras accidentales.

11.2.3 replace

  • Parámetros: path, old_string, new_string.
  • Funcionamiento:
    • Busca una única ocurrencia de old_string y la reemplaza.
    • Incluye un mecanismo de corrección asistido por el modelo si la coincidencia exacta no se encuentra (intenta refinar el fragmento).
    • Exige confirmación mostrando el diff final.
  • Fallas comunes: archivo inexistente, ocurrencias múltiples, old_string ambiguo.

11.2.4 read_many_files

  • Parámetros: paths (lista de rutas o patrones), include, exclude, max_files, useDefaultExcludes.
  • Características:
    • Soporta globs (**/*.ts, src/**), respetando exclusiones por defecto (.git, node_modules...).
    • Puede incluir archivos binarios permitidos (imágenes, PDFs) retornándolos en base64.
    • Ideal para pedir resúmenes de proyectos grandes o localizar archivos relevantes.
  • Precaución: limitar max_files para evitar respuestas muy voluminosas.

11.3 Ejecutar comandos con run_shell_command

Esta herramienta permite que el modelo ejecute comandos en tu entorno, por lo que está protegida por confirmaciones explícitas y restricciones.

  • Parámetros: command, timeoutSeconds, collectStdout, collectStderr.
  • Confirmación: antes de ejecutar, el CLI te muestra el comando y solicita permiso. Además, si estás en sandbox se ejecuta dentro del contenedor.
  • Restricciones:
    • Puedes excluir completamente esta herramienta o limitarlas con tools.core / tools.exclude.
    • Usa trustedFolders y sandbox para evitar que scripts maliciosos accedan a rutas no confiables.
  • Ejemplos: 
    !git status
!npm test

11.4 Acceso a la web: web_fetch y google_web_search

11.4.1 web_fetch

  • Descarga contenido de una URL (HTML, JSON, binarios permitidos).
  • Requiere que la URL esté en la lista permitida (la documentación oficial especifica dominios y límites).
  • Devuelve estructura con status_code, headers, contenido en texto y, si es binario, en base64.
  • Uso habitual: traer documentación, ejemplos de APIs, archivos adjuntos para analizarlos en la sesión.

11.4.2 google_web_search

  • Realiza búsquedas en la web (cuando el acceso está habilitado) y devuelve snippets y URLs.
  • Ideal para preguntas de actualización, noticias o referencias externas.
  • Revisa la configuración de tu organización: puede que desactiven esta herramienta por políticas internas.

11.5 Herramientas de memoria

11.5.1 save_memory

  • Permite guardar notas persistentes dentro de la sesión (similar a /memory add).
  • Parámetros: title, content, opcionalmente etiquetas.
  • Uso: registrar hallazgos, recordatorios, información que quieres reutilizar sin volver a preguntar al modelo.
  • Consulta lo guardado con /memory show y refresca el contexto con /memory refresh.

11.6 Integración con servidores MCP

Gemini CLI puede conectarse a servicios externos mediante el protocolo Model Context Protocol (MCP). Esto permite extender las herramientas disponibles más allá del entorno local.

  • Configuración: define servidores en settings.json bajo mcpServers, indicando el comando a ejecutar y argumentos.
  • Comandos CLI: 
    gemini mcp init         # Inicializa la sección en settings.json
gemini mcp add   --command "./servidor.sh" --args "--modo=demo"
  • Descubrimiento: el core prefija los nombres de herramientas con el alias del servidor (servidor__tool), evitando colisiones.
  • Casos de uso: consultar bases de datos corporativas, servicios de inventario, herramientas propietarias de código, etc.

Controla cuidadosamente los permisos del usuario que ejecuta el servidor MCP. Aunque el CLI solicite aprobaciones, el servidor puede tener acceso a recursos sensibles.

Conclusión: las herramientas integradas hacen que Gemini CLI sea un asistente completo: puede inspeccionar tu código, ejecutar comandos, traer información de la web, gestionar memoria y conectarse a servicios externos mediante MCP. Configúralas de forma consciente para equilibrar productividad y seguridad.

Retornar