Umbra

Controla tu propio Chrome con sesión iniciada desde un agente de IA, una sesión a la vez, sin entregar las cookies al agente.

Umbra son dos piezas que se emparejan con una clave compartida que generas: una extensión de Chrome MV3 que es dueña de cada llamada a la API de Chrome, y un servidor MCP local que expone una superficie de herramientas de navegador a cualquier cliente MCP. Se comunican únicamente a través de un WebSocket de loopback autenticado. Nada sale de la máquina.

Por qué existe esto

La depuración remota de un navegador le da al agente todo de golpe: cada pestaña, cada almacén de cookies, cada perfil. Umbra adopta la posición contraria. El agente recibe un grupo de pestañas que él mismo creó, las pestañas dentro de él, y nada más. Si le pides que lea una pestaña que no posee, la extensión se niega antes de que Chrome llegue a tocarse.

Dos herramientas quedan fuera de ese límite a propósito, y ambas están listadas como tal en docs/permissions.md: browser_find_tabs y browser_find_groups informan del título y la URL de pestañas que una sesión no posee, que es como se hace una cesión, y browser_cleanup_groups busca grupos de pestañas por título en todo el perfil para poder limpiar grupos dejados por una sesión que ya no existe. Dale a browser_cleanup_groups un prefijo de título que tus propios grupos no compartan, o ejecútalo con dryRun: true primero.

Ese límite es lo que lo hace utilizable contra un navegador en el que ya has iniciado sesión. El agente puede leer un panel en el que estás autenticado, rellenar un formulario, exportar un CSV y cerrar sus propias pestañas al terminar, mientras que tus otras ventanas permanecen intactas e ilegibles.

El proyecto es deliberadamente sobrio:

• Chrome real, perfil real, sesión iniciada real, elegidos por ti

• muchas sesiones de agente concurrentes en un solo navegador, cada una aislada en su propio grupo de pestañas

• propiedad de pestañas por sesión aplicada en cada acción

• sin exportación de cookies, sin extracción de tokens, sin resolución de CAPTCHA, sin fetch genérico en segundo plano

• transporte de solo loopback con handshake HMAC en ambas direcciones

Related MCP server: agent-browser-ga MCP

Instalación

La guía completa, con todas las variables que necesita una instalación normal, está en docs/install.md. La versión corta:

git clone https://github.com/RobertJLora/umbra
cd umbra/mcp-server
npm install
npm test

Las dependencias viven en mcp-server/, no en la raíz del repositorio, así que npm install en la raíz no instala nada y npm test falla hasta que el comando anterior se haya ejecutado una vez. Después de eso, npm test, npm run doctor y npm run release:check funcionan desde la raíz.

Carga extension/ sin empaquetar en chrome://extensions con el modo Desarrollador activado, abre la página de opciones de la extensión, haz clic en Generate Key y luego haz clic en Copy Environment Line y pega esa línea en la configuración de tu cliente MCP. Reinicia el cliente y las herramientas aparecerán. Haz clic en Grant Site Access en la misma página antes de la primera lectura, ya que Umbra no solicita acceso a sitios al instalarse.

La instalación es un checkout del repositorio público. Después del clonado anterior, node mcp-server/cli.js pair genera la clave, la escribe en ~/.umbra/shared-key e imprime el bloque de configuración del cliente. El checkout público no incluye plugins locales opcionales.

Superficie de herramientas

Sesiones y pestañas browser_create_tab, browser_list_tabs, browser_switch_tab, browser_close_tab, browser_freeze_session_tabs, browser_find_tabs, browser_cleanup_groups, browser_tabs_context, browser_get_session_status, browser_mark_debug_group

Adopción de pestañas ya abiertas browser_adopt_tab, browser_adopt_group

Navegación browser_navigate, browser_navigate_back, browser_navigate_forward, browser_resize

Lectura browser_get_page_content, browser_read_interactive, browser_find, browser_get_snapshot, browser_screenshot

Interacción browser_click, browser_type, browser_fill, browser_form_submit, browser_hover, browser_press, browser_shortcut, browser_scroll

Composición browser_batch, browser_navigate_wait_read, browser_wait_for_selector

