EyeBrowse

---

Por que EyeBrowse?

• 🥷 Furtivo por padrão — falsificação de impressão digital no nível do mecanismo (geoip + humanize ativados por padrão, impressão digital nova a cada execução); navigator.webdriver mascarado; viewport dimensionado automaticamente para a tela falsificada. Sem remendos puppeteer-extra — a anti-detecção está compilada no navegador.
• 🤖 Feito para LLMs — as páginas são lidas como uma árvore ARIA com identificadores [ref=…]; o modelo age por referência (click/type/hover), não por CSS frágil ou pixels brutos. Iframes de origem cruzada, shadow DOM, pop-ups — tratados.
• ⚡ Chrome DevTools Protocol — cliques confiáveis e sem cursor por referência de nó (Input.dispatchMouseEvent), acessobruto a Network/Performance/Emulation, snapshots MHTML, exportação PDF e vídeo nativo — tudo acessível como ferramentas.
• 🧰 Biblioteca e MCP a partir de uma única base de código — uma API Python limpa (EyeBrowse + Session), espelhada 1:1 por um servidor MCP fino (85 ferramentas browser_*) para Claude Code e qualquer cliente MCP.
• 🪟 Nunca limitado — a API de alto nível curada não esconde o Playwright: acesse session.page / .context / .browser para qualquer coisa que ela não encapsule.
• 🔋 Tudo incluso — múltiplas sessões, rotação de proxy + identidade, solucionadores de captcha em modo de API, vídeo nativo, captura completa de HAR e extração de markdown limpo.

Escopo. EyeBrowse é um mecanismo de navegador de baixo nível — ele não contém lógica de fluxo de trabalho. Os consumidores decidem o que fazer; o mecanismo fornece o que é possível.

Conteúdo

Quickstart · Instalação · Recursos · Comparação · Biblioteca · MCP · Proxy e identidade · Extração · Gravação · Como funciona · Ressalvas · Ferramentas · Licença

Quickstart

pip install eyebrowse
# The stealth-Chromium binary downloads automatically on first launch — nothing else to run.

import asyncio
from eyebrowse import EyeBrowse

async def main():
    eb = EyeBrowse()                          # stealth defaults: geoip · humanize
    async with eb.session() as s:
        await s.navigate("https://example.com")
        print(await s.snapshot())             # ARIA tree with [ref=...] handles
        await s.click("e6")                   # act on a ref from the snapshot
    await eb.aclose()

asyncio.run(main())

…ou conecte-o ao Claude Code (ou a qualquer cliente MCP) — veja Usar via MCP.

Instalação

Do PyPI

pip install eyebrowse                 # or: uv pip install eyebrowse
# CloakBrowser fetches its Chromium binary lazily on first launch — nothing to run.
pip install "eyebrowse[extract]"     # optional: + Crawl4AI markdown extraction (heavier)

Do código-fonte (desenvolvimento)

git clone https://github.com/Evil-Bane/eyebrowse && cd eyebrowse
uv sync                              # core engine  (add --extra extract for Crawl4AI)
cp .env.example .env                 # only if you use a proxy / captcha keys

Python 3.12 (fixado em <3.13). Mecanismo: cloakbrowser>=0.3 (Chromium furtivo, Chrome/146), em playwright 1.60 e mcp 1.27.

Recursos

