Dando Olhos e Mãos a um LLM em um Simulador Móvel

A interface que um humano usa

Quando uma pessoa faz QA no tapflow, o ciclo é:

1. Olhar para a tela do simulador
2. Decidir o que fazer (tocar, deslizar, digitar)
3. Fazer isso
4. Olhar novamente

Este é exatamente o ciclo de percepção-ação para o qual os LLMs com capacidade de visão são construídos. O modelo vê uma captura de tela, raciocina sobre o que ela mostra, decide qual ação tomar e chama uma ferramenta para executá-la.

Não precisávamos construir uma nova camada de automação. Apenas precisávamos expor as APIs WebSocket e REST existentes do tapflow como ferramentas MCP.

O que o servidor MCP faz

@tapflowio/mcp-server conecta-se a um relay tapflow em execução e registra 13 ferramentas que qualquer cliente compatível com MCP pode chamar:

list_devices       — ver todos os simuladores registrados no relay
connect_device     — entrar em uma sessão de dispositivo
boot_device        — inicializar um simulador (aguarda até 30s pelo estado pronto)
screenshot         — capturar a tela atual
tap                — tocar em uma coordenada de pixel
deslizar              — deslizar entre duas coordenadas
type_text          — digitar no campo focado
press_key          — pressionar uma tecla do teclado (Retorno, Delete, Escape...)
press_button       — pressionar um botão de hardware (início, bloqueio)
install_app        — instalar uma versão do App Center
launch_app         — iniciar um aplicativo instalado
list_builds        — listar versões disponíveis no relay
disconnect_device  — encerrar a sessão

A configuração é feita com duas variáveis de ambiente:

TAPFLOW_RELAY_URL=wss://seu-url-do-relay
TAPFLOW_TOKEN=seu-token-pat
npx @tapflowio/mcp-server

Adicione-o como um servidor MCP na configuração do seu cliente, e essas ferramentas aparecerão na lista de ferramentas do modelo.

Como as ferramentas são implementadas

Captura de tela — os olhos do modelo

A ferramenta screenshot chama o endpoint REST que adicionamos na v0.3.0 (GET /api/v1/sessions/:id/screenshot), recebe de volta um buffer PNG ou JPEG, codifica em base64 e o retorna como conteúdo image do MCP junto com as dimensões em pixels:

return {
  content: [
    { type: 'image', data: buf.toString('base64'), mimeType },
    { type: 'text', text: `Captura de tela salva: ${filePath} (${width}×${height}px)` },
  ],
}

O modelo recebe a imagem real. Ele pode ler texto na tela, identificar elementos da interface do usuário, notar estados de erro — as mesmas coisas que um humano faria.

Tocar e deslizar — coordenadas normalizadas

Esta é a parte que levou algumas iterações para acertar. O espaço de coordenadas lógico do simulador é diferente das coordenadas de pixel da captura de tela, e muda com a resolução da tela, tipo de dispositivo e fator de escala.

Em vez de expor coordenadas lógicas (que o modelo não pode raciocinar sem conhecimento específico do dispositivo), fazemos o modelo trabalhar inteiramente no espaço de pixels da captura de tela. A ferramenta tap recebe coordenadas de pixel mais as dimensões da captura de tela, e então normaliza internamente:

// tools.ts
client.tap(sessionId, x / screenshotWidth, y / screenshotHeight)

O modelo chama screenshot primeiro, lê as dimensões da resposta e, em seguida, usa essas mesmas dimensões ao chamar tap. Isso significa que o modelo pode identificar "o botão está aproximadamente no pixel 200, 450" da imagem e tocá-lo diretamente — sem necessidade de tradução do sistema de coordenadas.

O deslizar funciona da mesma forma, com 8 eventos touch:move interpolados ao longo da duração para simular um gesto natural:

// client.ts — interpolação de deslizar
const STEPS = 8
const interval = durationMs / STEPS

this.send({ type: 'input:touch:start', sessionId, payload: { x: startX, y: startY } })
for (let i = 1; i < STEPS; i++) {
  await delay(interval)
  const t = i / STEPS
  this.send({
    type: 'input:touch:move',
    sessionId,
    payload: {
      x: Math.round(startX + (