paco/opencode-browser-tool-installer

Fork 0

Paco 420c6c85bb chore: initialize browser tool devlog from project root

2026-04-24 23:59:41 +02:00

10 KiB

Raw Permalink Blame History

Plan de desarrollo - Browser Tool para OpenCode

Proyecto

Nombre del proyecto: opencode-browser-tool

Objetivo general:

Construir una herramienta browser externa a OpenCode que permita a un agente navegar, inspeccionar e interactuar con aplicaciones web de forma visible por defecto, con soporte posterior para ejecucion headless y capacidades avanzadas de diagnostico.

La herramienta debe quedar desacoplada del nucleo de OpenCode para que futuras actualizaciones de OpenCode no rompan ni obliguen a rehacer la solucion.

Resultado esperado

Al terminar el proyecto, OpenCode debe poder usar la herramienta como una tool externa para:

abrir un navegador controlado por la herramienta
entrar en aplicaciones locales o webs externas autorizadas
interactuar con la interfaz como un usuario real
inspeccionar DOM, consola y red
recoger evidencia de ejecucion
devolver resultados estructurados al agente

Criterios estructurales fijados

La solucion debe ser externa a OpenCode.
El browser y su logica no deben vivir dentro del core de OpenCode.
La integracion con OpenCode debe hacerse por MCP.
La primera version debe priorizar visible como modo por defecto.
headless quedara disponible para escenarios tecnicos donde la UI visible no sea el foco principal.
La base tecnologica inicial sera Playwright + Chromium.
CDP se considerara como capacidad complementaria y progresiva, no como dependencia central de la v1.

Arquitectura objetivo por fases

Fase 1 - Arquitectura simple funcional

Flujo:

OpenCode -> MCP server externo -> Playwright -> Chromium

Caracteristicas:

MCP server externo ejecutado fuera del core de OpenCode
Playwright como motor principal de automatizacion
Chromium como navegador base
gestion simple de sesiones de browser
artefactos locales: screenshots, logs, traces y video cuando aplique

Ventaja principal:

Permite llegar rapido a una version util sin comprometer la evolucion futura.

Fase 2 - Arquitectura modular

Flujo previsto:

OpenCode -> MCP server externo -> backend/orquestador interno -> runner browser

Caracteristicas previstas:

separacion entre capa MCP y capa operativa del navegador
gestion mas fuerte de sesiones, colas, perfiles y artefactos
posibilidad de varios runners o modos de ejecucion
mejor punto de extension para seguridad, politicas y control de uso

Fase 3 - Diagnostico avanzado

Capacidades previstas:

ganchos CDP para inspeccion avanzada de Chromium
mas telemetria y diagnostico de red, runtime y rendimiento
capacidades de analisis fino de estados del navegador durante pruebas complejas

Alcance funcional de la v1

La v1 debe resolver correctamente la interaccion efectiva entre OpenCode y el browser.

Lo que debe incluir

integracion por MCP
ejecucion visible por defecto
soporte para abrir navegador e ir a una URL
acciones basicas: click, type, press, select, scroll, hover
esperas utiles: selector, texto, URL, carga de pagina
lectura de informacion de pantalla y DOM
ejecucion de JavaScript en pagina cuando haga falta
logica nativa de estabilizacion tras acciones de navegacion/interaccion para reducir esperas manuales
captura de screenshot
captura de consola y errores del runtime de la pagina
soporte para video o tracing si el coste operativo es razonable desde la v1
respuesta estructurada al agente con estado, error y evidencia

Lo que puede quedar fuera de la v1 si retrasa demasiado

backend intermedio separado
politicas completas para webs externas
soporte fuerte de perfiles persistentes complejos
capacidades avanzadas de CDP
compatibilidad cross-browser real con WebKit o Firefox

Herramientas y componentes previstos

Base principal

Playwright
Chromium
Node.js 20+
TypeScript

Integracion

MCP server externo como interfaz con OpenCode

Diagnostico progresivo

CDP en puntos concretos cuando Playwright no cubra suficientemente el caso

Artefactos

screenshots
logs de consola
resultados estructurados
video o trace cuando convenga

Contratos que deben quedar bien definidos desde el inicio

Aunque la v1 use arquitectura simple, el diseno debe dejar estables estos contratos:

contrato de sesion de browser
contrato de acciones del navegador
contrato de artefactos generados
contrato de respuesta al agente

