convez.ai
MCP ServerAutomaçãoIntermediário
matanSht

WebControl

matanSht/WebControl

Automação de navegador headless para agentes LLM com API REST e MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Serviço de automação de navegador headless via REST API e MCP Server, permitindo que agentes LLM naveguem páginas, preencham formulários e cliquem em elementos. Utiliza Playwright com detecção automática de anti-bot e escalação de resiliência.

Instalação

$npx convez-ai matanSht/WebControl

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
28%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
0

Casos de uso

  • Automação de tarefas web complexas por agentes de IA
  • Preenchimento e submissão de formulários programáticos
  • Scraping e navegação com inteligência artificial
  • Testes automatizados de interfaces web

Veredito

Ferramenta robusta e bem-arquitetada para integrar controle de navegador em agentes LLM, com tratamento inteligente de anti-bot. Ideal para tarefas de automação web que exigem interação complexa com JavaScript e formulários.

README

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

WebControl

Headless browser automation service for LLM agents. Navigate pages, read structured content, click elements, fill forms — all through a REST API or MCP (Model Context Protocol) tools.

How It Works

┌──────────────────────────┐
│       LLM Agent          │
│  (Claude, custom, etc.)  │
└────────────┬─────────────┘
             │  1. navigate("https://example.com")
             │  2. receives PageContent with element refs (e1, e2, e3...)
             │  3. fill("e3", "user@example.com")
             │  4. click("e7")
             │  5. receives updated PageContent
             ▼
┌──────────────────────────┐
│      WebControl          │
│  REST API + MCP Server   │
│  (single process/port)   │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│  Playwright (headless)   │
│  Chromium browser        │
└──────────────────────────┘

The LLM reads a compact structured representation of the page (interactive elements, forms, links — not raw HTML), decides what to do, and sends an action. WebControl executes it and returns the new page state.

Quick Start

Local

# Install
python3 -m venv .venv && source .venv/bin/activate
pip install ".[dev]"
playwright install chromium

# Run
webcontrol serve

Server starts at http://localhost:8080. Try the health check:

curl http://localhost:8080/health

Docker

docker compose up --build

Usage

REST API

# Create a session
curl -X POST http://localhost:8080/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "my-task"}'
# Returns: {"id": "abc-123", "name": "my-task", ...}

# Navigate
curl -X POST http://localhost:8080/api/v1/sessions/abc-123/navigate \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
# Returns: {"success": true, "page_content": {"elements": [...], "forms": [...], ...}}

# Fill a form field (using ref from page_content)
curl -X POST http://localhost:8080/api/v1/sessions/abc-123/fill \
  -H "Content-Type: application/json" \
  -d '{"ref": "e3", "value": "hello@example.com"}'

# Click an element
curl -X POST http://localhost:8080/api/v1/sessions/abc-123/click \
  -H "Content-Type: application/json" \
  -d '{"ref": "e7"}'

# Close session when done
curl -X DELETE http://localhost:8080/api/v1/sessions/abc-123

MCP (Model Context Protocol)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "webcontrol": {
      "command": "webcontrol",
      "args": ["mcp-stdio"]
    }
  }
}

For Cursor, add to .cursor/mcp.json in your project. See mcp-configs/ for more examples.

Once configured, the LLM gets these tools: create_session, navigate, get_page_content, click, fill, select, submit, screenshot, execute_js, close_session.

Anti-Bot Resilience

Sites with anti-bot walls (Amazon, Cloudflare) often serve a block page with HTTP 200, so a naive browser thinks navigation succeeded. WebControl detects blocks and auto-escalates through robustness tiers — stealth fingerprint → human-like behavior → proxy (if configured) — and reports honestly which tier worked (blocked, tier_used, block_reason on every navigate response). If all browser tiers are blocked it raises a 409 Blocked error recommending the search tool; pass fallback_to_search: true to instead return read-only results from a pre-crawled search index (Tier S). See docs/robustness.md.

Configuration

All settings via environment variables prefixed WC_:

VariableDefaultDescription
WC_PORT8080Server port
WC_HOST0.0.0.0Bind address
WC_HEADLESStrueRun browser headless
WC_BROWSER_TYPEchromiumBrowser engine (chromium, firefox, webkit)
WC_MAX_SESSIONS10Maximum concurrent browser sessions
WC_DEFAULT_SESSION_TTL_SECONDS1800Session idle timeout (30 min)
WC_VIEWPORT_WIDTH1280Default viewport width
WC_VIEWPORT_HEIGHT720Default viewport height
WC_NAVIGATION_TIMEOUT_MS30000Navigation timeout
WC_ACTION_TIMEOUT_MS10000Action timeout (click, fill, etc.)
WC_API_KEY(empty)API key for REST auth; empty = no auth
WC_PROXY_SERVER(empty)HTTP proxy (e.g., http://proxy:8080); also enables the proxy escalation tier
WC_PROXY_USERNAME(empty)Proxy auth username
WC_PROXY_PASSWORD(empty)Proxy auth password
WC_STEALTH_ENABLEDtrueMask headless browser fingerprint (anti-bot tier 0)
WC_USER_AGENT(empty)Override the stealth default user-agent
WC_LOCALEen-USBrowser locale + Accept-Language header
WC_TIMEZONE_ID(empty)Override browser timezone
WC_NAVIGATION_ESCALATIONtrueAuto-escalate through robustness tiers when a site blocks
WC_BEHAVIORAL_JITTER_MS800Max random delay for the behavioral escalation tier
WC_SEARCH_TIER_ENABLEDfalseEnable the search-index fallback (Tier S)
WC_SEARCH_PROVIDERexaSearch provider for Tier S (exa/brave)
WC_SEARCH_API_KEY(empty)API key for the search provider
WC_NAVIGATION_RETRIES2Retry attempts for navigation
WC_ACTION_RETRIES1Retry attempts for actions
WC_RETRY_DELAY_MS500Delay between retries
WC_LOG_LEVELINFOLog level
WC_LOG_JSONfalseOutput structured JSON logs

Authentication

Set WC_API_KEY to enable API key authentication on REST endpoints:

export WC_API_KEY="your-secret-key"
webcontrol serve

Clients must include the key in requests:

curl -H "x-api-key: your-secret-key" http://localhost:8080/api/v1/sessions

The /health endpoint is always unauthenticated.

MCP stdio mode does not use HTTP auth (it runs as a local subprocess).

Development

# Run tests
pytest tests/ -v

# Run a single test
pytest tests/test_api/test_routes.py::test_navigate_and_get_content -v

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

License

MIT

Ver o original no GitHub

Bom para

Relacionados