Fast Playwright MCP

Fast Playwright MCP

Este servidor MCP es un fork del de Microsoft. https://github.com/microsoft/playwright-mcp

Un servidor de Model Context Protocol (MCP) que proporciona capacidades de automatización de navegador mediante Playwright. Este servidor permite a los LLM interactuar con páginas web a través de instantáneas de accesibilidad estructuradas, evitando la necesidad de capturas de pantalla o modelos ajustados visualmente.

Características clave

• Rápido y ligero. Utiliza el árbol de accesibilidad de Playwright, no la entrada basada en píxeles.

• Amigable con LLM. No se necesitan modelos de visión, opera puramente con datos estructurados.

• Aplicación de herramientas determinista. Evita la ambigüedad común con los enfoques basados en capturas de pantalla.

Características del servidor Fast (este fork)

• Optimización de tokens. Todas las herramientas admiten un parámetro expectation para controlar el contenido de la respuesta:

  • includeCode: false - Suprime la generación de código de Playwright para reducir tokens

  • includeSnapshot: false - Omite la instantánea de la página para respuestas mínimas (reducción de tokens del 70-80%)

  • includeConsole: false - Excluye los mensajes de consola

  • includeTabs: false - Oculta la información de pestañas

• Compresión de imágenes. La herramienta de captura de pantalla admite imageOptions:

  • format: 'jpeg' - Usa JPEG en lugar de PNG

  • quality: 1-100 - Comprime imágenes (p. ej., 50 para calidad al 50%)

  • maxWidth: number - Redimensiona las imágenes al ancho máximo

• Ejecución por lotes. Usa browser_batch_execute para múltiples operaciones:

  • Reducción significativa de tokens al eliminar respuestas redundantes

  • Configuración de expectativas por paso y global

  • Manejo de errores con opciones continueOnError y stopOnFirstError

• Control de instantáneas. Limita el tamaño de la instantánea con snapshotOptions:

  • selector: string - Captura solo secciones específicas de la página (recomendado sobre maxLength)

  • format: "aria" - Formato de árbol de accesibilidad para procesamiento por LLM

• Detección de diferencias. Rastrea solo los cambios con diffOptions:

  • enabled: true - Muestra solo lo que cambió respecto al estado anterior (gran ahorro de tokens)

  • format: "minimal" - Salida de diferencias ultracompacta

  • Perfecto para monitorear cambios de estado durante la navegación o interacciones

• Sistema de diagnóstico. Herramientas avanzadas de depuración y descubrimiento de elementos:

  • browser_find_elements - Encuentra elementos usando múltiples criterios de búsqueda (texto, rol, atributos)

  • browser_diagnose - Análisis completo de la página con métricas de rendimiento y resolución de problemas

  • Manejo de errores mejorado con sugerencias de elementos alternativos

  • Análisis de estructura de la página (iframes, modales, métricas de accesibilidad)

  • Monitoreo de rendimiento con tiempo de ejecución inferior a 300 ms

• Sistema de selectores mejorado. Selección unificada de elementos con múltiples estrategias:

  • Matrices de selectores: Todas las herramientas basadas en elementos ahora admiten múltiples selectores con respaldo automático

  • 4 tipos de selectores:

    • ref: IDs de elementos generados por el sistema a partir de resultados de herramientas anteriores (máxima prioridad)

    • role: Roles ARIA con coincidencia de texto opcional (p. ej., {role: "button", text: "Submit"})

    • css: Selectores CSS estándar (p. ej., {css: "#submit-btn"})

    • text: Búsqueda de contenido de texto con filtrado de etiquetas opcional (p. ej., {text: "Click me", tag: "button"})

  • Resolución inteligente: Resolución CSS en paralelo, coincidencia de roles secuencial, respaldo automático

  • Manejo de múltiples coincidencias: Cuando varios elementos coinciden, devuelve una lista de candidatos para que el LLM seleccione

  • Inspección de HTML: Nueva herramienta browser_inspect_html para extracción inteligente de contenido con control de profundidad

Catálogo de herramientas adaptativo

La versión 0.2 usa por defecto un catálogo de inicio adaptativo de siete herramientas, reduciendo el costo fijo de contexto de MCP mientras preserva el acceso a todas las herramientas registradas.

• browser_tools busca, habilita, deshabilita, restablece y reporta el estado del catálogo.

• browser_query despacha herramientas de solo lectura validadas por esquema.

• browser_execute despacha herramientas de acción y destructivas validadas por esquema.

• Las herramientas ocultas conocidas siguen siendo directamente invocables para integraciones existentes.

• --tool-profile=full restaura el catálogo estático completo anterior.

• --tool-profile=minimal expone solo las puertas de enlace de descubrimiento y despacho.

El repositorio aplica un presupuesto de inicio serializado en CI. Ejecuta bun run benchmark:tools -- --check para inspeccionar los tamaños de perfil actuales.

Controles de seguridad e interoperabilidad

La CLI y el archivo de configuración admiten cabeceras CDP y tiempo de espera de conexión, lista blanca de hosts HTTP, límites de tamaño del directorio de salida, redacción de secretos en respuestas, tiempos de espera de acción/navegación/expectativa, un atributo de test-id personalizado y codegen: "none". El panel opcional de aplicaciones MCP sin conexión se habilita con --caps=apps.

Documentación de mantenimiento:

• Arquitectura

• Guía de migración 0.2

