Arthur

Runtime headless de Chromium ligero y servidor MCP para agentes de IA

¿Qué es Arthur?

Arthur es un runtime de navegador headless de un solo comando y un servidor de Model Context Protocol (MCP) para agentes de IA.

Se conecta directamente a Chromium a través de WebSockets del Chrome DevTools Protocol (CDP) sin necesidad de extensiones de navegador, pantallas virtuales (X11/VNC) ni controladores de automatización pesados. Un solo comando lanza el servidor MCP, inicia un proceso headless de Chromium aislado y proporciona a tu agente de IA control procedural completo del navegador.

Agent / MCP Client
       │
       ▼  execute_python(code)
FastMCP Server (stdio / Streamable HTTP)
       │
       ▼
Python REPL Session (stateful memory & auto-snapshots)
       │
       ▼
Arthur Browser API (synchronous facade)
       │
       ▼  CDP WebSockets
Headless Chromium (--headless=new)

Related MCP server: openmcp

Inicio rápido

No necesitas clonar el repositorio ni instalar dependencias manualmente. Arthur se ejecuta al instante mediante uvx.

1. Escritorio local (Claude Desktop, Cursor, Goose)

Añade Arthur a tu archivo de configuración de MCP (p. ej. claude_desktop_config.json):

{
  "mcpServers": {
    "arthur": {
      "command": "uvx",
      "args": ["arthur-runtime", "mcp"]
    }
  }
}

Cuando tu agente de IA llama al navegador, Arthur detecta automáticamente Chrome/Chromium local, inicia el navegador headless, ejecuta las acciones y limpia al terminar.

2. Contenedor Docker (HTTP Streamable autocontenido)

Ejecuta Arthur en un contenedor Debian Slim ligero y autocontenido con Chromium headless, gestión de procesos tini como PID 1 y soporte nativo multi-arquitectura (amd64 / arm64):

Ejecutar con Docker:

docker run -d \
  --name arthur \
  -p 8000:8000 \
  --shm-size=1g \
  --restart unless-stopped \
  sh7vansh/arthur:latest

O ejecutar con Docker Compose:

docker compose up -d

Conecta tu cliente MCP:

{
  "mcpServers": {
    "arthur": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

3. Servidor remoto / nube (Python directo mediante uvx)

Para ejecutar Arthur en una VM remota, VPS o servidor en la nube sin Docker:

Inicia el servidor:

uvx arthur-runtime mcp --transport streamable-http --stateless --host 0.0.0.0 --port 8000

Conecta tu cliente MCP:

{
  "mcpServers": {
    "arthur": {
      "url": "http://YOUR_SERVER_IP:8000/mcp"
    }
  }
}

El HTTP Streamable sin estado es resistente a las caídas de red y funciona perfectamente detrás de Nginx, Cloudflare Tunnels y AWS ALBs, manteniendo las pestañas del navegador y las variables de Python en la memoria del servidor.

4. Shell de terminal interactiva (para pruebas)

Prueba el navegador directamente desde tu terminal:

uvx arthur-runtime repl

Arthur Interactive REPL (Type 'exit()' or press Ctrl+D to exit)
Global 'browser' instance is available.
arthur> browser.navigate('https://example.com')
arthur> print(browser.snapshot())
arthur> browser.click(1)

Cómo funciona

Arthur gestiona todo el ciclo de vida del navegador en un único proceso autocontenido:

1. Detección automática: Localiza Chrome, Chromium, Brave o Edge instalados en Linux, macOS o Windows.

2. Sandbox efímero: Inicia Chromium con --headless=new y un directorio temporal aislado de datos de usuario.

3. WebSockets CDP: Se comunica directamente a través de WebSockets locales para la selección de elementos de baja latencia y la simulación de entrada.

4. Cierre automático: Apaga correctamente el subproceso de Chromium y purga los archivos temporales cuando finaliza la sesión.

Referencia de la API de Python

Cuando tu agente de IA usa la herramienta execute_python, la instancia síncrona browser se inyecta previamente:

# Navigation & Page State
browser.navigate("https://example.com", timeout=30.0)
print(browser.snapshot())                # Semantic Ref-ID outline ([#1], [#2])
print(browser.url, browser.title)

# Interactions (Ref-ID, String Ref, or CSS Selector)
browser.click(1)                         # Click Ref-ID #1
browser.click("button.submit-btn")       # CSS selector fallback
browser.type(2, "search query", press_enter=True)
browser.select(3, "Option Value")
browser.hover(1)
browser.scroll(x=0, y=500)

# Waiting & Synchronization
browser.wait_for(1, state="visible", timeout=10.0)
browser.wait_for_url(r"^https://example\.com/dashboard", timeout=15.0)

# Page Evaluation & Inspection
result = browser.eval_js("window.innerWidth")
png_bytes = browser.screenshot()
text = browser.get_text(1)
attr = browser.get_attribute(1, "data-custom")

# Fast Native Media Control (Zero-DOM)
state = browser.media.status()           # HTML5 media state & player metadata
browser.media.toggle()                   # Toggle play/pause
browser.media.play()                     # Resume playback
browser.media.pause()                    # Pause playback
browser.media.seek(15.0)                 # Seek relative seconds (+15s / -10s)
browser.media.set_volume(0.8)            # Set volume level (0.0 to 1.0)

# Multi-Tab Control & Help
new_tab = browser.new_tab("https://google.com")
all_tabs = browser.tabs
active = browser.active_tab
browser.close_tab(2)
print(browser.help())                    # Built-in formatted SDK quick reference

Características principales

• Instantáneas semánticas Ref-ID: Genera árboles DOM accesibles compactos y eficientes en tokens con números asignados ([#1], [#2]), evitando XPath frágiles o selectores CSS largos.

• Controlador de medios rápido (browser.media): Manipulación de reproducción de medios sin DOM que penetra en las raíces abiertas de Shadow DOM sin costosos recálculos de instantáneas.

• REPL de Python persistente: El estado, las variables, las importaciones y las funciones personalizadas persisten entre las llamadas a las herramientas del agente.

• Autocuración en un solo turno: Adjunta automáticamente una instantánea DOM de diagnóstico ([diagnostic_auto_snapshot]) y sugerencias difusas cuando se produce un error, lo que permite a los agentes autocorregirse en un solo turno.

• Recursos y prompts de MCP: Recursos MCP integrados (arthur://docs/api, arthur://docs/workflow) y prompts estructurados (browser_automation, media_control) para una incorporación inteligente del agente.

• Presupuesto de tokens y desactivación: Trunca las salidas grandes para evitar la explosión de la ventana de contexto y sanea las balizas de imágenes de seguimiento ([IMAGE_BLOCKED]).

Desarrollo local

Si quieres contribuir o compilar desde el código fuente:

# Clone and install dependencies
git clone https://github.com/sh7vansh/arthur.git
cd arthur
uv sync --all-extras

# Run tests
uv run pytest

# Run type checker
uv run mypy src

Licencia

Este proyecto está licenciado bajo la Licencia MIT — consulta el archivo LICENSE para más detalles.