CrawlForge MCP v6.6.0: sesiones de navegador que siguen abiertas

Un agente nunca ha visto la página en la que está a punto de hacer clic. scrape_with_actions le pide igualmente que nombre hasta 20 acciones — escribe en #user, haz clic en .btn-primary, espera 1000 ms — y después cierra el navegador cuando la llamada termina. Si la conjetura falla en el paso 3, la cadena se detiene ahí, el resultado vuelve con success: false y los 5 credits ya están gastados.

CrawlForge MCP v6.6.0 arregla el bucle, no la conjetura. La nueva herramienta browser_session — la número 31 — mantiene viva una página real de navegador entre llamadas, así que un agente puede abrir una página, mirarla, actuar sobre lo que vio, mirar otra vez y leer el resultado. Mirar es la parte que importa, y tiene nombre: snapshot.

Tabla de contenidos

• Qué incluye v6.6.0
• Por qué una cadena de un solo disparo va a ciegas
• Snapshot: el agente mira antes de actuar
• El bucle de sesión, de principio a fin
• Los refs fallan en voz alta, nunca en silencio
• Snapshot también llegó a scrape_with_actions
• Cuánto cuesta una sesión
• Límites, dichos con claridad
• Una sesión desde la CLI
• Cuándo usar cada uno
• Cómo actualizar

Qué incluye v6.6.0

v6.6.0 es una herramienta y una primitiva:

• browser_session — una sola herramienta con un enum operation: open, snapshot, act, read, screenshot, close, list. La página, sus cookies y su sesión iniciada sobreviven entre llamadas hasta que la sesión expira.
• snapshot — un árbol de estilo accesibilidad de la página viva en el que cada elemento interactivo lleva un ref estable (@e1, @e2). El selector de cualquier acción acepta un ref en lugar de un selector CSS.
• El número de herramientas pasa de 30 a 31, en ambas superficies: MCP y la API REST.
• Junto a ella llegan una skill de agente crawlforge-browser-sessions y un comando de CLI crawlforge browser.

No se renombró nada y ninguna herramienta existente cambió de forma o de precio, así que es una actualización directa.

Por qué una cadena de un solo disparo va a ciegas

scrape_with_actions es una buena herramienta con un límite estructural: el array de acciones se escribe antes de que se haya cargado nada. El agente elige #login-email o input[name="email"] o .form-field:first-child recordando cómo suelen ser los formularios de acceso, no mirando este formulario.

Cuando una de esas conjeturas falla, ActionExecutor detiene la cadena — continueOnError vale false por defecto — y la herramienta devuelve un resultado con success: false y el error en vez de lanzar una excepción. La facturación sigue a la llamada, no al veredicto, así que los 5 credits se gastan en una cadena que llegó a la tercera acción.

El problema no es el coste. Es que el siguiente movimiento del agente es volver a adivinar, sin más información que la que tenía la primera vez. Una herramienta de un solo disparo no puede decirle qué contiene la página, porque el navegador ya no existe cuando llega el resultado.

Snapshot: el agente mira antes de actuar

snapshot recorre el DOM vivo y emite una línea indentada por cada nodo relevante, siguiendo el modelo del árbol de accesibilidad: rol, nombre accesible y, para los nodos interactivos, un ref:

[document] "Sign in"
  @e1 [textbox] "Email"
  @e2 [textbox] "Password"
  @e3 [button] "Sign in"
  [link] "Forgot password?"

Dos propiedades lo hacen útil y no decorativo. Los nodos estructurales (encabezados, landmarks, formularios) aparecen como contexto pero no reciben ref, porque no son objetivos. Y cada ref está respaldado por un atributo data-cf-ref estampado en el elemento durante el recorrido, así que @e1 se resuelve como un selector [data-cf-ref="e1"] corriente y funciona con todas las rutas de acción existentes — incluido el código de comportamiento humano del navegador stealth, que recibe una cadena de selector en crudo.

Escribimos el recorrido nosotros en vez de envolver ariaSnapshot() de Playwright, que emite YAML sin ningún ref de elemento, ni page._snapshotForAI(), que es API privada de la que no vamos a depender.

