Touchpoint

Touchpoint

Dale a tu agente de IA ojos y manos en cualquier escritorio.

pip install touchpoint-py

Un agente de IA investiga datos en Chrome y luego crea una tabla de Excel con formato — tarea completa en ~12 minutos

Touchpoint es una biblioteca de Python multiplataforma para leer e interactuar con la interfaz de escritorio mediante APIs nativas de accesibilidad. Una sola importación, una sola API — funciona en Linux, macOS y Windows, con soporte integrado para aplicaciones Chromium y Electron mediante CDP (Chrome DevTools Protocol).

En lugar de analizar píxeles o ejecutar modelos de visión, Touchpoint lee el árbol de accesibilidad real — nombres, roles, estados y posiciones estructurados para cada elemento en pantalla. Rápido y confiable, sin necesidad de un modelo de visión. Incluye un servidor MCP para que agentes LLM como Claude, Cursor o cualquier modelo local puedan controlar cualquier aplicación de escritorio de inmediato.

import touchpoint as tp

elements = tp.find("Send", role=tp.Role.BUTTON, app="Slack")
tp.click(elements[0])

¿Por qué Touchpoint?

Tabla de Contenidos

• Tabla de Contenidos
• Instalación
  • Requisitos de plataforma
• Inicio Rápido
  • IDs de elementos
  • Formatos de salida
• Servidor MCP
  • Herramientas
  • Configuración del cliente
  • Variables de entorno
• Aplicaciones de Navegador y Electron (CDP)
  • Configuración
• Referencia de API
  • Descubrimiento
  • Búsqueda y Espera
  • Acciones
  • Entrada
  • Captura de pantalla y Configuración
• Arquitectura
• Configuración
• Desarrollo
• Estado
  • Limitaciones conocidas
• Licencia

Instalación

Requiere Python 3.10+.

pip install touchpoint-py

Todo está incluido: el backend nativo de tu plataforma, soporte CDP para navegadores y aplicaciones Electron, el servidor MCP y capacidades de captura de pantalla. Las dependencias específicas de plataforma se instalan automáticamente mediante marcadores de entorno de pip.

Requisitos de plataforma

Inicio Rápido

import touchpoint as tp

# Discover
apps = tp.apps()                            # ["Firefox", "Slack", "Terminal", ...]
windows = tp.windows()                      # Window objects with title, position, size
all_els = tp.elements(app="Firefox", named_only=True)  # only elements with text labels

# Find
results = tp.find("Search", role=tp.Role.TEXT_FIELD, app="Firefox")

# Act
tp.set_value(results[0], "touchpoint python", replace=True)
tp.press_key("enter")
tp.hotkey("ctrl", "s")                      # keyboard shortcuts

# Wait for UI changes
tp.wait_for("results", app="Firefox", timeout=10)

# Screenshot
img = tp.screenshot()                       # full desktop → PIL.Image
img = tp.screenshot(app="Firefox")           # cropped to app window

IDs de elementos

Cada elemento tiene un ID único como atspi:1234:1:2.0 o cdp:9222:TID:4. Las funciones de acción aceptan tanto un objeto Element como una cadena de ID simple — útil para almacenar referencias entre pasos:

results = tp.find("Send", max_results=1)
element_id = results[0].id                  # "atspi:1234:1:5.2"

# later...
tp.click(element_id)                        # works with just the string

Formatos de salida

Controla cómo se devuelven los resultados:

tp.elements(app="Slack", format="flat")     # one compact line per element (best for LLMs)
tp.elements(app="Slack", format="tree")     # indented parent/child hierarchy
tp.elements(app="Slack", format="json")     # full JSON with all fields

Servidor MCP

Touchpoint incluye un servidor MCP (Model Context Protocol) listo para cualquier cliente compatible con MCP. Úsalo para permitir que agentes LLM como Claude, Cursor, modelos locales o cualquier herramienta que admita MCP controle tu escritorio.

Dos modos — con visión y sin visión

Establece TOUCHPOINT_MODE=no-vision (predeterminado: vision) para cambiar de modo:

• Modo con visión — los agentes usan screenshot() para ver la pantalla e interactuar por ID de elemento o coordenadas. Mejor para modelos de vanguardia con fuertes capacidades de visión.
• Modo sin visión — los agentes usan snapshot() para obtener un árbol de texto estructurado y compacto de la ventana activa, y luego actúan directamente sobre los IDs de elementos. Funciona con cualquier modelo, incluidos los locales que no tienen capacidad de visión. La mayoría de las herramientas de acción añaden banderas de verificación automática ((new window: ...), (focus moved), (no change detected)) para que el agente pueda detectar cambios de estado sin tomar una captura de pantalla.

Herramientas

El servidor MCP incluye instrucciones integradas que enseñan a los agentes el flujo de trabajo correcto para cada modo — incluido el bucle orientar → actuar → verificar, cuándo usar read_text vs find, y cómo recuperarse de errores.

         ┌──────────┐
    ┌───▶│  ORIENT  │  screenshot · apps · windows
    │    └────┬─────┘
    │         ▼
    │    ┌──────────┐
    │    │  LOCATE  │  find · snapshot · get_element
    │    └────┬─────┘
    │         ▼
    │    ┌──────────┐
    │    │   ACT    │  click · set_value · type_text · press_key
    │    └────┬─────┘
    │         ▼
    │    ┌──────────┐
    │    │  VERIFY  │───▶ Done ✅
    │    └────┬─────┘
    │         │ not yet
    └─────────┘

Configuración del cliente

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

