convez.ai
MCP ServerAutomaçãoAvançado
1999AZZAR

Browser Agent MCP

1999AZZAR/browser-agent-mcp

Automação web resiliente com interação semântica e recuperação de crashes

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP de automação web profissional e modular, baseado em Playwright, com capacidades de interação semântica, gerenciamento de múltiplas abas e recuperação automática de falhas. Oferece controle em nível de rede, interceptação de requisições, persistência de sessão e estratégias inteligentes de espera para diferentes tipos de sites.

Instalação

$npx convez-ai 1999AZZAR/browser-agent-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v3.2.0
Issues abertas
4
Contribuidores
2

Casos de uso

  • Automação de testes end-to-end em aplicações web
  • Web scraping com suporte a JavaScript e SPAs
  • Preenchimento automatizado de formulários e resolução de CAPTCHAs
  • Monitoramento e captura de dados em múltiplas abas simultaneamente

Veredito

Ferramenta sólida para automação web em produção, com recursos avançados como interceptação de requisições, evasão de detecção e recuperação de crashes. Recomendada para equipes que precisam de automação robusta e configurável em aplicações web complexas.

README

A tradução para o português deste README ainda está na fila.

General Browser Agent MCP

A modular, production-ready browser automation agent implemented as a Model Context Protocol (MCP) server. Powered by Playwright, it provides a comprehensive toolset for human-like web interaction, state analysis, automated navigation, and network-level control.

Features

  • Semantic Interaction: Click elements by text (browser_click_text) and fill entire forms (browser_fill_form) with single commands.
  • Multi-Tab Management: Handle multiple sites simultaneously with tab list, switch, and creation tools.
  • Resilient Navigation: Automatic retry with configurable attempts and backoff on network failures.
  • Request Interception: Block, mock, or modify requests at the network level — stub APIs, strip ads, inject auth headers.
  • Session & Persistence: Persistent browser contexts with named session save/load for both cookies and Web Storage (localStorage/sessionStorage).
  • Crash Recovery: Browser state is automatically persisted to disk. If the browser process dies, tabs and intercept rules are restored on the next tool call — no data loss.
  • Parallel Agents: Run independent named pages within a single browser context. Create, switch, and remove agents to handle multi-page workflows without interference.
  • PDF Export: Save pages to disk as PDF with a custom output path and accurate file size reporting.
  • Smart Wait Strategy: browser_wait_for_load for sites with WebSocket/SSE connections; browser_wait_until_stable for AJAX-heavy SPAs; browser_wait_for_navigation for post-action URL/selector waits.
  • Stealth and Evasion: Anti-detection behavioral profiles (stealth vs speed), realistic user-agent spoofing, human-like mouse jitter and typing delay.
  • Robust State Capture: Extracts semantic page data including Accessibility Trees (AX Tree), interactive elements, and structural headings.
  • Data Extraction: Table-to-JSON extraction, high-fidelity PDF/HTML capture, and visible-only text extraction.
  • CAPTCHA Management: Automated detection and assisted resolution for reCAPTCHA, hCaptcha, and common challenge pages.
  • API Interception & Capture: Capture XHR/fetch responses as structured JSON — extract quiz data without DOM scraping.
  • Batch Automation: Answer entire quizzes in one tool call; batch form filling with index-based selection.
  • OCR: Extract text from code screenshots and images via Tesseract.js with preprocessing.
  • Macro Recording & Replay: Record workflows once, replay them with different parameters.
  • Parallel Execution: Run actions on multiple named pages concurrently.

Demo

See the General Browser Agent in action with Gemini CLI: Watch on YouTube

Toolset

Navigation & Tabs

ToolDescription
browser_navigateNavigate to a URL with automatic retry on failure (retries, retryDelay) — state is saved for crash recovery
browser_new_tabOpen a new tab, optionally at a URL
browser_list_tabsList all open tabs and their active status
browser_switch_tabSwitch active tab by index
browser_back / browser_forward / browser_reloadStandard history control
browser_waitWait for a fixed number of milliseconds
browser_wait_for_selectorWait until an element appears in the DOM
browser_wait_for_urlWait until the URL matches a pattern (substring or regex)
browser_wait_for_navigationSmart wait for URL change/selector after an action (replaces fixed waits)
browser_wait_until_stableWait for networkidle — use for AJAX/SPA pages
browser_wait_for_loadWait for the load or domcontentloaded event — use for WebSocket/SSE pages

Named Agents / Parallelism

ToolDescription
browser_agent_createCreate a new named agent page, or switch to an existing one
browser_agent_switchSwitch active context to a named agent
browser_agent_removeClose and remove a named agent
browser_agent_listList all active named agents and their URLs