interactive_only vale true por defecto y max_nodes vale 200, así que la página de una aplicación con 4.000 elementos vuelve como una lista que un agente puede leer de verdad.

El bucle de sesión, de principio a fin

Aquí tienes un inicio de sesión y una lectura, con el paquete crawlforge-sdk. Cinco llamadas, una página de navegador, un solo juego de cookies.

// npm install crawlforge-sdk
import { CrawlForge } from 'crawlforge-sdk';

const client = new CrawlForge({ apiKey: process.env.CRAWLFORGE_API_KEY });

// 1. Open the session (3 credits). One API key may hold one session at a time.
const opened = await client.browserSession({
  operation: 'open',
  url: 'https://app.example.com/login',
  ttl: 600
});

const { sessionId } = opened.data as { sessionId: string };

try {
  // 2. Look before acting (1 credit). Every interactive element comes back
  //    with a stable ref, so the next call targets what is actually there.
  const seen = await client.browserSession({ operation: 'snapshot', session_id: sessionId });
  console.log((seen.data as { snapshot: { tree: string } }).snapshot.tree);

  // 3. Act on those refs in a separate call (1 credit) — same page, same cookies.
  await client.browserSession({
    operation: 'act',
    session_id: sessionId,
    actions: [
      { type: 'type', selector: '@e1', text: 'user@example.com' },
      { type: 'type', selector: '@e2', text: 'secret123' },
      { type: 'click', selector: '@e3' },
      { type: 'wait', duration: 1000 }
    ]
  });

  // 4. Read the page the login landed on (2 credits) — the live DOM with the
  //    session's cookies, not a fresh fetch of the URL.
  const page = await client.browserSession({
    operation: 'read',
    session_id: sessionId,
    formats: ['markdown']
  });
  const { title, content } = page.data as { title: string; content: { markdown: string } };
  console.log(title, content.markdown.length);
} finally {
  // 5. Close it rather than waiting for the TTL (1 credit).
  await client.browserSession({ operation: 'close', session_id: sessionId });
}

Merece la pena detenerse en el paso 4. read extrae de la página que la sesión está sosteniendo, no de una nueva petición a su URL — esa petición llegaría sin las cookies y antes de todo lo que la sesión ya ha pulsado, que es justo la razón de tener una. Los formatos son markdown, html, text y json, y puedes pedir varios en una sola llamada.

Los refs fallan en voz alta, nunca en silencio

Los refs quedan invalidados por la navegación. Eso no es una advertencia, es el diseño: un ref que sobreviviera a un cambio de página apuntaría a lo que quedara tercero en el documento nuevo, y el agente haría clic sin saberlo.

Por eso la tabla de refs vive en un WeakMap indexado por página y se borra en cada navegación del frame principal. Actúa sobre un ref caducado y obtienes el motivo y la solución, no un misterio:

Stale element ref @e3: the page navigated since the last snapshot —
take a new snapshot before acting on refs.

Un ref desconocido es igual de explícito: "Unknown element ref @e9: the current snapshot has 4 refs (@e1-@e4) — take a new snapshot." Un agente puede actuar sobre cualquiera de los dos mensajes por su cuenta. Un clic equivocado en silencio es el fallo que gastamos el presupuesto de diseño en evitar.

Snapshot también llegó a scrape_with_actions

No necesitas una sesión para mirar primero. snapshot llegó también como tipo de acción dentro de scrape_with_actions, así que una cadena de un solo disparo puede observar y luego actuar sobre los refs que produjo su propio snapshot, dentro de la misma llamada de 5 credits:

{
  "url": "https://news.ycombinator.com/login",
  "actions": [
    { "type": "snapshot" },
    { "type": "type", "selector": "@e1", "text": "reader" },
    { "type": "click", "selector": "@e3" }
  ]
}

Eso cubre el caso habitual en el que el agente necesita ver la página pero todo el flujo sigue cabiendo en una llamada. Recurre a una sesión cuando el flujo no cabe: cuando una decisión posterior depende de lo que devolvió un paso anterior, o cuando un inicio de sesión debe mantenerse a lo largo de varias lecturas.

