Metadata-Version: 2.4
Name: browser-mcp-automation
Version: 1.0.0
Summary: Browser automation MCP server with triple engine (static + selenium + playwright)
Project-URL: Homepage, https://github.com/Medalcode/BrowserMCP
Project-URL: Repository, https://github.com/Medalcode/BrowserMCP
Project-URL: Bug Tracker, https://github.com/Medalcode/BrowserMCP/issues
Author-email: Jonatthan Medalla <152304407+Medalcode@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: browser-automation,mcp,model-context-protocol,playwright,selenium,web-scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: selenium>=4.30.0
Description-Content-Type: text/markdown

# BrowserMCP — Browser Automation MCP Server

[![CI](https://github.com/Medalcode/BrowserMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Medalcode/BrowserMCP/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/browser-mcp-automation.svg)](https://pypi.org/project/browser-mcp-automation/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)]()
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Servidor MCP para automatización de navegador web. Navega, extrae contenido, hace clic, rellena formularios, toma capturas de pantalla y más. Arquitectura de triple motor: Selenium (Chromium), Playwright (Chromium) y motor estático (BeautifulSoup) como fallback.

## Features / Funcionalidades

| Tool / Herramienta | Description / Descripción |
|---|---|
| `navigate` | Navega a una URL y devuelve título, URL y texto |
| `extract` | Extrae texto de elementos CSS selector |
| `click` | Hace clic en un elemento por selector CSS |
| `click_by_text` | Hace clic en un botón/enlace por su texto visible (soporta múltiples textos con \|) |
| `fill` | Rellena un campo de formulario con un valor |
| `run_script` | Ejecuta JavaScript en el navegador y devuelve el resultado |
| `screenshot` | Toma captura de pantalla (base64 PNG) |
| `forms` | Lista formularios con campos, labels y tipos |
| `links` | Lista todos los enlaces (internos/externos) |
| `scroll` | Desplaza la página (down/up/bottom/top) |
| `wait` | Espera una cantidad de milisegundos |
| `engine_info` | Muestra el motor activo (selenium/playwright/static) |

## Tech Stack

- **Python** — `>=3.11`
- **Framework**: `mcp` (FastMCP) via stdio JSON-RPC
- **Selenium Engine**: `selenium` + Chromium (headless)
- **Playwright Engine**: `playwright` + Chromium (experimental)
- **Static Engine**: `requests` + `beautifulsoup4` + `lxml` (fallback)

## Selenium Setup / Configuración

El servidor usa Chromium via Selenium en modo headless. Auto-detecta el binario de Chromium.

```bash
# Instalar dependencias
pip install mcp selenium beautifulsoup4 lxml requests httpx

# Ejecutar servidor
python server.py

# Forzar motor específico
export BROWSER_ENGINE=selenium    # Usar Selenium
export BROWSER_ENGINE=playwright  # Usar Playwright (experimental)
export BROWSER_ENGINE=static      # Usar motor estático (sin navegador)
export BROWSER_ENGINE=auto        # Intentar Selenium, fallback a static (por defecto)
```

### Chromium en Ubuntu

El servidor busca `chromium-browser`, `chromium` y la ruta de snap. Si no encuentra Chromium, usar `--headless=new`.

## Triple Engine Architecture

- **Selenium** (preferred): navegador real — soporta click, fill, screenshot, scroll, JS execution
- **Playwright** (experimental): navegador real alternativo — soporta mismas capacidades que Selenium
- **Static** (fallback): solo extracción HTML — no soporta interacciones dinámicas
- **Auto** (default): intenta Selenium, fallback automático a estático

## 🔧 Recent Improvements

- **`click_by_text` Tool** — Click buttons, links, or interactive elements by visible text content.
  Supports multiple texts separated by `|` (e.g. `Postularme|Apply|Aplicar`). Uses JavaScript
  execution to find elements by text, not CSS selectors.
- **`run_script` Tool** — Execute arbitrary JavaScript in the browser and return the result.
  Useful for debugging, inspecting page state, and complex interactions.
- **Improved Label Detection** — `get_forms()` now also finds labels in `<div for="...">` elements
  (not just `<label for="...">`), with JS-based fallback for React SPAs.
- **Multiple Submit Fix** — `click_by_text` avoids clicking the wrong submit button by matching
  text content ("Responder", "Enviar", etc.) instead of CSS selector.
- **Headless Mode** — Chrome now runs with `--headless=new` (no visible windows)
- **Random Debug Port** — `--remote-debugging-port=0` + `--remote-debugging-address=127.0.0.1` (security: no more fixed port 9222 exposed)
- **Temp Dir Cleanup** — Chrome temp directories are cleaned on server shutdown (no disk leaks)
- **XPath Injection Fix** — Label lookup escapes special characters in form IDs
- **Configurable Settings** — `CHROME_WINDOW_SIZE`, `CHROME_LANG`, `BROWSER_TEXT_MAX`, `BROWSER_JS_FILL_THRESHOLD` env vars
- **Playwright Scroll Fix** — "bottom" now scrolls to `scrollHeight` instead of fixed 10000px
- **Playwright Async Fix** — `_sync_run` uses `new_event_loop()` (no more nested event loop deadlocks)
- **Scroll Case-Insensitive** — `DOWN`/`down`/`Down` all work
- **Double Truncation Removed** — Server no longer applies a second text truncation after the engine
- **Client Uses `sys.executable`** — No more hardcoded `.venv/bin/python` path
- **Selenium in CLI** — `--engine selenium` now available in the test client
- **Dead Dependencies Removed** — `httpx` and `websocket-client` cleaned from pyproject.toml

## Project Structure

```
browser-mcp/
├── server.py                 # MCP server entry point (tools)
├── engines/
│   ├── __init__.py
│   ├── base.py               # BaseEngine, PageResult, LinkInfo, FormInfo
│   ├── selenium_engine.py    # Selenium/Chromium engine
│   ├── static.py             # Static HTML engine (requests + BS4)
│   └── playwright_engine.py  # Playwright engine (experimental)
├── client.py                 # Test client CLI
└── pyproject.toml
```
