# browser-mcp

Servidor **MCP (stdio)** que expone herramientas de automatización de navegador sobre **Playwright (Chromium)**, con una superficie orientada a un "panel de navegador" que un agente puede controlar: pestañas, lectura de página, clics y teclado, capturas, consola y red.

Agnóstico al modelo/IDE: funciona con cualquier cliente MCP.

## Características

- Navegador visible con **perfil persistente** (las sesiones iniciadas se conservan entre ejecuciones).
- **Pestañas** y apuntado por `tabId`.
- **Lectura** de la página como árbol de accesibilidad (`read_page`) o texto plano (`get_page_text`).
- **Búsqueda** de elementos (`find`) y entrada de formularios (`form_input`).
- **Automatización** de ratón/teclado (`computer`) y ejecución de JS para depuración (`javascript_tool`).
- **Consola** y **red** de la página (`read_console_messages`, `read_network_requests`).
- **Cursor flotante** del agente (`show_cursor` / `hide_cursor`).
- **`browser_batch`** para encadenar varias llamadas en un solo viaje.

## Requisitos

- Node.js 18+
- Google Chrome instalado (el canal por defecto es `chrome`; ajustable con `BM_CHANNEL`).

## Instalación

```bash
npm install
```

## Uso como servidor MCP

Regístralo en tu cliente MCP. Ejemplo (config de OpenCode):

```jsonc
{
  "mcp": {
    "browser": {
      "type": "local",
      "command": ["node", "/ruta/a/browser-mcp/src/index.js"],
      "environment": {},
      "enabled": true
    }
  }
}
```

## Variables de entorno

| Variable | Por defecto | Descripción |
|---|---|---|
| `BM_PROFILE` | `~/.browser-mcp/profile` | Directorio del perfil persistente de Chromium. |
| `BM_CHANNEL` | `chrome` | Canal de Chromium (p. ej. `chrome`, `msedge`, o vacío para el de Playwright). |
| `BM_CDP` | — | URL CDP para conectar a un navegador ya abierto (p. ej. `http://127.0.0.1:9222`). |
| `BM_CURSOR` | activado | `0` para no mostrar el cursor flotante por defecto. |

## Herramientas

| Herramienta | Qué hace |
|---|---|
| `preview_start(url)` | Abre el panel de navegador en una pestaña nueva. Devuelve `tabId`. |
| `navigate(url)` | Navega a una URL o va `back`/`forward`. |
| `read_page(filter?, depth?, ref_id?, max_chars?)` | Devuelve la página como árbol de accesibilidad con refs `[ref_N]`. |
| `get_page_text()` | Extrae el texto visible de la página. |
| `find(query)` | Busca elementos por rol/nombre/texto. |
| `form_input(ref, value?)` | Rellena inputs/textarea/select/checkbox/contenteditable. |
| `computer(action, …)` | Ratón/teclado: screenshot, zoom, clics, hover, drag, type, key, scroll, wait. |
| `javascript_tool(code)` | Ejecuta JS en la página (solo depuración/inspección). |
| `read_console_messages(...)` | Salida de consola de la página. |
| `read_network_requests(...)` | Peticiones de red (o cuerpo de una respuesta). |
| `resize_window(...)` | Emula viewport (mobile/tablet/desktop) y esquema de color. |
| `tabs_context()` | Lista las pestañas abiertas. |
| `tabs_create()` / `tabs_select()` / `tabs_close()` | Crear / enfocar / cerrar pestañas. |
| `browser_batch(actions[])` | Encadena llamadas a herramientas en un solo viaje. |
| `show_cursor()` / `hide_cursor()` | Muestra u oculta el cursor flotante del agente. |
| `preview_stop()` | Cierra el navegador y libera recursos. |

## Licencia

MIT