<!-- trunk-ignore-all(prettier) -->

Gemini Web MCP Agent

Un agente automatizado que interactúa con la interfaz web de Gemini usando Playwright y LangGraph, diseñado para ser controlado por un LLM a través de MCP.

📋 Requisitos

• Docker y Docker Compose
• Python 3.11+ (solo para configuración inicial de autenticación)
• Cuenta de Google con acceso a Gemini
• Servidor Redis (incluido en docker-compose) para persistencia de respuestas

🚀 Inicio Rápido

1. Configurar Autenticación Automatizada

El sistema ahora soporta autenticación automatizada y persistencia de sesión robusta.

1. Configurar Credenciales (Opcional): Crea o edita el archivo .env en la raíz del proyecto y añade tus credenciales de Google si deseas que el login sea automático.

   GOOGLE_EMAIL=tu_email@gmail.com
   GOOGLE_PASSWORD=tu_password
   REDIS_URL=redis://localhost:6379/0  # Opcional, por defecto localhost para local, 'redis' para docker
   

2. Iniciar Sesión Inicial: Ejecuta el script de configuración. Esto abrirá un navegador (automáticamente si configuraste el .env, o esperando tu input si no).

   # Instalar dependencias
   pip install -r requirements.txt
   python -m playwright install chromium
   
   # Ejecutar setup
   python auth_setup.py
   

   El navegador se abrirá usando un perfil persistente guardado en profiles/default.

   • Si configuraste el .env, el script intentará loguearse por ti.
   • Si no, inicia sesión manualmente.
   • Una vez veas el chat de Gemini, cierra el navegador. El perfil se guardará automáticamente.

3. Configuración en Servidor Remoto (SSH/Headless): Si estás instalando esto en un servidor sin entorno gráfico, tienes dos opciones:

   • Opción A (Recomendada - Virtual Display): Usa el script run_auth_remote.sh que utiliza xvfb-run.

     sudo apt-get update && sudo apt-get install -y xvfb
     ./run_auth_remote.sh
     

     El script tomará capturas de pantalla periódicas en el directorio screenshots/ para que puedas ver el progreso y si se requiere interacción manual (ej. 2FA).

   • Opción B (Headless): Ejecuta el script con el flag --headless.

     python auth_setup.py --headless
     

     Nota: Esto requiere que GOOGLE_EMAIL y GOOGLE_PASSWORD estén configurados en el .env.

2. Ejecutar el Servidor MCP

# Construir y ejecutar el contenedor en segundo plano
docker compose up -d --build

# Ver los logs para confirmar que está funcionando
docker compose logs -f gemini-agent

El servidor estará disponible en http://localhost:8000.

Herramientas Disponibles

El agente expone varias herramientas para interactuar con Gemini. Para una guía detallada, consulta la Referencia de Herramientas.

1. Ejecución de Tareas: execute_gemini_tasks

Permite realizar consultas simples o invocar herramientas especiales de Gemini.

{
  "tool": "execute_gemini_tasks",
  "arguments": {
    "tasks": ["Crea un resumen de las noticias de hoy"],
    "tool": "deep_research"
  }
}

2. Control Visual: take_gemini_screenshot

Captura una imagen visual de la sesión actual para depuración o verificación.

3. Gestión de Archivos: upload_file_to_gemini

Sube archivos locales directamente al prompt de Gemini. Ideal para análisis de logs, imágenes o documentos.

4. Navegación: list_gemini_chats y switch_gemini_chat

Lista y cambia entre conversaciones existentes en tu historial.

5. Monitoreo: get_gemini_task_status y get_gemini_session_status

Consulta el progreso de tareas largas o verifica si la sesión sigue activa.

6. Gestión de Selectores: verify_gemini_selectors y update_gemini_selector

Permite verificar si los selectores CSS siguen funcionando (detectando cambios en la UI de Gemini) y actualizarlos dinámicamente sin reiniciar el servidor.

[!IMPORTANT] Al usar new_chat: false en execute_gemini_tasks, el agente NO resetea la sesión. Esto es fundamental para monitorear el progreso de deep_research o para mantener el contexto de una conversación fluida. Por defecto, new_chat es true.

---

🌐 Uso Alternativo: API HTTP (curl)

También puedes interactuar con el agente directamente a través de HTTP.

Ejecutar una Tarea

curl -X POST http://localhost:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": ["¿Cuáles son las últimas tendencias en IA?"]
  }'

Usar una Herramienta (ej. deep_research)

curl -X POST http://localhost:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": ["Investiga el impacto de la IA en la educación"],
    "tool": "deep_research"
  }'

---

🏗️ Arquitectura y Flujo Asíncrono

El agente está diseñado para manejar tareas de larga duración (como Deep Research de ~30min) sin bloquear al cliente MCP mediante un sistema de Polling Asíncrono:

1. Ejecución: Al llamar a execute_gemini_tasks, el servidor devuelve un request_id inmediato y procesa la tarea en segundo plano.
2. Persistencia: El estado y los resultados se guardan en Redis.
3. Recuperación: El cliente debe usar get_gemini_task_status periódicamente para obtener la respuesta final.

Para más detalles, consulta:

• Arquitectura del Sistema
• Funcionamiento Asíncrono

Gestión Dinámica de Selectores

El sistema incluye un módulo de Verificación de Selectores que:

1. Fuente de Verdad: Usa Redis para almacenar la configuración de selectores. Si Redis está vacío, carga desde config/selectors.json.
2. Validación: Un script (scripts/check_selectors.py) y una herramienta MCP (verify_gemini_selectors) pueden lanzar un navegador para comprobar si los elementos críticos (tools_button, send_button, etc.) son visibles.
3. Actualización en Caliente: Si un selector falla, se puede actualizar usando update_gemini_selector y el cambio se aplica inmediatamente en todas las sesiones activas, persistiendo en Redis.
4. Automatización: Un cron job diario (8:00 AM) verifica automáticamente el estado de los selectores.

---

🔧 Solución de Problemas

Error: "No puedes acceder"

Si ves este error durante auth_setup.py, el script ya incluye configuraciones anti-detección. Asegúrate de:

• Usar la última versión de Chrome.
• Tener una conexión a internet estable.
• Intentar desde una red diferente si el problema persiste.

Error: TimeoutError o el agente no funciona

Si el agente se queda esperando, especialmente después de una actualización de la web de Gemini:

1. Verifica el Perfil: Asegúrate de que la carpeta profiles/default existe. Si tienes dudas, borra la carpeta profiles y ejecuta python auth_setup.py de nuevo.
2. Revisa los Selectores: El problema más común son los selectores de CSS desactualizados. La interfaz de Gemini puede cambiar, invalidando los selectores en config/selectors.json.
   • Abre la web de Gemini en tu navegador.
   • Usa las herramientas de desarrollador (F12) para inspeccionar los elementos que fallan (ej. el botón "Deep Research", el indicador de plan, etc.).
   • Actualiza los selectores correspondientes en config/selectors.json con valores únicos y estables.
   • Reinicia el contenedor: docker compose up -d --build.

Error Común de Selector: Ambigüedad

Un error frecuente es cuando un selector coincide con múltiples elementos (violación de "strict mode"). Por ejemplo, si text="Razonamiento" coincide tanto con el botón que abre el menú como con la opción dentro del menú.

Solución: Haz el selector más específico.

• Mal (Ambiguo): [role='menuitemradio']:has-text('Razonamiento')
• Bien (Específico): menu [role='menuitemradio']:has-text('Razonamiento')

Al añadir menu como ancestro, te aseguras de que solo se seleccione el elemento dentro del menú emergente.

📁 Estructura del Proyecto

.
├── src/
│   ├── mcp_server.py           # Servidor MCP y API HTTP
│   ├── mcp_controller/
│   │   ├── actions.py          # Lógica de interacción con Playwright (POM)
│   │   ├── selectors.py        # Gestión de selectores (Redis + File)
│   │   └── selector_validator.py # Lógica de validación de elementos UI
│   └── orchestrator/
│       ├── graph.py            # Orquestación del workflow con LangGraph
│       └── state.py            # Definición del estado del agente
├── doc/
│   ├── TOOLS.md                # Referencia detallada de herramientas
│   ├── ARCHITECTURE.md         # Resumen de arquitectura y flujo
│   ├── OPTIMIZATION.md         # Mejores prácticas y optimización
│   └── NATURAL_LANGUAGE.md     # Guía de uso con lenguaje natural
├── config/
│   └── selectors.json          # Selectores CSS (la parte más frágil)
├── .env.example                # Plantilla de variables de entorno
├── scripts/
│   └── check_selectors.py      # Script de verificación para cron/manual
├── cron_setup.sh               # Instalador del cron job diario
├── auth_setup.py               # Script para generar auth_state.json
├── auth_state.json             # Sesión guardada (ignorado por Git)
├── Dockerfile                  # Definición de la imagen del contenedor
├── docker-compose.yml          # Orquestación de servicios Docker
└── requirements.txt            # Dependencias de Python

🔐 Seguridad

• auth_state.json y el directorio profiles/ contienen cookies de sesión de Google. Quien tenga esos archivos puede acceder a tu cuenta. Ambos están en .gitignore — nunca los subas al repositorio ni los compartas.
• Las credenciales (GOOGLE_EMAIL, GOOGLE_PASSWORD) van únicamente en .env (también ignorado por git). Usa .env.example como plantilla.
• Para mayor seguridad, borra profiles/ y auth_state.json y regenera la autenticación periódicamente.
• Si alguna vez commiteaste uno de estos archivos por accidente, no basta con borrarlo: reescribe el historial (p. ej. con git filter-repo) y cierra las sesiones de tu cuenta de Google (myaccount.google.com → Seguridad → Administrar dispositivos) o cambia tu contraseña para invalidar las cookies filtradas.

📄 Licencia

Este proyecto está bajo la licencia MIT — puedes usarlo, modificarlo y redistribuirlo libremente.

🛠️ Desarrollo

Ejecutar localmente (sin Docker)

# Instalar dependencias
pip install -r requirements.txt
python -m playwright install chromium

# Es necesario tener auth_state.json generado
# Ejecutar el servidor directamente
python src/mcp_server.py