# 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: ```text 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: ```text 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. Capacidades previstas: - backend/orquestador intermedio - gestion mas rica de sesiones y perfiles - configuracion de seguridad y permisos de uso - control mas fino de navegacion externa - artefactos y observabilidad mas avanzados - puntos de extension para diagnostico con `CDP` - posible evaluacion futura de `WebKit` para compatibilidad, sin desplazar a Chromium como base inicial --- ## Por definir mas adelante - politica exacta de uso sobre webs externas - allowlist de dominios - confirmacion para acciones sensibles - gestion de `CAPTCHA` y `2FA` - necesidad real de soporte `WebKit` - nivel de persistencia de sesiones entre ejecuciones - politica final de seleccion entre `managed chromium` y `system browser` --- ## Criterio de exito de la v1 La v1 se considerara lograda cuando: - OpenCode pueda usar la herramienta browser como tool externa por `MCP` - el browser se abra en modo visible y responda a acciones reales - el agente pueda navegar e interactuar con una app local - la herramienta pueda devolver evidencia suficiente para diagnosticar fallos - la estructura creada permita evolucionar a v2 sin rehacer la integracion con OpenCode