• Política de compatibilidad ascendente

• Matriz de compatibilidad ascendente

• Lista de verificación de lanzamiento

Requisitos

• Node.js 20 o superior

• VS Code, Cursor, Windsurf, Claude Desktop, Goose o cualquier otro cliente MCP

Primeros pasos

Primero, instala el servidor Playwright MCP con tu cliente.

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

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@tontoko/fast-playwright-mcp@latest"
      ]
    }
  }
}

Usa la CLI de Claude Code para agregar el servidor Playwright MCP:

claude mcp add fast-playwright npx @tontoko/fast-playwright-mcp@latest

Sigue la guía de instalación de MCP, usa la configuración estándar anterior.

Haz clic en el botón para instalar:

O instala manualmente:

Ve a Cursor Settings -> MCP -> Add new MCP Server. Ponle el nombre que prefieras, usa el tipo command con el comando npx @tontoko/fast-playwright-mcp@latest. También puedes verificar la configuración o agregar argumentos como comandos haciendo clic en Edit.

Sigue la guía de instalación de MCP, usa la configuración estándar anterior.

Haz clic en el botón para instalar:

O instala manualmente:

Ve a Advanced settings -> Extensions -> Add custom extension. Ponle el nombre que prefieras, usa el tipo STDIO y establece el command a npx @tontoko/fast-playwright-mcp. Haz clic en "Add Extension".

Haz clic en el botón para instalar:

O instala manualmente:

Ve a Program en la barra lateral derecha -> Install -> Edit mcp.json. Usa la configuración estándar anterior.

Sigue la documentación de servidores MCP. Por ejemplo, en ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@tontoko/fast-playwright-mcp"
      ],
      "enabled": true
    }
  }
}

Abre el panel de chat de Qodo Gen en VSCode o IntelliJ → Conectar más herramientas → + Agregar nuevo MCP → Pega la configuración estándar anterior.

Haz clic en Save.

Haz clic en el botón para instalar:

O instala manualmente:

Sigue la guía de instalación de MCP, usa la configuración estándar anterior. También puedes instalar el servidor Playwright MCP usando la CLI de VS Code:

# For VS Code
code --add-mcp '{"name":"fast-playwright","command":"npx","args":["@tontoko/fast-playwright-mcp@latest"]}'

Después de la instalación, el servidor Playwright MCP estará disponible para usarse con tu agente GitHub Copilot en VS Code.

Sigue la documentación de MCP de Windsurf. Usa la configuración estándar anterior.

Archivo de configuración

El servidor Playwright MCP se puede configurar usando un archivo JSON. Puedes especificar el archivo de configuración usando la opción de línea de comandos --config:

npx @tontoko/fast-playwright-mcp@latest --config path/to/config.json

{
  /**
   * Tool catalog profile. Adaptive is the 0.2 default; full restores the
   * pre-0.2 static catalog and minimal exposes only the discovery gateways.
   */
  toolProfile?: 'adaptive' | 'full' | 'minimal';

  browser?: {
    /**
     * The browser to use.
     */
    browserName?: 'chromium' | 'firefox' | 'webkit';

    /**
     * Keep the browser profile in memory. By default the profile is written
     * under the operating system's temporary Playwright registry directory.
     */
    isolated?: boolean;

    /**
     * Path to the user data directory. Supplying this overrides the generated
     * persistent profile location.
     */
    userDataDir?: string;

    /**
     * Launch options passed to Playwright.
     */
    launchOptions?: {
      channel?: string;
      executablePath?: string;
      headless?: boolean;
      args?: string[];
    };

    /**
     * Browser context options passed to Playwright.
     */
    contextOptions?: Record<string, unknown>;

    /**
     * Existing Chrome DevTools Protocol endpoint.
     */
    cdpEndpoint?: string;

    /**
     * HTTP headers sent when connecting to the CDP endpoint.
     */
    cdpHeaders?: Record<string, string>;

    /**
     * CDP connection timeout in milliseconds.
     */
    cdpTimeout?: number;

    /**
     * Playwright remote browser endpoint.
     */
    remoteEndpoint?: string;
  };

  server?: {
    host?: string;
    port?: number;
    allowedHosts?: string[];
  };

  capabilities?: Array<'vision' | 'pdf' | 'apps'>;
  outputDir?: string;
  outputMode?: 'file' | 'stdio';
  outputMaxSize?: number;
  secrets?: Record<string, string>;
  testIdAttribute?: string;
  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };
  codegen?: 'typescript' | 'none';
}

Perfil de usuario

Puedes ejecutar Playwright MCP con un perfil persistente, como un navegador normal (predeterminado), en contextos aislados para sesiones de prueba, o conectarte a un navegador existente usando la extensión de navegador.

Perfil persistente

Toda la información de inicio de sesión se almacenará en el perfil persistente; puedes eliminarlo entre sesiones si deseas borrar el estado sin conexión. El perfil persistente se ubicará en los siguientes directorios y puedes sobrescribirlo con el argumento --user-data-dir.

# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile

# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile

# Linux
- ~/.cache/ms-playwright/mcp-{channel}-profile

Aislado

En modo aislado, cada sesión se inicia en un perfil aislado. Cada vez que le pidas a MCP cerrar el navegador, la sesión se cierra y todo el estado de almacenamiento de esta sesión se pierde. El modo aislado se puede usar para fines de prueba para garantizar que cada sesión sea independiente.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@tontoko/fast-playwright-mcp@latest",
        "--isolated"
      ]
    }
  }
}