Named agents are independent pages within the same browser. Use them to parallelize workflows — each agent keeps its own navigation state, forms, and cookies. Create one, work on it, switch to another, come back later.

Wait strategy guide:

SituationTool
Standard page navigationbrowser_wait_for_load()
SPA / AJAX-heavy contentbrowser_wait_until_stable()
Page with WebSocket or long-pollingbrowser_wait_for_load() — networkidle will hang
Specific element expectedbrowser_wait_for_selector(selector)
URL change after actionbrowser_wait_for_url(pattern)

Interaction

ToolDescription
browser_click_textClick element by visible text (smart button/link detection)
browser_fill_formPopulate multiple fields at once from a {selector: value} object
browser_clickClick by selector or x, y coordinates — includes smart retry with fallback selectors
browser_double_click / browser_right_clickPointer events
browser_hoverHover over an element or coordinates
browser_dragDrag source element to target
browser_scroll / browser_scroll_toScroll by direction or to a target
browser_smart_scrollIncremental scroll to trigger lazy-loaded content

Forms & Input

ToolDescription
browser_typeHuman-like character insertion with configurable delay
browser_clearClear an input field
browser_pressPress a keyboard key
browser_selectSelect a dropdown option by value or label
browser_select_by_indexSelect radio/checkbox by 0-based index (reliable for quiz questions)
browser_check / browser_uncheckCheckbox and radio control

Observation & Extraction

ToolDescription
browser_get_stateUnified page snapshot: URL, title, AX tree, interactive elements, screenshot — auto-saves AX tree for later diffing
browser_observeLow-token alternative to browser_get_state — returns only interactable elements with ref numbers, no screenshot. Use for pre-action planning.
browser_click_refClick an element by its ref number from the last browser_observe or browser_get_state call
browser_state_diffCompare last two AX snapshots: URL/title changes, new/removed headings, element shifts, popups, captcha
browser_screenshotTake a screenshot
browser_get_textRead text from one or all matching elements
browser_get_visible_textExtract only visible text (skips hidden, display:none, zero-size elements)
browser_get_htmlGet full page or element HTML
browser_extract_tableConvert an HTML table to structured JSON
browser_get_cookiesGet all cookies for the active page
browser_evaluateExecute JavaScript in the page context (supports return, await, and args injection)
browser_print_to_pdfSave the page as a PDF file to a specified path
browser_console_messagesReturn captured browser console messages and JS errors (last 100). Filter by type. Pass clear: true to flush.
browser_network_requestsReturn captured network requests with status and timing (last 100). Filter by URL substring or statusMin.
browser_healthCheck browser health: context alive, page responsive, latency, active URL. Use to diagnose crashes or unresponsive pages.

browser_evaluate usage:

// Return a value
script: "return document.title"

// Use await
script: "const r = await fetch('/api/status'); return r.status"

// Pass data via args (no string interpolation needed)
script: "return args.x * args.y"
args: { "x": 6, "y": 7 }

Request Interception & API Capture

ToolDescription
browser_interceptAdd an intercept rule: block, mock, or modify
browser_intercept_listList all active intercept rules
browser_clear_interceptsRemove all intercept rules
browser_intercept_apiCapture API responses matching a URL pattern as structured JSON
browser_get_captured_apisRetrieve all captured API responses with optional filter

Actions:

  • block — abort matching requests (ads, trackers, heavy assets)
  • mock — return a synthetic response with status, body, contentType, headers
  • modify — pass the request through with injected headers (auth tokens, API keys)

Examples:

# Block all images
pattern: "**/*.{png,jpg,jpeg,gif,webp}", action: "block"

# Mock an API endpoint
pattern: "https://api.example.com/users*", action: "mock"
body: { "users": [] }, status: 200

# Inject Authorization header
pattern: "https://api.example.com/*", action: "modify"
headers: { "Authorization": "Bearer <token>" }

Rules persist across page navigations until browser_clear_intercepts is called.

Session & Profile Management

ToolDescription
browser_save_sessionSave cookies (and optionally localStorage/sessionStorage) to a named file
browser_load_sessionRestore a saved session
browser_list_sessionsList saved session files with size, cookie count, and origin
browser_set_agent_profileSwitch between stealth and speed behavioral profiles
browser_handle_captchaDetect and manage CAPTCHA with optional manual hand-off
browser_solve_captcha_gridClick specific grid cells in a visual CAPTCHA
browser_switch_to_new_tabDetect and switch to a newly opened tab/popup
browser_closeTerminate the browser session and clear all state

Batch Automation