Avanzado y utilidades browser_evaluate, browser_download, browser_wait_for_download, browser_reload_extension

browser_reload_extension solo existe para instalaciones de desarrollo sin empaquetar. La página de opciones tiene el mismo botón; este no pasa por el límite de herramientas, por lo que un agente siempre verá la herramienta rechazada en una instalación publicada.

La lista anterior es completa: los builds publicados no exponen más herramientas. Un checkout público puede llevarlas todas; los plugins opcionales específicos del sitio no forman parte de ningún build publicado.

Arquitectura

1. Tu cliente MCP habla con el servidor a través de stdio.

2. El servidor abre un WebSocket de loopback por sesión o a través del broker Rust.

3. La extensión es el único componente que llama a la API de Chrome; el servidor no tiene permisos de Chrome.

4. Cada sesión se limita a su propio grupo de pestañas con nombre y a las pestañas dentro de él.

Seguridad

• Sin exportación de cookies, sin extracción de tokens, sin fetch en segundo plano.

• WebSocket de loopback autenticado por clave compartida; las conexiones no autenticadas se cierran.

• Sin código de terceros en el proceso de la extensión: las dependencias del servidor son solo para Node.

• El agente solo ve las pestañas del grupo que posee, más las herramientas de descubrimiento que listan grupos, no su contenido.

Limitaciones conocidas

• Las capturas de pantalla por defecto activan la pestaña antes de capturar. silent: true evita eso adjuntando chrome.debugger a la pestaña, pero Chrome muestra su banner de automatización.

• Los clics genéricos en texto pueden fallar en controles de paginación. Usa browser_read_page y browser_click con los selectores devueltos en su lugar.

• Site access es un permiso opcional, solicitado desde la página de opciones en lugar de en la instalación. Hasta que se conceda, las lecturas de página fallarán con el error de permisos de Chrome.

• Cambiar el rango de puertos requiere ajustar el mismo valor en ambos lados.

Diseño

• extension/ — extensión de Chrome MV3, puente offscreen, service worker de fondo.

• mcp-server/ — servidor MCP stdio, listener WebSocket y lógica de sesión.

• rust-broker/ — multiplexor de sesiones de una sola extensión WebSocket.

• scripts/ — lanzador de Chrome aislado para pruebas locales.

• docs/ — documentación de instalación, arquitectura, permisos y pruebas.

Documentación relacionada

• docs/install.md — instalación y configuración completa.

• docs/architecture.md — flujo de datos y componentes.

• docs/permissions.md — justificación de cada permiso.

• docs/security.md — modelo de amenazas y superficie de ataque.

• docs/testing.md — cómo ejecutar la suite de pruebas.# Umbra

Controla tu propio Chrome desde un agente de IA, una sesión a la vez, sin compartir nada más.

Umbra son dos piezas que trabajan juntas con una clave compartida: una extensión MV3 de Chrome que posee todas las llamadas a la API de Chrome, y un servidor MCP que expone una superficie de herramientas del navegador a cualquier cliente MCP. La comunicación entre ambas se realiza a través de un WebSocket local autenticado. Nada sale de tu máquina.

Por qué existe

Depurar un navegador de forma remota expone demasiado: todas las pestañas, todas las cookies, todos los perfiles. Umbra invierte ese modelo. En lugar de dar a un agente acceso a todo el navegador, le das una sesión aislada: un perfil de Chrome temporal, propio, que se crea, se usa y se destruye. El agente solo puede ver y tocar lo que esa sesión contiene.

Cómo funciona

1. La extensión de Chrome se ejecuta en segundo plano y gestiona la creación y el ciclo de vida de las sesiones.

2. El servidor MCP se conecta a la extensión a través del WebSocket local.

3. Cada sesión tiene su propio perfil de Chrome aislado (carpeta de datos de usuario, cookies, almacenamiento).

4. Cuando la sesión termina, el perfil se elimina por completo.

Instalación

git clone https://github.com/RobertJLora/umbra
cd umbra/mcp-server
npm install
npm test

Dependencias en mcp-server/, no en la raíz, así que npm install en la raíz no instala nada y npm test falla hasta que el comando anterior se ha ejecutado una vez. Después, npm test, npm run doctor y npm run release funcionan desde la raíz.