Extensión de navegador

La extensión de navegador Playwright MCP te permite conectarte a pestañas de navegador existentes y aprovechar tu sesión de navegador actual y el estado autenticado. Consulta el extension/README.md para obtener instrucciones de instalación y uso.

Configuración

El servidor Playwright MCP admite los siguientes argumentos. Todos son opcionales:

> npx @tontoko/fast-playwright-mcp@latest --help
  --allowed-hosts <hosts>          comma-separated list of allowed HTTP Host
                                   header values
  --allowed-origins <origins>      semicolon-separated list of origins to allow
                                   the browser to request. Default is to allow
                                   all.
  --blocked-origins <origins>      semicolon-separated list of origins to block
                                   the browser from requesting. Blocklist is
                                   evaluated before allowlist.
  --block-service-workers          block service workers
  --browser <browser>              browser or chrome channel to use: chrome,
                                   firefox, webkit, or msedge
  --caps <caps>                    comma-separated optional capabilities:
                                   vision, pdf, apps
  --cdp-endpoint <endpoint>        CDP endpoint to connect to
  --cdp-header <header...>         CDP request header in Name: Value form; may
                                   be repeated
  --cdp-timeout <timeout>          CDP connection timeout in milliseconds
  --codegen <mode>                 generated code mode: typescript or none
  --config <path>                  path to the configuration file
  --device <device>                device to emulate, for example: "iPhone 15"
  --executable-path <path>         path to the browser executable
  --headless                       run browser in headless mode, headed by
                                   default
  --host <host>                    host to bind server to. Default is localhost.
                                   Use 0.0.0.0 to bind all interfaces.
  --ignore-https-errors            ignore HTTPS errors
  --isolated                       use an in-memory isolated browser profile
  --image-responses <mode>         whether image responses are allow or omit
  --no-sandbox                     disable the Chromium sandbox for process
                                   types that normally use it
  --output-dir <path>              directory for output files
  --output-max-size <bytes>        maximum output directory size in bytes; zero
                                   disables eviction
  --port <port>                    port to listen on for HTTP transport
  --proxy-bypass <bypass>          comma-separated domains to bypass the proxy
  --proxy-server <proxy>           proxy server URL
  --save-session                   save the Playwright MCP session
  --save-trace                     save the Playwright trace
  --secrets <path>                 dotenv file containing values to redact
  --storage-state <path>           path to storage state for isolated sessions
  --test-id-attribute <attribute>  attribute used by test-id selectors
  --timeout-action <timeout>       default action timeout in milliseconds
  --timeout-expect <timeout>       default expectation timeout in milliseconds
  --timeout-navigation <timeout>   default navigation timeout in milliseconds
  --timeout-settle <timeout>       delay after browser actions before capturing
                                   the response, in milliseconds
  --tool-profile <profile>         tool catalog profile: adaptive, full, or
                                   minimal
  --user-agent <ua string>         browser user-agent string
  --user-data-dir <path>           browser user data directory
  --viewport-size <size>           viewport size as width,height, for example
                                   1280,720

Ejecutables de navegador personalizados (forks de Firefox y forks de Chrome/Chromium)

De forma predeterminada, Playwright lanza sus navegadores incluidos. Puedes usar un ejecutable de navegador personalizado (por ejemplo, un fork de Chromium con marca o un navegador basado en Firefox) especificando la ruta completa al ejecutable. Consulta CUSTOM_BROWSER_EXECUTABLES.md para obtener instrucciones detalladas y advertencias específicas de la plataforma.

• CLI: --browser <chromium|firefox|webkit> con --executable-path <full path>

• Archivo de configuración: establece browser.launchOptions.executablePath

Ejemplos:

npx @tontoko/fast-playwright-mcp@latest --browser chromium --executable-path "/opt/google/chrome/chrome"

npx @tontoko/fast-playwright-mcp@latest --browser firefox --executable-path "/opt/waterfox/waterfox"

Importante: no se garantiza la compatibilidad con navegadores de terceros. Verifica el editor y el binario antes de usarlo; el servidor ejecuta directamente la ruta proporcionada. Waterfox es solo un ejemplo ilustrativo de la familia Firefox y puede que no sea compatible con los parches del protocolo Firefox que requiere Playwright.

Servidor MCP independiente

Cuando se ejecuta un navegador con interfaz gráfica en un sistema sin pantalla o desde los procesos de trabajo de los IDE, ejecuta el servidor MCP desde un entorno con la variable DISPLAY configurada a un servidor X válido. Por ejemplo DISPLAY=:1 npx @tontoko/fast-playwright-mcp@latest --port 8931.

Docker

NOTA: La implementación de Docker solo admite chromium headless por el momento.

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

O si prefieres ejecutar el contenedor como un servicio de larga duración en lugar de dejar que el cliente MCP lo inicie, usa:

docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  --name playwright-mcp \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  cli.js --headless --browser chromium --no-sandbox --port 8931

El servidor estará disponible en el puerto 8931 y se puede acceder a él mediante cualquier cliente MCP.

Puedes construir la imagen de Docker tú mismo.

docker build -t mcr.microsoft.com/playwright/mcp .

Uso programático

import http from 'node:http';