ToolDescription
browser_batch_answer_quizAnswer all quiz questions in one call — auto-detects radio/checkbox, navigates, optional submit
browser_fill_formFill multiple form fields at once (see Forms & Input)

OCR & Macros

ToolDescription
browser_ocrExtract text from screenshots/code via Tesseract.js with preprocessing (threshold, grayscale, sharpen)
browser_record_macroStart/stop/clear/export macro recordings as Playwright tests or JSON
browser_replay_macroReplay recorded macros or action arrays with speed control and dry-run
browser_parallel_executeRun actions on multiple named pages concurrently

Session storage note: Pass includeStorage: true to browser_save_session to also capture localStorage and sessionStorage. Required for sites that store auth tokens in Web Storage instead of cookies (most modern SPAs). Storage is only restored if the current page origin matches the saved origin.

Helpers

ToolDescription
browser_dismiss_popupsSuppress modals, banners, and dialogs
browser_export_stateExport current page state (URL/title/AX/cookies/storage) as a JSON snapshot for sharing or replay

Installation

Prerequisites

  • Node.js 18.x or higher
  • npm

Setup

bash install.sh

Cookie Injection (Firefox Sync)

Place a cookies.json file in the project root. The agent will automatically inject these cookies into every new session.

Configuration

Register in your MCP client config:

{
  "mcpServers": {
    "browser-agent": {
      "command": "node",
      "args": ["/absolute/path/to/browser-agent/src/server.js"],
      "env": {}
    }
  }
}

Environment Variables

VarDefaultDescription
START_URL—Page to open when the session starts.
GOAL—Task description exposed to MCP clients.
CHROMIUM_EXECUTABLE_PATHPlaywright bundledPath to a dedicated Chromium binary. If set, Playwright uses this instead of its bundled Chromium.
CHROMIUM_CHANNEL—Playwright channel hint (e.g. chromium, chrome, chrome-beta). Ignored if CHROMIUM_EXECUTABLE_PATH is set.
BROWSER_HEADLESSfalseSet to true for headless operation (CI / production).
BROWSER_LAUNCH_RETRIES3Number of retries on browser launch failure.
BROWSER_LAUNCH_BACKOFF1000Base delay (ms) between launch retries; doubled each retry.

Browser Stability

The browser layer is hardened for long-running sessions:

  • Launch retry with exponential backoff — if chromium.launchPersistentContext fails, the launcher retries up to BROWSER_LAUNCH_RETRIES times, doubling the wait between attempts.
  • Tab creation retry — if Target.createTarget or related protocol errors occur when opening a new tab, the context is reset and the call is retried.
  • Context health probe — the cached context is checked for liveness (with timeout) before reuse; dead contexts are torn down and relaunched transparently.
  • Stability flags — Chromium is launched with flags that disable background timer throttling, renderer backgrounding, BackForwardCache, and other features that commonly cause crashes in automation.
  • browser_health tool — returns { contextAlive, pageResponsive, pageCount, pageLatencyMs, activePageUrl, headless, executablePath, launchRetries } for runtime diagnostics.

Token-Efficient Interaction: Observe → Act

For repetitive or well-understood pages, skip the heavy browser_get_state screenshot and use the observe→click loop:

1. browser_observe()           # Returns elements with ref numbers, no screenshot
   → { elements: [{ ref: 1, tag: "BUTTON", text: "Sign In" }, ...] }

2. browser_click_ref(ref=1)    # Click by ref — no re-snapshot needed
   → "Clicked ref 1 (BUTTON "Sign In") at (320, 240)."

This matches the approach used by browser-use (93% context reduction) and Stagehand's act primitive.

For debugging after an interaction:

browser_console_messages(type='error')   # Any JS errors?
browser_network_requests(statusMin=400)  # Any failed API calls?

Architecture: Sense-Think-Act

The agent is designed for closed-loop automation with a hybrid screenshot strategy — screenshots are used only when the AX tree is insufficient.

Unfamiliar page      → browser_get_state()               # AX tree + elements, no image
Planning an action   → browser_observe()                  # interactable elements + refs only
Visual verification  → browser_get_state(screenshot=true) # full state + screenshot
Act by ref           → browser_click_ref(ref)             # stable, no re-snapshot needed
After action         → browser_state_diff()               # diff only, no image
Debug failures       → browser_console_messages()         # JS errors
                       browser_network_requests()         # failed API calls

When to request a screenshot:

  • Canvas-rendered UIs, game elements, charts
  • aria-hidden elements that are visually significant
  • Cross-origin iframes
  • Visual layout verification (CAPTCHA, image-heavy pages)

All other cases → AX tree is sufficient and far cheaper in tokens.

Ver o original no GitHub

Bom para

Relacionados