🥷 Furtividade	Falsificação de impressão digital do Chromium corrigido do CloakBrowser (nova --fingerprint a cada execução); geoip + humanize por padrão; webdriver mascarado; viewport correspondente à tela falsificada.
🤖 Interação com LLM	aria_snapshot(mode="ai") → árvore ARIA + identificadores [ref]; clicar / digitar / passar o mouse / selecionar / arrastar / enviar arquivo / diálogos / teclado; também mouse por coordenadas.
⚡ CDP	clique confiável sem cursor por referência, CDP bruto (Network / Performance / Emulation), captura MHTML, exportação PDF.
🪟 Frames e DOM	roteamento de iframes de origem cruzada por referência, travessia de shadow DOM, alternância de pop-ups/novas abas, evaluate dentro de qualquer frame.
🗂 Multi-sessão	sessões furtivas independentes, cada uma com seu próprio contexto / identidade / proxy.
🌐 Rede	inspecione requisições/respostas (incl. corpos de XHR/fetch e frames de WebSocket), bloqueie URLs, simule respostas, fique offline, exportação completa de HAR.
💾 Estado	cookies, localStorage e sessionStorage (CRUD), salvar/recarregar storage_state.
🪪 Rotação de identidade	impressão digital nova + perfil isolado + proxy pareado; ProxyProvider residencial plugável.
🧩 Captcha	solucionadores em modo de API plugáveis (CapSolver / 2Captcha / CapMonster / NextCaptcha) + TOTP — sem extensão de navegador.
📄 Extração	feed raw: do Crawl4AI → markdown limpo e eficiente em tokens (sem LLM, sem chaves de API).
🎥 Captura	screenshots, tracing do Playwright e vídeo nativo (.webm).
✅ Verificação e depuração	asserções, destaque de elementos, geração de localizadores, emulação de geolocalização/cabeçalhos.

Referência completa por ferramenta: docs/TOOLS.md (85 ferramentas em 18 grupos).

Como EyeBrowse se compara

	EyeBrowse	Playwright MCP	browser-use	playwright-stealth
Anti-detecção compilada no navegador	✅	❌	❌	⚠️ patches JS
Modelo de interação [ref] ARIA nativo para LLM	✅	✅	✅	❌
Inclui um servidor MCP	✅ (85 ferramentas)	✅	⚠️ parcial	❌
Uma base de código: biblioteca e MCP em Python	✅	somente MCP	somente lib	somente lib
CDP completo (cliques confiáveis · rede · MHTML · PDF · vídeo)	✅	⚠️ parcial	❌	⚠️ parcial
Captcha (modo de API) + TOTP	✅	❌	❌	❌
Rotação de proxy + identidade integrada	✅	❌	⚠️ parcial	❌
Iframes de origem cruzada · shadow DOM · pop-ups	✅	✅	⚠️ parcial	n/d

_{Nota de uso justo: cada projeto tem um nicho diferente — esta comparação é feita nos eixos que o EyeBrowse otimiza (furtividade + dirigível por LLM + uma base de código biblioteca/MCP), não como uma classificação geral.}

Usar como biblioteca

import asyncio
from eyebrowse import EyeBrowse

async def main():
    eb = EyeBrowse()                           # stealth defaults
    try:
        async with eb.session() as s:          # a stealth session (auto-closed)
            await s.navigate("https://example.com")
            print(await s.snapshot())          # ARIA tree with [ref=...] handles
            await s.click("e6")                # act on a ref
            await s.type("e8", "hello", submit=True)
            png = await s.screenshot(full_page=True)
            title = await s.page.title()        # full Playwright power when you need it
    finally:
        await eb.aclose()

asyncio.run(main())

Execute a prova inclusa: uv run python examples/direct_usage.py.

Usar via MCP

EyeBrowse inclui um servidor MCP (eyebrowse-mcp, FastMCP sobre stdio). Adicione-o a qualquer cliente MCP.

Claude Code (CLI):

claude mcp add eyebrowse -- eyebrowse-mcp

Qualquer cliente MCP (config JSON):

{
  "mcpServers": {
    "eyebrowse": {
      "command": "eyebrowse-mcp"
    }
  }
}

Em seguida, conduza o loop: browser_navigate(url) → leia o snapshot → aja por referência (browser_click / browser_type / …). Uma sessão padrão é criada automaticamente, então a maioria das ferramentas funciona diretamente. Lista completa: docs/TOOLS.md.

Proxy e identidade (opcional)

Funciona sem proxy por padrão (geoip ainda alinha idioma/fuso horário ao seu IP real). Adicione um proxy somente quando quiser:

await eb.new_session(proxy="http://user:pass@residential.example:8080")
await eb.rotate_identity(proxy="socks5://host:1080")   # fresh fingerprint + paired IP
await eb.new_session(no_proxy=True)                     # force proxyless

Defina um padrão uma única vez via EYEBROWSE_PROXY_* em .env, eb.set_static_proxy(...) ou um ProxyProvider personalizado para rotação. Via MCP: browser_new_session(proxy_url=…) / browser_new_identity(proxy_url=…) / browser_set_proxy(…).

