forms-vision — MCP para ver y manejar Oracle Forms

Permite a Claude abrir SAFIX, fotografiar la pantalla y los elementos de una forma, y navegar por ella (clicks, texto, teclas).

⚠ Maneja una sesión REAL del ERP

Esta herramienta inyecta entrada real: mueve el puntero físico y el foco del teclado de verdad, porque AWT ignora los mensajes sintéticos. Un click mal calculado pulsa lo que haya en ese píxel.

Solo actúa en los ambientes de ambientes_permitidos —SAFIXDEMOS de fábrica—. Esto ya no es un consejo del README: lee el ambiente del título de la ventana y rechaza todo lo demás, incluida la captura. Falla cerrado: si no puede leer el ambiente, no actúa.

Guardas que trae puestas: F10 y CTRL+S bloqueadas, se niega a pulsar botones cuyo WHEN-BUTTON-PRESSED contiene COMMIT/RUN_PRODUCT/DELETE, no inyecta nada si la ventana no logra ponerse en primer plano, y ante «¿Desea salvar los cambios?» la respuesta correcta es siempre No.

Los controles técnicos y —más importante— los que una herramienta no puede implementar están en SEGURIDAD.md.

Precondición: SAFIX tiene que declarar el ambiente

El control anterior lee el ambiente de títulos como Administración del Sistema [XENCO/Safix@SAFIXDEMOS/2026-09]. SAFIX solo rotula así una vez completado el inicio de sesión con empresa y período; antes de eso el título es XENCO - Administracion del Sistema y no declara nada, así que la herramienta se niega a trabajar.

No es un defecto: es no actuar sin saber contra qué base se trabaja. Completa el inicio de sesión antes de empezar. forms_ventanas —la única herramienta sin restricción, porque para saber dónde estás hay que poder mirar— dice qué ambiente ve.

Por qué está hecho así

Verificado en este equipo el 2026-09-01 con probe_forms.py:

Por eso la ubicación de los items no se descubre, se deduce: sale de los XPosition/YPosition/Width/Height que 06-frontend/forms/extraer_forma.py ya extrae del .fmb, traducidos a píxeles con una calibración medida una vez por forma. No se asume ninguna conversión de unidades — se mide, porque coordenadas_modulo viene None en los extracts existentes.

Related MCP server: Computer Use MCP Server

Flujo obligatorio para una sesión de fotos

Añadido 2026-09-02, después de medir dónde se iba el tiempo en la primera sesión real. Las decisiones se toman con el extract, no frente a la forma.

[1] forms_plan(forma)      -> qué fotos hacen falta, cómo llegar a cada una,
                              qué NO necesita foto y por qué, y qué botones
                              NO se pueden pulsar porque escriben en la BD
[2] revisar el plan         -> cerrar la lista ANTES de tocar la forma
[3] forms_secuencia(...)    -> ejecutar por lotes: click, tecla, capturar
[4] lo que no salga         -> anotarlo y seguir; nada de explorar la forma

Prohibido en el paso 3: ir a la forma "a ver qué hay". Si aparece algo que el extract no anunció, se anota y se continúa con el resto.

Por qué es más rápido que la primera versión

Las capas

winauto.py    833   Win32, pixeles, ajustes            no sabe nada de MCP
nucleo.py     143   configuracion, extract, contrato   depende solo de winauto
                    ambiente permitido (A.8.31)
plan.py       366   planificacion desde el .fmb        no toca la forma
calibra.py    168   calibracion .fmb -> pixel
server.py    1143   las 15 herramientas MCP

Cada capa depende solo de las de abajo. nucleo.py existe justamente para romper el círculo: si la configuración y el contrato vivieran en server.py, plan.py tendría que importar server y server importar plan.

El servidor MCP se declara solo en server.py, así que plan y calibra se pueden importar desde una prueba sin levantar nada de MCP — que es lo que permite que las 67 comprobaciones corran sin sesión de Forms.

El contrato de éxito y fallo

Las herramientas devuelven texto, porque quien las lee es un modelo. El problema era que devolvían texto también al fallar, así que un lote tenía que adivinar por subcadenas si un paso había salido bien. Eso costó tres defectos en un solo día, y en dos de ellos se guardaron fotos con el nombre de una lista que nunca se abrió.

Ahora cada fallo va prefijado con [FALLO] y cada aviso que invalida lo que venga detrás con [AVISO]. La lista de marcas_fallo queda como red de seguridad y, cuando salta, lo dice: «…(por marcador de texto, sin token)».

pruebas_contrato.py audita el código fuente de las cuatro capas y falla si alguien añade un retorno de fallo sin token. Ya cazó cuatro que se me escaparon en la conversión.

Herramientas

15 herramientas, agrupadas por lo que hacen:

forms_esperar existe solo como paso de forms_secuencia, que es donde se usa. forms_ventana_activa desapareció: su información está en forms_ventanas.

