convez.ai
PluginAutomaçãoIntermediário
LvcidPsyche

Auto Browser

LvcidPsyche/auto-browser

Navegador controlado por IA com aprovações, auth profiles e intervenção humana

Ver no GitHub
Muito bomPluginScore · de 0 a 100

Servidor MCP que fornece controle de navegador real (Playwright) para agentes de IA com intervenção humana. Inclui autenticação reutilizável, trilhas de auditoria, noVNC para takeover manual e deployment local-first via Docker Compose.

Instalação

$npx convez-ai LvcidPsyche/auto-browser

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
929
Forks
155
Acompanhando
5
Saúde
100%
Último commit
há 2 dias
Versão
v1.18.1
Issues abertas
2
Contribuidores
4

Casos de uso

  • Automação de fluxos web com validação humana
  • Testes de interface com agentes IA e rastreamento de ações
  • Scraping e coleta de dados com aprovação de operador
  • Workflows autenticados reutilizáveis com perfis salvos

Veredito

Ferramenta sólida e bem arquitetada para automação web com agentes IA. O design MCP-native, suporte a intervenção humana e recursos de segurança (aprovações, audit trails, scrubbing de PII) a diferenciam de alternativas. Melhor para quem precisa de browser automation governada e auditável.

README

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

Auto Browser

CI PyPI License: MIT MCP Server Local First Glama Open in GitHub Codespaces

Auto Browser demo

Give your AI agent a real browser, with a human in the loop.

Auto Browser is an MCP-native browser control plane for authorized workflows. It gives MCP clients, LLM agents, and operators a shared Playwright browser with human takeover, reusable auth profiles, approvals, audit trails, and local-first deployment.

Works with:

  • Claude Desktop
  • Cursor
  • any MCP client that can talk HTTP or stdio
  • direct REST callers when you want curl-first control

Why Auto Browser

  • MCP-native from day one. The browser surface is already packaged as an MCP server instead of bolted on after the fact.
  • Human takeover when the web gets brittle. noVNC keeps the same live session available when a person needs to step in.
  • Login once, reuse later. Save named auth profiles and reopen fresh sessions that are already signed in.
  • Local-first by default. Run the full stack on your own box with Docker Compose, or use Codespaces for a quick hosted demo.
  • Safety rails built in. Approvals, operator identity, PII scrubbing, Witness receipts, and policy presets are all part of the product surface.
  • Governed skill induction. Verified browser traces can become staged skill candidates with signed provenance, verifier adapters, and review-only graduation — agents that prove they can repeat themselves correctly, not just act once.

Release Highlights (v1.2.1)

  • On PyPI. pip install auto-browser-client for the SDK, pip install auto-browser-langchain for the LangChain/LangGraph/CrewAI adapters, and uvx auto-browser-mcp to run the MCP stdio bridge with zero setup. Releases publish via PyPI trusted publishing (OIDC) on tag push.

Since v1.2.0

  • Verifiable Witness receipts. Receipts were always hash-chained at write time; now you can check the chain on demand. GET /sessions/{id}/witness/verify and the read-only browser.verify_witness MCP tool walk the full chain and report the first divergent receipt if the log was altered, reordered, or truncated.
  • Sturdier session isolation. Per-session browser containers now get memory/PID/CPU caps, and the controller reaps containers orphaned by a crash at startup.
  • Fresh dependency floor. Playwright 1.60 (controller and browser-node aligned), uvicorn 0.49, and a unified, current user-agent pool replacing the stale Chrome 122-era defaults.
  • Quieter failure modes. Cleanup and capture paths that previously swallowed errors now log them with context.
  • Release gates in CI continue to enforce dependency audits, fixture evals, client tests, Python wheel builds, and the 80% controller coverage gate — now on Python 3.11 and 3.14.

See CHANGELOG.md for the full release history.

Good Fits

  • internal dashboards and admin tools
  • operator-assisted QA and browser debugging
  • login-once, reuse-later account workflows
  • brittle sites where a human may need to recover the flow
  • MCP-powered agent workflows that need a real browser, not just HTML fetches

Not the Goal

  • CAPTCHA solving
  • unauthorized scraping or account automation
  • deceptive identity shaping or bypass tooling

What You Get

Browser ControlOperator SafetyDeployment and Integration
Playwright-backed sessions with screenshots, DOM summaries, OCR excerpts, tab controls, downloads, and network inspectionapproval gates, operator identity headers, audit events, PII scrubbing, Witness receipts, and protection profilesMCP over HTTP, bundled stdio bridge, REST API, Docker Compose, Codespaces, auth profiles, and optional per-session isolation

Quickstart

git clone https://github.com/LvcidPsyche/auto-browser.git
cd auto-browser
docker compose up --build

That is enough for local development with the default settings.

Optional:

cp .env.example .env
make doctor

Run make doctor from a normal terminal with local Docker access and permission to open localhost sockets.

Open:

  • API docs: http://127.0.0.1:8000/docs
  • Operator dashboard: http://127.0.0.1:8000/dashboard
  • Visual takeover: http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale

All published ports bind to 127.0.0.1 by default.

Try It in Codespaces

Open in GitHub Codespaces

Codespaces provisions the stack automatically. The dashboard and noVNC tabs are usually ready in about 90 seconds.

First Useful Demo

The highest-signal flow in this repo is:

  1. create a session
  2. log in manually if the site needs a human
  3. save the session as a named auth profile
  4. open a new session from that auth profile
  5. continue work without reauthing