Carga extension/ sin empaquetar en chrome://extensions, abre la página de opciones de la extensión, haz clic en Generar clave y luego en Copiar línea de entorno y pega esa línea en la configuración de tu cliente MCP. Reinicia el cliente y las herramientas aparecerán. Haz clic en Conceder acceso al sitio en la misma página antes de la primera lectura, porque Umbra no solicita acceso a sitios en el momento de la instalación.

La instalación es una copia del repositorio público. Después del clonado anterior, node mcp-server/cli.js pair genera la clave, la escribe en ~/.umbra/shared-key e imprime el bloque de configuración del cliente. La copia pública no incluye plugins locales opcionales.

Herramientas

Sesión y pestañas browser_create_session, browser_list_sessions, browser_switch_session, browser_close_session, browser_freeze_session, browser_list_tabs, browser_switch_tab, browser_close_tab

Navegación y lectura browser_navigate, browser_read_page, browser_snapshot, browser_wait_for, browser_scroll, browser_find

Interacción browser_click, browser_type, browser_submit, browser_upload, browser_download, browser_shortcut

Avanzado browser_run_javascript, browser_get_cookies, browser_set_cookie, browser_clear_cookies, browser_get_storage, browser_set_storage

Qué no hace

• No expone cookies entre sesiones: cada sesión tiene su propio almacenamiento.

• No permite que un agente acceda a sesiones de otros agentes.

• No ejecuta JavaScript arbitrario fuera del ámbito de la sesión.

• No permite que una sesión abra ventanas del navegador principal.

Limitaciones conocidas

• La primera lectura de página requiere que hagas clic en "Grant Site Access" en la página de opciones; Umbra no solicita acceso a sitios en la instalación.

• Las capturas de pantalla por defecto activan la pestaña antes de capturar. silent: true evita eso adjuntando chrome.debugger a la pestaña, lo que muestra el banner de automatización de Chrome.

• El rango de puertos por defecto es 47829-47859; la extensión lo limita a 1024-65535. Si cambias el rango, reinicia tanto la extensión como el servidor.

• Las capturas de pantalla por defecto activan la pestaña antes de capturar. silent: true evita eso adjuntando chrome.debugger a la pestaña, lo que hace que Chrome muestre su banner de automatización.

• El acceso a sitios es un permiso opcional, solicitado desde el botón Grant Site Access en la página de opciones en lugar de en la instalación. Hasta que se concede, las lecturas de página y las capturas de pantalla fallan.

Concurrencia y presión

Un solo agente puede abrir muchas pestañas, y muchos agentes pueden compartir un servidor. Umbra supervisa la presión de la sesión: número de pestañas propiedad de una sesión, recuento de listeners conectados y profundidad de la cola del agente de contenido. browser_get_session_status informa de esa presión. Cuando una sesión supera un umbral, rechaza nuevas peticiones de creación en lugar de degradar el rendimiento.

Lo que Umbra no hará

• No sincronizará ni volcará cookies.

• No resolverá CAPTCHAs.

• No expondrá almacenamiento de claves o secretos del sistema.

• No ejecutará nada que no sea JavaScript en la página activa de la sesión.

• No usará chrome.debugger a menos que se solicite explícitamente (para capturas de pantalla o red).

Limitaciones conocidas

• Las capturas de pantalla por defecto activan la pestaña. silent: true evita eso usando chrome.debugger para una única Page.captureScreenshot, lo que muestra el banner de automatización.

• Los selectores de clics son compatibles con text=, css= y xpath=; el soporte de role= aún no está completo.

• La subida de archivos requiere una ruta absoluta local y una política de permisos que lo permita.

Estructura del repositorio

• extension/ — la extensión MV3 de Chrome.

• mcp-server/ — el servidor MCP (TypeScript, sin dependencias de runtime).

• rust-broker/ — puente de loopback opcional escrito en Rust para la comunicación entre la extensión y el servidor.

• scripts/ — lanzador de Chrome aislado y comprobaciones de estado.

• docs/ — documentación de instalación, arquitectura, permisos y guía de pruebas.

Lee THREAT_MODEL.md y SECURITY_REVIEW.md antes de apuntar esto a un navegador que contenga algo que te importe.