Las capturas se guardan en 06-frontend/forms/_capturas/<fecha>/ y las herramientas devuelven la ruta, no la imagen: una imagen en línea cuesta mucho contexto y casi siempre basta con abrir la que interesa.

Los dos fallos que no daban ninguna señal

Lo más valioso de la herramienta no es lo que hace, es lo que se niega a hacer a ciegas. Dos fallos producían fotos impecables con el nombre equivocado, y ninguno de los dos daba error:

forms_secuencia detiene el lote ante [FALLO] o [AVISO]: seguir después de uno de estos solo produce fotos mal rotuladas.

El mismo mecanismo decide si un control necesita dos fotos: se mide el área que cambió. CAMBIO ESTRUCTURAL (aparece una pestaña o un panel) → las dos versiones; CAMBIO MENOR (uno o dos campos) → una sola. El umbral está en píxeles, no en porcentaje: el mismo cambio es 0,26% de la ventana de datos y 1,6% de un recuadro de LOV, y con un umbral porcentual la misma diferencia se clasificaba distinto según dónde ocurriera.

Bitácora

Cada captura y cada click_item dejan una línea en _capturas/_bitacora/<fecha>.log con la hora, el usuario de Windows, el pid del servidor, el ambiente, lo que se pidió y los avisos. Los rechazos por ambiente quedan también, marcados XX. Una corrida de ~90 fotos es larga y desatendida: sin registro no hay forma de saber después qué salió y qué quedó a medias. Se cambia con FORMS_VISION_BITACORA.

La escritura del registro se traga sus errores —tumbar una captura por no poder anotarla sería peor— pero los anota y los expone: forms_ventanas muestra siempre la ruta, porque el modo de fallo real no es una excepción sino escribir en el sitio equivocado sin quejarse. Eso pasó de verdad: una prueba con una raíz inexistente creó un árbol entero en Z:\NoExisteEsteProyecto\ sin un solo error.

Ajustes — lo que se afina sin reiniciar

Trece valores viven en ajustes.json y se releen en cada llamada, con caché por fecha de modificación. Son justo los que se afinan probando:

Dejar ambientes_permitidos vacío inhabilita la herramienta a propósito: una lista vacía no significa «todos». Es la única forma de apagarla sin desinstalar.

El archivo aguanta que se edite mal: si falta, no es JSON válido, trae una clave desconocida o un tipo equivocado, se usan los valores de respaldo que lleva winauto.py dentro y se avisa del problema. Un JSON roto a mitad de una corrida de 90 fotos sería peor que el reinicio que evita.

Pruebas

python pruebas_deteccion.py      # 19 comprobaciones, sin sesión de Forms
python pruebas_ajustes.py        # 16 comprobaciones, sin sesión de Forms
python pruebas_contrato.py       # 16 comprobaciones, sin sesión de Forms
python pruebas_ambiente.py       # 16 comprobaciones, sin sesión de Forms
python verificar_entorno.py      # entorno + captura real

Las 67 comprobaciones corren sin abrir SAFIX. Dos de ellas no comprueban un resultado sino el código: pruebas_contrato.py audita las cuatro capas buscando retornos de fallo sin token, y pruebas_ajustes.py compara las claves contra AJUSTES_DEFECTO en vez de contra un número fijo — porque una prueba que hay que editar cada vez que el código crece acaba fallando por estar vieja, no por un defecto.

pruebas_ambiente.py demuestra que el control de ambientes impide en vez de avisar, y lo hace sustituyendo la lectura del título por títulos de prueba, uno de ellos de producción. Comprobar un control de separación de entornos entrando en producción sería el incidente que el control evita.

pruebas_deteccion.py sintetiza las imágenes que necesita, así que corre en cualquier momento. Existe porque lo que verifica está puesto para cazar fallos silenciosos, y una verificación que se creyera a sí misma no serviría de nada — de hecho la primera vez tumbó el umbral porcentual.

verificar_entorno.py necesita las mismas variables que .mcp.json. Sin FORMS_VISION_PROYECTO la raíz se deduce y los chequeos de extracts no valen: eso sale como aviso, no como fallo, para no mandar a buscar un problema que no existe.

Flujo típico

forms_ventanas                                   # ver qué hay abierto
forms_capturar  nombre="estado"                  # foto del canvas
forms_items     forma="ipedidosopt" canvas="LOTES"
forms_calibrar  forma="ipedidosopt" \
                item_a="FECHA_VENCIMIENTO" px_a=... py_a=... \
                item_b="..."            px_b=... py_b=...
forms_capturar_item forma="ipedidosopt" item="FECHA_VENCIMIENTO"

La calibración se guarda en calibraciones.json y deja de valer si mueves o redimensionas la ventana de Forms, o si cambias de resolución.

Si una forma no tiene extract todavía:

python 06-frontend/forms/extraer_forma.py <ruta>/<forma>.xml

Guardas

• Solo se actúa en los ambientes autorizados. El ambiente se lee del título de la ventana —no de la configuración: la configuración dice a qué ambiente se quiso apuntar, el título dice en cuál se está— y lo comprueba _exigir_frente, por donde pasa toda inyección de entrada, más forms_capturar. Falla cerrado. La única herramienta sin restricción es forms_ventanas, que solo mira.

• Ninguna tecla ni click se inyecta si la ventana de Forms no logra ponerse en primer plano. Evita escribir en la aplicación equivocada.

• F10 y CTRL+S están bloqueadas por defecto: son candidatas a confirmar o guardar contra la base de datos. Es una precaución de esta herramienta, no una regla de Forms — se cambia con FORMS_VISION_TECLAS_BLOQUEADAS en .mcp.json.

• La sesión que se maneja es una sesión real, y las capturas contienen los datos reales que estuvieran a la vista. Eso no lo resuelve el código: es el riesgo abierto que documenta SEGURIDAD.md.

El semáforo de la barra — qué significa de verdad

Digitar en los campos no depende del semáforo: se puede escribir en cualquier momento y en cualquier parte. El color importa en el momento de guardar, actualizar o cambiar de página habiendo digitado algo:

De ahí que la guarda de esta herramienta esté en las teclas de guardado, no en el teclear. Antes de pulsar cualquier cosa que confirme, comprobar el color.

Ojo con un patrón frecuente en las formas SAFIX: navegar entre pestañas o mover un radio puede marcar el registro como modificado, y entonces al entrar a modo consulta la forma pregunta si guardar aunque nadie haya escrito. La respuesta segura es siempre No.

Nada está atado a una forma concreta

Todo lo que se descubrió trabajando una forma quedó como mecanismo general:

Para trabajar otra forma no hay que tocar código: basta su extract y sus rutas.

Instalación

git clone <repo> && cd MCP-Capturas-Oracle-Forms
powershell -ExecutionPolicy Bypass -File instalar.ps1 -Proyecto Z:\Projects

El instalador crea el venv, copia el código a %LOCALAPPDATA%\forms-vision e imprime el JSON exacto para el panel Servidores MCP locales de la app.

Por qué el código se copia y no se ejecuta desde el repo

En el equipo donde se desarrolló, Z: es un recurso de red compartido, de ahí la separación. En una máquina con el repo en disco local da igual, pero el instalador hace lo mismo: una sola forma de instalar, sin casos especiales.

Lo que NO se versiona, y por qué

• calibraciones.json — la conversión unidades del .fmb → píxeles, medida contra la ventana viva. Depende de la resolución, del tamaño de la ventana y hasta de la corrida: la misma sección dio escala 1.335 / off 6 en una y 1.33 / off 7 en otra. Versionarlo haría que otra máquina arrancara con una geometría ajena, y los clicks caerían desplazados sin dar ningún error. Se regenera con forms_calibrar.

• el venv y los __pycache__ — binarios de una máquina y una versión de Python concretas.

• .mcp.json y claude_desktop_config.json — configuración de máquina, y el segundo puede llevar credenciales en texto plano.

Tras editar server.py o winauto.py hay que reinstalar y reiniciar la app: el proceso del MCP ya tiene el módulo en memoria y Python no recarga nada por su cuenta. Se comprueba comparando la fecha del archivo con la hora de arranque del proceso — si el proceso es anterior, corre código viejo. Los 9 ajustes de ajustes.json son la excepción: esos se releen en caliente (ver Ajustes).

Configuración

Registrado en Z:\Projects\.mcp.json (ámbito de proyecto: carga cuando la sesión está abierta en Z:\Projects). Variables de entorno:

FORMS_VISION_PROYECTO es obligatoria con la copia local: subir tres niveles desde %LOCALAPPDATA%\forms-vision da una ruta absurda. verificar_entorno.py lo avisa en vez de reportar fallos falsos por extracts que no encuentra.

Dependencias: mcp, mss, pillow. Sin pywin32: la capa Win32 es ctypes puro en winauto.py.

Mejora pendiente — Java Access Bridge

Daría el árbol de componentes en vivo (rol, nombre y rectángulo por item), sin calibrar y sin depender del .fmb. Requiere dos cosas que hoy no están:

1. Habilitar el puente: jabswitch -enable y reiniciar la sesión de Forms.

2. Resolver el choque de arquitectura — instalar un Python de 32 bits, o un JRE 8 de 64 bits para que aparezca WindowsAccessBridge-64.dll.

Ambas son instalaciones en la máquina, así que no se hicieron sin permiso.

Diagnóstico

python probe_forms.py <carpeta_salida>

Enumera las ventanas Java, sus hijos nativos y captura cada una. No envía teclas ni clicks: es seguro contra una sesión en uso.