Start here:

Minimal session creation:

curl -s http://127.0.0.1:8000/sessions \
  -X POST \
  -H 'content-type: application/json' \
  -d '{"name":"demo","start_url":"https://example.com"}' | jq

Minimal observation:

curl -s http://127.0.0.1:8000/sessions/<session-id>/observe | jq

MCP Clients

Auto Browser exposes:

  • an HTTP MCP endpoint at http://127.0.0.1:8000/mcp
  • convenience endpoints at http://127.0.0.1:8000/mcp/tools and http://127.0.0.1:8000/mcp/tools/call
  • a stdio bridge: uvx auto-browser-mcp from PyPI, or scripts/mcp_stdio_bridge.py in a repo checkout

The default MCP tool profile is curated, which keeps the browser surface compact for better tool selection. If you want the full internal tool surface, set:

MCP_TOOL_PROFILE=full

Raw tool-call example:

curl -s http://127.0.0.1:8000/mcp/tools/call \
  -X POST \
  -H 'content-type: application/json' \
  -d '{
    "name":"browser.create_session",
    "arguments":{
      "name":"demo",
      "start_url":"https://example.com"
    }
  }' | jq

Client setup guides:

Convergence Harness

Auto Browser ships a Stage 0 convergence harness for Agent Skill Induction. It runs a structured task contract, records tamper-checked traces, verifies completion, and writes a staged skill candidate with signed provenance. Generated skills are staged only — promotion stays explicit and reviewed.

Read-only inspection tools (harness.list_runs, harness.get_status, harness.get_trace) are exposed in the default curated MCP tool profile so agents can introspect harness state without elevated access. Convergence runs, drift checks, candidate management, and graduation require MCP_TOOL_PROFILE=full, or can be invoked directly over REST.

Start with docs/convergence-harness.md. A deterministic local smoke is:

python -m controller.harness.run --contract evals/contracts/example_read.json --mock-final-url https://example.com --mock-final-text "Example Domain"

For MCP clients, set MCP_TOOL_PROFILE=full to expose the harness.* tools.

Security and Compliance

For a real private deployment, set at least:

APP_ENV=production
API_BEARER_TOKEN=<strong-random-secret>
REQUIRE_OPERATOR_ID=true
AUTH_STATE_ENCRYPTION_KEY=<44-char-fernet-key>
REQUIRE_AUTH_STATE_ENCRYPTION=true
REQUEST_RATE_LIMIT_ENABLED=true
METRICS_ENABLED=true
STEALTH_ENABLED=false

COMPLIANCE_TEMPLATE can apply a preconfigured posture at startup:

PresetAuth EncryptionOperator IDPII ScrubIsolationMax Session Age
strictrequiredrequiredall layersdocker_ephemeral4h
balanced-requirednetwork + textshared24h

Both presets require upload approvals and enable Witness receipts. Startup writes the applied policy to /data/compliance-manifest.json. The legacy names (HIPAA, SOC2, GDPR, PCI-DSS) still work as deprecated aliases and emit a warning at startup.

Example:

COMPLIANCE_TEMPLATE=strict docker compose up

For deployment details, hosted Witness notes, CLI auth modes, and reverse-SSH guidance, see:

Architecture at a Glance

flowchart LR
    User[Human operator] -->|watch / takeover| noVNC[noVNC]
    LLM[OpenAI / Claude / Gemini] -->|shared tools| Controller[Controller API]
    Controller -->|Playwright protocol| Browser[Browser node]
    noVNC --> Browser
    Browser --> Artifacts[(screenshots / traces / auth state)]
    Controller --> Artifacts
    Controller --> Policy[Allowlist + approval gates]

Core components:

  • browser-node/ runs Chromium, Xvfb, x11vnc, and noVNC
  • controller/ exposes the FastAPI controller, MCP transport, policy rails, and orchestration endpoints
  • data/ holds runtime artifacts, auth state, approvals, audit logs, and optional CLI caches
  • scripts/ contains local helpers for doctor, smoke tests, bridges, and release checks

Repo Guide

PathWhat It Contains
controller/controller API, MCP transport, tests, and packaging
browser-node/browser runtime and Playwright connection layer
examples/copy-paste flows and MCP client setup
integrations/langchain/LangChain, LangGraph, and CrewAI adapters
docs/architecture, deployment, hardening, and launch docs
scripts/doctor, smoke harnesses, stdio bridge, and auth helpers
ops/supporting service templates and operational assets

Common Commands

CommandPurpose
make helplist available repo commands
make lintrun Ruff checks on app, tests, and helper scripts
make testrun controller tests in Docker
make test-localrun controller tests on host Python 3.10+
make evalrun deterministic provider/profile eval scoring
make doctorrun the local readiness smoke
make release-auditrun the fuller release-validation pass
make smoke-isolationverify per-session Docker isolation
make smoke-reverse-sshverify reverse-SSH remote access

Documentation Map

If You Want To...Start Here
understand the system shapedocs/architecture.md
connect Claude Desktop or Cursordocs/mcp-clients.md
run the curl-first examplesexamples/README.md
deploy on a trusted hostdocs/deployment.md
review production constraintsdocs/production-hardening.md
run the convergence harnessdocs/convergence-harness.md
inspect release historyCHANGELOG.md
see where the project is headedROADMAP.md

Contributing

If you want to help, start with:

If Auto Browser is useful, a star helps other people find it. Sponsorship and tip options live in TIPS.md.

Ver o original no GitHub

Bom para

Relacionados