reCAPTCHA v3 / portais de reputação são baseados em pontuação e dependem da reputação de IP + sessão — um navegador novo em um IP sinalizado falha independentemente da furtividade. Combine EyeBrowse com um proxy residencial limpo.

Extração

eb.extract() (ou browser_extract) entrega o HTML renderizado ao feed raw: do Crawl4AI e retorna markdown limpo e podado — nenhum LLM é chamado e nenhuma chave de LLM é lida; o agente consumidor faz qualquer estruturação.

md  = await eb.extract()                            # markdown string
res = await eb.extract(output_path="data/page.md")  # → {"path": ..., "chars": ...}

Gravação

Vídeo nativo — o Playwright grava a sessão inteira em um .webm, escrito ao fechar. O caminho é conhecido antecipadamente; o arquivo é finalizado quando a sessão encerra:

s = await eb.new_session(record_video=True)
# ... drive the browser ...
print(await s.video_path())          # path is known up-front; file finalizes on close
await eb.close_session(s.id)

Via MCP: browser_new_session(record_video=True) → browser_video_path. Quer um GIF para um README? Converta o .webm com ffmpeg (ffmpeg -i demo.webm demo.gif). A demonstração no topo foi capturada dessa forma — veja examples/make_demo.py.

Como funciona

CONSUMERS                         ENGINE (library: eyebrowse/)
 Claude Code  ──MCP──▶  mcp/  ──▶  EyeBrowse façade (public API)
 your code   ─ import ──────────▶   ├─ BrowserEngine (CloakBrowser / stealth Chromium)
 any MCP client                     ├─ proxy / identity rotation (pluggable)
                                    ├─ captcha solvers (pluggable, API-mode)
                                    └─ Crawl4AI (raw: feed) → clean markdown

A fachada (EyeBrowse + Session) é o produto; o adaptador MCP é um wrapper fino 1:1 sobre ela. A API de alto nível é curada e amigável para LLM — não uma reimplementação de todo o Playwright — e os objetos brutos page / context / browser estão sempre a um atributo de distância. O launcher é a única camada específica do mecanismo; todo o resto é Playwright puro.

Ressalvas

Vale a pena saber:

• evaluate é executado no mundo principal da página (globais da página acessíveis). Para substituir os globais de widget de uma página e disparar um callback do site (por exemplo, para captcha), EyeBrowse injeta um <script> para que o código seja executado no mundo da página — veja captcha/inject.py.
• A exportação de HAR fecha a sessão — o Playwright só libera o buffer de HAR quando o contexto é fechado. Use o padrão de checkpoint: browser_storage_state → browser_har_export → browser_new_session(storage_state=...). Para o HAR do Chrome rico em iniciadores (pilhas de chamadas JS), acesse o domínio Network.* via browser_cdp_send.
• O vídeo nativo é .webm — converta para GIF/MP4 com ffmpeg se precisar de outro formato.

Estrutura do projeto

eyebrowse/
  api.py            EyeBrowse façade — the single public entry point
  config.py         settings / secrets (pydantic-settings)
  snapshot.py       aria_snapshot(mode="ai") + aria-ref= resolution
  proxy.py          ProxyConfig + pluggable ProxyProvider
  identity.py       Identity + random_identity() (isolated profile dir)
  extract.py        Crawl4AI raw: feed → markdown (lazy, optional dep)
  engine/           engine.py (CloakBrowser launch) + session.py (verbs + registry)
  captcha/          solver ABC + 4 providers + DOM detect/inject
  mcp/              FastMCP server + state + tools/ (18 groups · 85 tools)
examples/direct_usage.py   library proof (no MCP)
examples/make_demo.py      the native-video demo above
docs/TOOLS.md              full tool reference

Notas de build, justificativa do pin de versão e comportamento verificado do mecanismo estão em CLAUDE.md.

Uso responsável

EyeBrowse conduz um navegador real com recursos de anti-detecção. Use-o somente contra sites que você possui ou está explicitamente autorizado a automatizar, e dentro de seus termos e da lei aplicável.

Licença

MIT © Evil-Bane