{
  "servers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

claude mcp add touchpoint -- touchpoint-mcp

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

Variables de entorno

Aplicaciones de Navegador y Electron (CDP)

Las APIs nativas de accesibilidad devuelven datos limitados para aplicaciones Electron y Chromium (Slack, Discord, VS Code, etc.). El backend CDP de Touchpoint se conecta mediante Chrome DevTools Protocol para obtener el contenido web completo.

El auto-descubrimiento está habilitado de forma predeterminada — Touchpoint encuentra automáticamente navegadores y aplicaciones Electron en ejecución que se lanzaron con un puerto de depuración. No se necesita configuración manual más allá de lanzar la aplicación con la bandera.

Configuración

1. Lanza la aplicación con un puerto de depuración:

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/tp-chrome

# macOS
open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/tp-chrome

# Windows
start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\tp-chrome

2. Configura Touchpoint:

import touchpoint as tp

tp.configure(cdp_discover=True)             # auto-discover from running processes
# or
tp.configure(cdp_ports={"Google Chrome": 9222})  # explicit mapping

3. Controla lo que obtienes con el parámetro source:

tp.elements(app="Google Chrome", source="full")     # native chrome + web content (default)
tp.elements(app="Google Chrome", source="cdp_ax")   # web content only (CDP accessibility tree)
tp.elements(app="Google Chrome", source="native")   # native UI only (toolbar, tabs, menus)
tp.elements(app="Google Chrome", source="dom")      # DOM walker (catches what AX misses)

Los resultados CDP se combinan con los resultados del backend nativo — obtienes la barra de herramientas y los controles de ventana de AT-SPI2/UIA/AX, combinados con el contenido completo de la página web de CDP, en una sola llamada elements().

source="ax" sigue siendo aceptado como un alias de compatibilidad para source="cdp_ax". Prefiere cdp_ax en código nuevo para que no se confunda con el backend nativo AX de macOS.

Referencia de API

Descubrimiento

Búsqueda y Espera

Acciones

Entrada

Captura de pantalla y configuración

Todas las funciones de acción aceptan un objeto Element o un ID de cadena. elements(), find() y get_element() admiten format="flat", format="json" o format="tree" (solo elementos) para devolver cadenas preformateadas en lugar de objetos. La gestión de ventanas está implementada en los backends Linux AT-SPI2, Windows UIA y macOS AX.

Arquitectura

┌───────────────────────────────────────────────────────┐
│               import touchpoint as tp                 │
│  tp.find() · tp.click() · tp.screenshot() · ...       │
│                    (Public API)                       │
├─────────────────────────┬─────────────────────────────┤
│     Backend (ABC)       │    InputProvider (ABC)      │
├─────────────────────────┼─────────────────────────────┤
│  AT-SPI2     (Linux)    │  Xdotool       (X11)        │
│  UIA         (Windows)  │  SendInput     (Win32)      │
│  AX          (macOS)    │  CGEvent       (macOS)      │
│  CDP         (browsers) │                             │
├─────────────────────────┴─────────────────────────────┤
│  Utilities: formatter · matcher · screenshot · scale  │
└───────────────────────────────────────────────────────┘

Diseño de dos capas:

• Backend lee el árbol de accesibilidad y ejecuta acciones estructuradas (clic, set_value, focus). Consciente de elementos y fiable.
• InputProvider simula entrada bruta de teclado y ratón. Basado en coordenadas y sin conocimiento de elementos. Se usa como respaldo automático cuando una acción de accesibilidad nativa no está disponible.

CDP se ejecuta junto al backend de la plataforma. Sus resultados se fusionan: el marco nativo de la ventana (barra de herramientas, pestañas, menús) de AT-SPI2/UIA/AX, más el contenido web completo de CDP, unificados bajo una sola API.

Para detalles internos, ver ARCHITECTURE.md.

Configuración

tp.configure(
    fuzzy_threshold=0.6,          # minimum match score for find() (0.0–1.0)
    fallback_input=True,          # use InputProvider when native actions fail
    type_chunk_size=40,           # split long text into chunks for typing (0 = disable)
    max_elements=5000,            # max elements per query
    max_depth=20,                 # default tree depth limit
    scale_factor=None,            # display scale override (None = auto-detect)
    cdp_ports={"Chrome": 9222},   # explicit CDP port mapping
    cdp_discover=True,            # auto-discover CDP ports from running processes
    cdp_refresh_interval=5.0,     # seconds between CDP target scans
    ax_messaging_timeout=1.0,     # max seconds to wait for a macOS AX app reply
)

tp.diagnostics() devuelve un informe de salud compatible con JSON. Incluye el backend activo, el proveedor de entrada, los objetivos CDP, las herramientas de plataforma opcionales, los tiempos de espera configurados y las apps de macOS omitidas recientemente tras un tiempo de espera de mensajería AX.

Desarrollo

git clone https://github.com/Touchpoint-Labs/touchpoint.git
cd touchpoint
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Estado

Alfa — totalmente funcional y probado en las tres plataformas. La API puede cambiar antes de la versión 1.0 según los comentarios de los usuarios.

Limitaciones conocidas

• Entrada Wayland — El InputProvider de Linux usa xdotool, que requiere X11. En Wayland puro (sin XWayland), la simulación de teclado/ratón no está disponible. El árbol de accesibilidad y las acciones nativas siguen funcionando.

• CDP síncrono — Las llamadas CDP bloquean las respuestas de WebSocket. Los diálogos de JavaScript (alert, confirm, prompt) se descartan automáticamente para evitar bloqueos. Se planea una reescritura asíncrona.

• Sin API de navegación — Touchpoint no tiene navegación de URL integrada. Los agentes pueden navegar interactuando directamente con los elementos de la interfaz: encontrar la barra de direcciones, escribir una URL, pulsar Enter.

• Las ventanas CDP son objetivos de página, no ventanas del SO — pero la gestión de ventanas sigue funcionando: tp.activate_window() trae el objetivo al frente mediante CDP, y minimize/fullscreen/close/move/resize en una ventana cdp: visible se enrutan a la ventana nativa del SO subyacente (resuelta por el PID propietario) y se gestionan mediante el backend de la plataforma. Solo lanzan ActionFailedError si no se puede encontrar una ventana nativa del SO para ese objetivo (por ejemplo, si se ha cerrado).

• La paridad de roles/estados del backend sigue siendo desigual — macOS AX y Windows UIA mejoraron significativamente en 0.3.0, pero Windows aún depende de más heurísticas y tiene más roles de cola larga sin mapear que los otros backends.

Hoja de ruta

Prioridad alta

• Arquitectura CDP asíncrona — WebSocket no bloqueante, cola de diálogos adecuada, consultas concurrentes de múltiples pestañas

Prioridad media

• Paridad de roles/estados del backend — cerrar las brechas restantes de mapeo de roles, especialmente los roles de cola larga de UIA en Windows
• Backend de entrada Wayland — libei / xdg-desktop-portal RemoteDesktop cuando X11 no esté disponible

Prioridad baja

• Visibilidad de tooltips y notificaciones
• Caché de elementos

Licencia

MIT