Cuánto cuesta una sesión

browser_session cobra por operación, porque una sesión son muchas llamadas y un precio plano cobraría el techo por cada una de las baratas:

El flujo de acceso de arriba son 8 credits: 3 + 1 + 1 + 2 + 1. Añade el nuevo snapshot que pide la navegación posterior al login y son 9. Una llamada a scrape_with_actions que intente lo mismo cuesta 5 — y, sobre un formulario que nunca ha visto, es mucho más probable que gaste esos 5 en nada.

La referencia de la herramienta publica browser_session con una tarifa plana de 3 credits. Ese es el precio de open, y es un techo más que una tarifa: la ruta REST reserva 3 antes de poder leer el cuerpo de la petición y después descuenta el coste real de la operación cuando la llamada tiene éxito. Nunca se te cobra más que el número publicado, y normalmente menos. Los credits salen del mismo saldo que el de cualquier otra herramienta — mira los planes y paquetes de credits.

Límites, dichos con claridad

Una sesión ocupa infraestructura real, así que los límites también son reales:

• Expira. ttl vale 600 segundos desde open por defecto (rango 30-3600) y activity_ttl 300 segundos desde el último uso (rango 10-3600), lo que ocurra antes. Cierra las sesiones cuando termines en vez de dejar que caduquen.
• Una cada vez en la API alojada. Una API key de REST puede mantener una sesión; las instalaciones por stdio y autoalojadas conservan el valor por defecto de tres. Es aritmética, no prudencia: un solo cliente con tres sesiones ocuparía toda la capacidad de sesiones alojadas.
• Nada de executeJavaScript en la superficie alojada. Un script arbitrario en un navegador de nuestra infraestructura es un acto distinto del mismo script en tu portátil, así que se rechaza sobre un transporte remoto. Usa click, type, select y press, o ejecuta el MCP server localmente por stdio.
• Cada navegación se vuelve a comprobar. Una sesión de larga duración es una primitiva de navegación repetible, así que cada navigate dentro de la sesión vuelve a pasar el guardia SSRF, la lista de hosts bloqueados y la comprobación de robots.txt. Abrir una sesión no compra un salto sin revisar.
• Los inicios de sesión no persisten entre sesiones. Un login se mantiene dentro de una sesión. No hay perfiles guardados que pasen de una sesión a la siguiente.

Una sesión desde la CLI

La CLI ejecuta una sesión completa por invocación — open, snapshot, tus pasos, read, close — porque una sesión vive en el proceso que la abrió y un proceso de CLI termina cuando termina el comando:

# steps.json: [{"operation":"act","actions":[{"type":"click","selector":"@e2"}]}]
crawlforge browser https://news.ycombinator.com \
  --steps steps.json \
  --read --format markdown

Cuando una sesión tiene que sobrevivir a la llamada que la abrió, usa la herramienta MCP o la API REST. No existe un crawlforge browser open que devuelva un id: la página detrás de ese id moriría al salir.

Cuándo usar cada uno

Ninguna sustituye a scrape (2 credits), que sigue siendo la respuesta correcta para una página que se renderiza sin tocarla. Y browser_session es ideal para equipos cuyos objetivos son aplicaciones y no documentos: paneles detrás de un login, asistentes de varios pasos, resultados de búsqueda filtrados que solo existen después de cuatro clics.

Cómo actualizar

npm install -g crawlforge-mcp-server@latest
crawlforge --version   # 6.6.0

Si tu cliente MCP arranca el servidor con npx, cogerá la v6.6.0 en el siguiente reinicio. Ninguna herramienta existente cambia de esquema, de forma de salida ni de coste. El historial completo de versiones está en el changelog.

¿Quieres un agente que mire antes de hacer clic? Empieza gratis con 1.000 credits — 125 sesiones completas de login y lectura — y lee la referencia de la API de browser_session para conocer cada operación, parámetro y campo de respuesta.