import { createConnection } from '@tontoko/fast-playwright-mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // Creates a headless Playwright MCP server with SSE transport
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);
  // ...
});

Herramientas

• browser_batch_execute

  • Title: Ejecutar acciones del navegador por lotes

  • Description: Ejecuta múltiples acciones de navegador registradas en secuencia con una sola respuesta.

  • Parámetros:

    • steps (array): Matriz de pasos a ejecutar en secuencia. Recomendado para rellenar formularios (múltiples type→click), navegación de varios pasos, cualquier flujo de trabajo con 2 o más pasos conocidos. Ahorra un 90% de tokens en comparación con las llamadas individuales. Ejemplo: [{tool:"browser_navigate",arguments:{url:"https://example.com"}},{tool:"browser_type",arguments:{selectors:[{css:"#user"}],text:"john"}},{tool:"browser_click",arguments:{selectors:[{css:"#btn"}]}}]

    • stopOnFirstError (boolean, optional): Detener todo el lote en el primer error

    • globalExpectation (optional): Expectativa predeterminada para todos los pasos. Recomendado: {includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}. Anulación por paso con steps[].expectation

  • Solo lectura: false

• browser_click

  • Title: Realizar clic en la página web

  • Description: Realizar clic en la página web

  • Parámetros:

    • selectors (array): Matriz de selectores de elementos (máx. 5). Los selectores se prueban en orden hasta que uno tiene éxito (mecanismo de respaldo). Las coincidencias múltiples provocan un error con una lista de candidatos. Compatible con: ref (prioridad más alta), CSS (#id, .class, tag), role (button, textbox, etc.), contenido de texto. Ejemplo: [{css: "#submit"}, {role: "button", text: "Submit"}] - prueba primero el ID y recurre a role+text

    • doubleClick (boolean, optional): Doble clic si es true

    • button (string, optional): Botón del ratón (predeterminado: izquierdo)

    • expectation (object, optional): Configuración de captura del estado de la página. Usa batch_execute para múltiples clics

  • Solo lectura: false

• browser_close

  • Title: Cerrar el navegador

  • Description: Cerrar la página

  • Parámetros: Ninguno

  • Solo lectura: false

• browser_console_messages

  • Title: Obtener mensajes de consola

  • Description: Devuelve todos los mensajes de consola

  • Parámetros:

    • consoleOptions (object, optional): undefined

  • Solo lectura: true

• browser_diagnose

  • Title: Diagnosticar la página

  • Description: Analiza la complejidad de la página, el número de iframes, el tamaño del DOM, el estado de los modales, las estadísticas de elementos y las características de rendimiento.

  • Parámetros:

    • searchForElements (object, optional): Buscar elementos específicos e incluirlos en el informe

    • includePerformanceMetrics (boolean, optional): Incluir métricas de rendimiento en el informe

    • includeAccessibilityInfo (boolean, optional): Incluir información de accesibilidad

    • includeTroubleshootingSuggestions (boolean, optional): Incluir sugerencias de solución de problemas

    • diagnosticLevel (string, optional): Nivel de detalle del diagnóstico: none (sin diagnósticos), basic (solo crítico), standard (predeterminado), detailed (con métricas), full (toda la información)

    • useParallelAnalysis (boolean, optional): Usar el análisis paralelo de la Fase 2 para mejorar el rendimiento y la supervisión de recursos

    • useUnifiedSystem (boolean, optional): Usar el sistema de diagnóstico unificado de la Fase 3 con manejo de errores y supervisión mejorados

    • configOverrides (object, optional): Anulaciones de configuración en tiempo de ejecución para el sistema de diagnóstico

    • includeSystemStats (boolean, optional): Incluir estadísticas del sistema unificado e información de estado

    • expectation (object, optional): undefined

  • Solo lectura: true

• browser_drag

  • Title: Arrastrar el ratón

  • Description: Realizar arrastrar y soltar entre dos elementos

  • Parámetros:

    • startSelectors (array): Selectores del elemento de origen para iniciar el arrastre

    • endSelectors (array): Selectores del elemento de destino para finalizar el arrastre

    • expectation (object, optional): Estado de la página después del arrastre. Usa batch_execute para flujos de trabajo

  • Solo lectura: false

• browser_evaluate

  • Title: Evaluar JavaScript

  • Description: Evalúa una expresión de JavaScript en la página o en un elemento y devuelve el resultado

  • Parámetros:

    • function (string): Función JS: () => {...} o (element) => {...}

    • selectors (array, optional): Selectores de elementos opcionales. Si se proporcionan, la función recibe el elemento como parámetro

    • expectation (object, optional): Configuración del estado de la página. false para extracción de datos, true para cambios en el DOM

  • Solo lectura: false

• browser_file_upload

  • Title: Subir archivos

  • Description: Sube uno o varios archivos a la entrada de archivos

  • Parámetros:

    • paths (array): Rutas absolutas para subir (array)

    • expectation (object, optional): Configuración del estado de la página. Usa batch_execute para click→upload

  • Solo lectura: false

• browser_find

  • Title: Buscar en la instantánea de la página

  • Description: Busca en la instantánea de accesibilidad actual y devuelve un contexto compacto de coincidencias.

  • Parámetros:

    • query (string): undefined

    • regex (boolean, optional): undefined

    • caseSensitive (boolean, optional): undefined

    • maxResults (integer, optional): undefined

    • contextLines (integer, optional): undefined

    • expectation (object, optional): undefined

  • Solo lectura: true

• browser_find_elements

  • Title: Buscar elementos

  • Description: Busca elementos en la página utilizando múltiples criterios de búsqueda, como text, role, tag name o atributos. Devuelve los elementos coincidentes ordenados por confianza.

  • Parámetros:

    • searchCriteria (object): Criterios de búsqueda para encontrar elementos

    • maxResults (number, optional): Número máximo de resultados a devolver

    • includeDiagnosticInfo (boolean, optional): Incluir información de diagnóstico sobre la página

    • useUnifiedSystem (boolean, optional): Usar el sistema de diagnóstico unificado para un manejo de errores mejorado

    • enableEnhancedDiscovery (boolean, optional): Habilitar la detección mejorada de elementos con sugerencias contextuales

    • performanceThreshold (number, optional): Umbral de rendimiento en milisegundos para la detección de elementos

    • expectation (object, optional): undefined

  • Solo lectura: true

• browser_handle_dialog

  • Title: Manejar un diálogo

  • Description: Maneja un diálogo (alert, confirm, prompt)

  • Parámetros:

    • accept (boolean): Aceptar (true) o rechazar (false)

    • promptText (string, optional): Texto para los diálogos prompt

    • expectation (object, optional): Estado de la página después del diálogo. Usa batch_execute para flujos de trabajo

  • Solo lectura: false

• browser_hover

  • Title: Pasar el ratón por encima

  • Description: Pasa el ratón por encima de un elemento de la página

  • Parámetros:

    • selectors (array): Matriz de selectores de elementos (máx. 5). Los selectores se prueban en orden hasta que uno tiene éxito (mecanismo de respaldo). Las coincidencias múltiples provocan un error con una lista de candidatos. Compatible con: ref (prioridad más alta), CSS (#id, .class, tag), role (button, textbox, etc.), contenido de texto. Ejemplo: [{css: "#submit"}, {role: "button", text: "Submit"}] - prueba primero el ID y recurre a role+text

    • expectation (object, optional): Estado de la página después de pasar el ratón. Usa batch_execute para hover→click

  • Solo lectura: false

• browser_inspect_html

  • Title: Inspección de HTML

  • Description: Extrae HTML filtrado con profundidad configurable, formato de salida, límites de tamaño y truncamiento automático.

  • Parámetros:

    • selectors (array): Matriz de selectores de elementos a inspeccionar

    • depth (number, optional): Profundidad máxima de jerarquía a extraer

    • includeStyles (boolean, optional): Incluir estilos CSS calculados

    • maxSize (number, optional): Tamaño máximo en bytes (1KB-500KB)

    • format (string, optional): Formato de salida

    • includeAttributes (boolean, optional): Incluir atributos de los elementos

    • preserveWhitespace (boolean, optional): Preservar los espacios en blanco en el contenido

    • excludeSelector (string, optional): Selector CSS para excluir elementos

    • includeSuggestions (boolean, optional): Incluir sugerencias de selectores CSS en la salida

    • includeChildren (boolean, optional): Incluir elementos secundarios en la extracción

    • optimizeForLLM (boolean, optional): Optimizar el HTML extraído para el consumo de LLM

    • expectation (object, optional): Configuración del estado de la página (mínima para la inspección de HTML)

  • Solo lectura: true

• browser_navigate

  • Title: Navegar a una URL

  • Description: Navegar a una URL

  • Parámetros:

    • url (string): La URL a la que navegar

    • expectation (object, optional): Estado de la página después de la navegación

  • Solo lectura: false

• browser_navigate_back

  • Title: Volver a la página anterior

  • Description: Volver a la página anterior

  • Parámetros:

    • expectation (object, optional): Estado de la página después de volver

  • Solo lectura: false

• browser_navigate_forward

  • Title: Avanzar a la página siguiente

  • Description: Avanzar a la página siguiente

  • Parámetros:

    • expectation (object, optional): Estado de la página después de avanzar

  • Solo lectura: false

• browser_network_requests

  • Title: Listar solicitudes de red

  • Description: Devuelve las solicitudes de red desde la carga de la página con filtrado opcional

  • Parámetros:

    • urlPatterns (array, optional): Patrones de URL para filtrar (admite regex)

    • excludeUrlPatterns (array, optional): Patrones de URL a excluir (tienen prioridad)

    • statusRanges (array, optional): Rangos de códigos de estado (p. ej., [{min:200,max:299}])

    • methods (array, optional): Métodos HTTP para filtrar

    • maxRequests (number, optional): Máximo de solicitudes a devolver (predeterminado: 20)

    • newestFirst (boolean, optional): Ordenar por marca de tiempo (predeterminado: más recientes primero)

  • Solo lectura: true

• browser_press_key

  • Title: Pulsar una tecla

  • Description: Pulsa una tecla del teclado

  • Parámetros:

    • key (string): Tecla a pulsar

    • expectation (object, optional): Configuración del estado de la página. Usa batch_execute para varias teclas

  • Solo lectura: false

• browser_resize

  • Título: Redimensionar ventana del navegador

  • Descripción: Redimensionar la ventana del navegador

  • Parámetros:

    • width (número): Ancho de la ventana del navegador

    • height (número): Alto de la ventana del navegador

    • expectation (objeto, opcional): undefined

  • Solo lectura: false

• browser_select_option

  • Título: Seleccionar opción

  • Descripción: Seleccionar opción en un desplegable

  • Parámetros:

    • selectors (array): Array de selectores de elementos (máx. 5). Los selectores se prueban en orden hasta que uno tiene éxito (mecanismo de respaldo). Varias coincidencias generan un error con lista de candidatos. Admite: ref (prioridad más alta), CSS (#id, .class, tag), rol (button, textbox, etc.), contenido de texto. Ejemplo: [{css: "#submit"}, {role: "button", text: "Submit"}] - intenta primero con ID, luego con rol+texto

    • values (array): Valores a seleccionar (array)

    • expectation (objeto, opcional): Estado de la página tras la selección. Usa batch_execute para formularios

  • Solo lectura: false

• browser_snapshot

  • Título: Instantánea de la página

  • Descripción: Capturar una instantánea de accesibilidad de la página actual

  • Parámetros:

    • expectation (objeto, opcional): Configuración del estado de la página

  • Solo lectura: true

• browser_take_screenshot

  • Título: Tomar una captura de pantalla

  • Descripción: Tomar una captura de pantalla de la página actual y devolver los datos de la imagen

  • Parámetros:

    • type (cadena, opcional): Formato de imagen. Si se omite, se infiere del nombre de archivo o se usa png por defecto.

    • filename (cadena, opcional): Nombre de archivo para guardar la captura. Por defecto page-{timestamp}.{png|jpeg|webp} si no se especifica.

    • selectors (array, opcional): Selectores de elementos opcionales para capturas de elementos. Si no se proporcionan, se tomará una captura de la ventana gráfica.

    • scale (cadena, opcional): Usar píxeles CSS o píxeles de dispositivo para la captura.

    • fullPage (booleano, opcional): Si es true, captura la página completa desplazable, en lugar de la ventana gráfica visible. No se puede usar con capturas de elementos.

    • expectation (objeto, opcional): Configuración adicional del estado de la página

  • Solo lectura: false

• browser_type

  • Título: Escribir texto

  • Descripción: Escribir texto en un elemento editable

  • Parámetros:

    • selectors (array): Array de selectores de elementos (máx. 5) que admite selección por ref, rol, CSS o texto

    • text (cadena): Texto a escribir en el elemento

    • submit (booleano, opcional): Pulsar Enter después de escribir si es true

    • slowly (booleano, opcional): Escribir lentamente para autocompletar si es true

    • expectation (objeto, opcional): Configuración del estado de la página. Usa batch_execute para formularios

  • Solo lectura: false

• browser_wait_for

  • Título: Esperar

  • Descripción: Esperar a que aparezca o desaparezca un texto o a que pase un tiempo especificado

  • Parámetros:

    • time (número, opcional): Tiempo de espera en segundos

    • text (cadena, opcional): undefined

    • textGone (cadena, opcional): undefined

    • expectation (objeto, opcional): Estado de la página tras la espera

  • Solo lectura: true

• browser_tab_close

  • Título: Cerrar una pestaña

  • Descripción: Cerrar una pestaña por índice o cerrar la pestaña actual

  • Parámetros:

    • index (número, opcional): Índice de la pestaña a cerrar (omitir para la actual)

    • expectation (objeto, opcional): Estado de la página tras el cierre

  • Solo lectura: false

• browser_tab_list

  • Título: Listar pestañas

  • Descripción: Listar las pestañas del navegador con títulos y URLs

  • Parámetros:

    • expectation (objeto, opcional): Configuración del estado de la página

  • Solo lectura: true

• browser_tab_new

  • Título: Abrir una pestaña nueva

  • Descripción: Abrir una pestaña nueva

  • Parámetros:

    • url (cadena, opcional): URL para la pestaña nueva (opcional)

    • expectation (objeto, opcional): Estado de la página de la pestaña nueva

  • Solo lectura: false

• browser_tab_select

  • Título: Seleccionar una pestaña

  • Descripción: Seleccionar una pestaña por índice

  • Parámetros:

    • index (número): El índice de la pestaña a seleccionar

    • expectation (objeto, opcional): Estado de la página tras el cambio de pestaña

  • Solo lectura: false

• browser_install

  • Título: Instalar el navegador especificado en la configuración

  • Descripción: Instalar el navegador especificado en la configuración. Llama a esto si recibes un error sobre que el navegador no está instalado.

  • Parámetros: Ninguno

  • Solo lectura: false

• browser_mouse_click_xy

  • Título: Clic

  • Descripción: Clic en coordenadas específicas

  • Parámetros:

    • element (cadena): undefined

    • x (número): Coordenada X (requiere --caps=vision)

    • y (número): Coordenada Y (requiere --caps=vision)

    • expectation (objeto, opcional): Estado de la página tras el clic. Prefiere ref de elemento sobre coordenadas

  • Solo lectura: false

• browser_mouse_drag_xy

  • Título: Arrastrar el ratón

  • Descripción: Arrastrar de una coordenada a otra

  • Parámetros:

    • element (cadena): undefined

    • startX (número): X inicial (requiere --caps=vision)

    • startY (número): Y inicial (requiere --caps=vision)

    • endX (número): X final

    • endY (número): Y final

    • expectation (objeto, opcional): Estado de la página tras el arrastre. Prefiere refs de elemento sobre coordenadas

  • Solo lectura: false

• browser_mouse_move_xy

  • Título: Mover el ratón

  • Descripción: Mover el ratón a coordenadas. Requiere la capacidad de visión; prefiere interacciones basadas en elementos cuando sea posible.

  • Parámetros:

    • element (cadena): undefined

    • x (número): Coordenada X

    • y (número): Coordenada Y

    • expectation (objeto, opcional): undefined

  • Solo lectura: false

• browser_pdf_save

  • Título: Guardar como PDF

  • Descripción: Guardar la página como PDF

  • Parámetros:

    • filename (cadena, opcional): Nombre de archivo para guardar el PDF. Si no se especifica, se usa page-{timestamp}.pdf por defecto.

  • Solo lectura: false

• browser_dashboard

  • Título: Abrir el panel del navegador

  • Descripción: Abrir el panel de vista previa y selección de pestañas incluido.

  • Parámetros: Ninguno

  • Solo lectura: true

Ejemplos de optimización de tokens

El Fast Server ofrece una optimización avanzada de tokens mediante controles de expectativa y ejecución por lotes:

Control básico de expectativas

{
  "name": "browser_navigate",
  "arguments": {
    "url": "https://example.com",
    "expectation": {
      "includeSnapshot": false,
      "includeConsole": false,
      "includeTabs": false
    }
  }
}

Opciones de expectativa

• includeSnapshot (booleano, por defecto: varía según la herramienta): Incluir instantánea de accesibilidad de la página

• includeConsole (booleano, por defecto: varía según la herramienta): Incluir mensajes de la consola del navegador

• includeDownloads (booleano, por defecto: true): Incluir información de descargas

• includeTabs (booleano, por defecto: varía según la herramienta): Incluir información de pestañas

• includeCode (booleano, por defecto: true): Incluir código ejecutado en la respuesta

Opciones avanzadas de instantánea

{
  "name": "browser_click",
  "arguments": {
    "element": "Login button",
    "ref": "#login-btn",
    "expectation": {
      "includeSnapshot": true,
      "snapshotOptions": {
        "selector": ".dashboard",
        "maxLength": 1000,
        "format": "text"
      }
    }
  }
}

Opciones de filtrado de consola

{
  "name": "browser_navigate",
  "arguments": {
    "url": "https://example.com",
    "expectation": {
      "includeConsole": true,
      "consoleOptions": {
        "levels": ["error", "warn"],
        "maxMessages": 5,
        "patterns": ["^Error:"],
        "removeDuplicates": true
      }
    }
  }
}

Ejecución por lotes

Ejecutar múltiples acciones del navegador en una sola solicitud con manejo optimizado de respuestas y control de errores flexible.

Ejecución básica por lotes

{
  "name": "browser_batch_execute",
  "arguments": {
    "steps": [
      {
        "tool": "browser_navigate",
        "arguments": { "url": "https://example.com/login" }
      },
      {
        "tool": "browser_type",
        "arguments": { 
          "element": "username field", 
          "ref": "#username", 
          "text": "testuser" 
        }
      },
      {
        "tool": "browser_type",
        "arguments": { 
          "element": "password field", 
          "ref": "#password", 
          "text": "password" 
        }
      },
      {
        "tool": "browser_click",
        "arguments": { "element": "login button", "ref": "#login-btn" }
      }
    ]
  }
}

Configuración avanzada de lotes

{
  "name": "browser_batch_execute",
  "arguments": {
    "steps": [
      {
        "tool": "browser_navigate",
        "arguments": { "url": "https://example.com" },
        "expectation": { "includeSnapshot": false },
        "continueOnError": true
      },
      {
        "tool": "browser_click",
        "arguments": { "element": "button", "ref": "#submit" },
        "expectation": { 
          "includeSnapshot": true,
          "snapshotOptions": { "selector": ".result-area" }
        }
      }
    ],
    "stopOnFirstError": false,
    "globalExpectation": {
      "includeConsole": false,
      "includeTabs": false
    }
  }
}

Opciones de manejo de errores

• continueOnError (por paso): Continuar la ejecución del lote incluso si este paso falla

• stopOnFirstError (global): Detener todo el lote en el primer error

• La combinación flexible permite flujos de automatización robustos

Valores predeterminados específicos de cada herramienta

Cada herramienta tiene valores predeterminados optimizados según los patrones de uso típicos:

• Herramientas de navegación (browser_navigate): incluir contexto completo para verificación

• Herramientas interactivas (browser_click, browser_type): incluir instantánea pero registro mínimo

• Herramientas de captura/instantánea: excluir contexto adicional

• Evaluación de código: incluir salida de consola pero poca información adicional

• Operaciones de espera: salida mínima para eficiencia

Beneficios de rendimiento

• Reducción de tokens: 50-80% de reducción en el uso de tokens con expectativas optimizadas

• Ejecución más rápida: mejora de 2-5x en velocidad con ejecución por lotes

• Menor latencia: menos viajes de ida y vuelta entre cliente y servidor

• Optimización de costos: menores costos de API debido al menor consumo de tokens

Detección de diferencias en respuestas

El Fast Server incluye detección automática de diferencias para rastrear cambios de manera eficiente entre ejecuciones consecutivas de herramientas:

{
  "name": "browser_click",
  "arguments": {
    "element": "Load more button",
    "ref": "#load-more",
    "expectation": {
      "includeSnapshot": true,
      "diffOptions": {
        "enabled": true,
        "threshold": 0.1,
        "format": "unified",
        "maxDiffLines": 50,
        "context": 3
      }
    }
  }
}

Beneficios de la detección de diferencias

• Uso mínimo de tokens: solo se muestra el contenido cambiado en lugar de instantáneas completas

• Seguimiento de cambios: detecta automáticamente qué cambió después de las acciones

• Formatos flexibles: elige entre formatos de diferencias unificados, divididos o mínimos

• Caché inteligente: compara con la respuesta anterior de la misma herramienta

Cuándo usar la detección de diferencias

1. Interacciones de UI sin navegación: clics, escritura, efectos de desplazamiento

2. Actualizaciones de contenido dinámico: cargar más elementos, actualizaciones en tiempo real

3. Interacciones con formularios: rastrear cambios mientras los usuarios completan formularios

4. Monitoreo selectivo: usar con selectores CSS para rastrear áreas específicas

{
  "name": "browser_type",
  "arguments": {
    "element": "Search input",
    "ref": "#search",
    "text": "playwright",
    "expectation": {
      "includeSnapshot": true,
      "snapshotOptions": {
        "selector": "#search-results"
      },
      "diffOptions": {
        "enabled": true,
        "format": "minimal"
      }
    }
  }
}

Mejores prácticas

1. Usa ejecución por lotes para flujos de trabajo de varios pasos

2. Habilita la detección de diferencias para acciones sin navegación de página

3. Desactiva las instantáneas para pasos intermedios que no necesitan verificación

4. Usa instantáneas selectivas con selectores CSS para páginas grandes

5. Filtra los mensajes de consola solo a los niveles relevantes

6. Combina expectativas globales y específicas por paso para un control fino

7. Usa el formato de diferencias mínimo para el máximo ahorro de tokens

Ejemplos del sistema de diagnóstico

Encontrar elementos alternativos cuando los selectores fallan:

{
  "name": "browser_find_elements",
  "arguments": {
    "searchCriteria": {
      "text": "Submit",
      "role": "button"
    },
    "maxResults": 5
  }
}

Generar diagnósticos completos de la página:

{
  "name": "browser_diagnose",
  "arguments": {
    "includePerformanceMetrics": true,
    "includeAccessibilityInfo": true,
    "includeTroubleshootingSuggestions": true
  }
}

Depurar fallos de automatización con errores mejorados: Todas las herramientas proporcionan automáticamente mensajes de error mejorados con:

• Sugerencias de elementos alternativos

• Análisis de la estructura de la página

• Consejos de solución de problemas contextuales

• Información de rendimiento

Filtrado de solicitudes de red

La herramienta browser_network_requests ofrece capacidades avanzadas de filtrado para reducir el uso de tokens hasta un 80-95% al trabajar con registros de red.

Ejemplos de uso básico

// Filter API requests only
{
  "name": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["api/", "/graphql"]
  }
}

// Exclude analytics and tracking
{
  "name": "browser_network_requests", 
  "arguments": {
    "excludeUrlPatterns": ["analytics", "tracking", "ads"]
  }
}

// Success responses only
{
  "name": "browser_network_requests",
  "arguments": {
    "statusRanges": [{ "min": 200, "max": 299 }]
  }
}

// Recent errors only
{
  "name": "browser_network_requests",
  "arguments": {
    "statusRanges": [{ "min": 400, "max": 599 }],
    "maxRequests": 5,
    "newestFirst": true
  }
}

Filtrado avanzado

// Complex filtering for API debugging
{
  "name": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["/api/users", "/api/posts"],
    "excludeUrlPatterns": ["/api/health"],
    "methods": ["GET", "POST"],
    "statusRanges": [
      { "min": 200, "max": 299 },
      { "min": 400, "max": 499 }
    ],
    "maxRequests": 10,
    "newestFirst": true
  }
}

// Monitor only failed requests
{
  "name": "browser_network_requests", 
  "arguments": {
    "statusRanges": [
      { "min": 400, "max": 499 },
      { "min": 500, "max": 599 }
    ],
    "maxRequests": 3
  }
}

Soporte de patrones regex

{
  "name": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["^/api/v[0-9]+/users$"],
    "excludeUrlPatterns": ["\\.(css|js|png)$"]
  }
}

Beneficios de optimización de tokens

• Reducción masiva: 80-95% menos tokens para aplicaciones grandes

• Depuración enfocada: ver solo la actividad de red relevante

• Monitoreo de rendimiento: rastrear endpoints o patrones de error específicos

• Ahorro de costos: menores costos de API debido al menor uso de tokens

Cuándo usar el filtrado de red

1. Depuración de API: enfocarse en endpoints y métodos específicos

2. Monitoreo de errores: rastrear solo solicitudes fallidas

3. Análisis de rendimiento: monitorear endpoints lentos o problemáticos

4. Aplicaciones grandes: reducir registros de red abrumadores

5. Gestión de tokens: mantenerse dentro de los límites de contexto del LLM

Guía de migración

El código existente sigue funcionando sin cambios. Para optimizar:

1. Comienza añadiendo expectation: { includeSnapshot: false } a los pasos intermedios

2. Usa la ejecución por lotes para secuencias de 3 o más operaciones

3. Ajusta gradualmente las expectativas según tus necesidades específicas

4. Usa herramientas de diagnóstico cuando la automatización falle o necesite depuración

5. Configura --tool-profile=full antes de actualizar cuando un cliente dependa de la respuesta estática completa de tools/list.