Esto permitira pasar a una arquitectura con backend/orquestador sin rehacer el modelo base.

Stack fijado para la v1

Queda fijado para la v1:

Node.js 20+
TypeScript
Playwright
Chromium
@modelcontextprotocol/sdk
MCP por stdio

Decision de navegador para v1:

usar Chromium managed by Playwright como modo por defecto y recomendado
ejecutar instalacion de Chromium durante install.sh mediante npx playwright install chromium
no depender del Chromium del sistema en la v1 para evitar variaciones de compatibilidad

Evolucion prevista:

habilitar en fase posterior un modo opcional system browser por executablePath para quienes prefieran reutilizar un navegador ya instalado

Queda descartado por ahora:

usar Puppeteer en paralelo a Playwright
introducir WebKit en la v1 como motor principal
construir desde el inicio un backend intermedio obligatorio

Tools MCP minimas de la v1

La v1 se implementara con un conjunto pequeno y suficiente de tools MCP.

Lista inicial fijada:

browser_open
browser_close
browser_navigate
browser_click
browser_type
browser_press
browser_scroll
browser_wait
browser_snapshot
browser_evaluate

Capacidad cubierta por este conjunto:

apertura y cierre de sesion de browser
navegacion a URL objetivo
interaccion base con la interfaz
esperas para estabilizar ejecuciones
captura de evidencia visual inicial
lectura o evaluacion de estado en pagina mediante JavaScript

Capacidades previstas para ampliacion posterior sin romper estos contratos:

logs de consola como tool separada o adjunta a respuestas
tracing o video
lectura estructurada de red
gestion avanzada de perfiles y sesiones

Estructura inicial fijada del proyecto

La estructura inicial del proyecto queda fijada asi:

opencode-browser-tool/
  artifacts/
  docs/
    PLAN_DE_DESARROLLO.md
    TODO.md
  scripts/
  src/
    browser/
    tools/
    types/
    server.ts
  .gitignore
  check.sh
  install.sh
  opencode.mcp.example.json
  package.json
  README.md
  tsconfig.json

Objetivo de esta estructura:

separar claramente documentacion, codigo, scripts y artefactos
dejar lista la base para evolucionar a una arquitectura modular
mantener el paquete autocontenido para instalarlo en otros equipos con OpenCode

Comunicacion interna prevista

En la v1

OpenCode actuara como cliente MCP.

La herramienta expondra un MCP server externo que OpenCode podra arrancar y usar.

Ese servidor traducira las tools pedidas por OpenCode a operaciones sobre Playwright.

En la v2

El MCP server podra seguir siendo la cara publica, pero delegando ya en un backend intermedio propio.

Esto permite mantener estable la integracion con OpenCode mientras evoluciona el interior del sistema.

Instalacion y distribucion esperadas

La herramienta debe poder distribuirse como carpeta autocontenida del proyecto.

Estructura objetivo aproximada:

opencode-browser-tool/
  docs/
  src/
  scripts/
  artifacts/
  package.json
  README.md
  install.sh
  check.sh
  opencode.mcp.example.json

Objetivo de instalacion

En un PC con OpenCode, debe ser posible dejar la herramienta lista con uno de estos caminos:

ejecutar un script de instalacion rapida
seguir instrucciones claras en un .md
pedir a un agente de OpenCode que ejecute esas instrucciones y deje todo listo

Lo que debe dejar listo la instalacion

dependencias del proyecto instaladas
Playwright y Chromium preparados
scripts de verificacion funcional
plantilla de configuracion de OpenCode para conectar el MCP server
rutas de artefactos creadas
instrucciones claras para primer uso

Funcionamiento operativo esperado de la v1

Configuracion inicial

el usuario instala el proyecto en una carpeta del sistema
el usuario ejecuta el script o sigue el .md de instalacion
OpenCode queda configurado para conocer el MCP server del browser tool

Uso normal

el agente decide usar la herramienta o el usuario se lo ordena
OpenCode lanza el MCP server externo si la integracion se hace por stdio
el MCP server llama a Playwright
Playwright controla Chromium
la herramienta devuelve al agente resultados y evidencia

Modos de arranque del MCP server

Se prioriza para la v1:

stdio autolanzado por OpenCode

Queda prevista mas adelante la opcion:

servicio persistente separado si el crecimiento del sistema lo requiere

V2 prevista

La v2 debe apoyarse en una v1 ya funcional y estable.