convez.ai
MCP ServerAutomaçãoAvançado
zifengjiang

Preflight — Testes de Mobile com IA em Dispositivos Reais

zifengjiang/Preflight

Teste apps mobile em dispositivos reais via agentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server local que integra Claude, Cursor e outros assistentes de IA com dispositivos reais Android, iOS e HarmonyOS para testes automatizados de apps mobile. Transforma requisições em linguagem natural em fluxos visuais executáveis com screenshots e relatórios salvos, eliminando a necessidade de seletores frágeis ou coordenadas fixas.

Instalação

$npx convez-ai zifengjiang/Preflight

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v2.0.3
Issues abertas
1
Contribuidores
2

Casos de uso

  • Automatizar testes de UI em apps Android, iOS e HarmonyOS com assistentes de código
  • Validar fluxos de login, navegação e interações sem XPath ou accessibility IDs frágeis
  • Gerar relatórios visuais de testes com screenshots e execução ao vivo

Veredito

Solução robusta e bem-arquitetada para testes mobile assistidos por IA, cobrindo os principais ecosistemas (Android, iOS, HarmonyOS). Requer setup local significativo (dependências de SDK, chaves de API de vision) e conhecimento técnico, mas elimina fragilidades tradicionais de automação mobile.

README

A tradução para o português deste README ainda está na fila.

Preflight

Local MCP server for testing mobile apps on real Android, iOS, and HarmonyOS devices with AI coding assistants.

npm version License: Apache-2.0 Release

Preflight gives Claude Code, Cursor, Codex, and other MCP clients a real mobile device to inspect, operate, and test. It turns natural-language testing requests into structured visual-flow runs with live viewing, screenshots, and saved reports.

Why Preflight?

  • Test on real devices instead of mocked browser views or screenshots.
  • Let coding agents inspect screens, tap, type, swipe, wait, and assert UI state.
  • Generate visual-flow tests without fragile XPath selectors, accessibility-id assumptions, or fixed coordinates.
  • Keep the runtime local: devices, reports, configuration, and the MCP server stay on your machine.
  • Use the same workflow across Android, iOS, and HarmonyOS.

Quick Start

Install the local runtime and register the MCP server:

npx -y preflite@latest setup

This installs the packaged runtime under ~/.preflight/runtime, writes a Preflight MCP entry for Codex (~/.codex/config.toml), and writes a Cursor project entry when you run it inside a repository (.cursor/mcp.json).

Create ~/.preflight/config.json with a Midscene-compatible vision model:

{
  "env": {
    "MIDSCENE_MODEL_BASE_URL": "https://ark.cn-beijing.volces.com/api/v3",
    "MIDSCENE_MODEL_API_KEY": "sk-xxxxxxxxxxxxxxxx",
    "MIDSCENE_MODEL_NAME": "doubao-seed-2-0-lite-260215",
    "MIDSCENE_MODEL_FAMILY": "doubao-seed",
    "MIDSCENE_MODEL_REASONING_ENABLED": "false"
  }
}

Restart your AI coding assistant, then ask it to use Preflight:

Check my connected devices and run a smoke test on the app.

What You Can Ask

Once the MCP server is available, your coding agent can work with real devices through requests like:

  • "List my connected Android and iOS devices."
  • "Open the app and verify the login flow."
  • "Explore the settings screen and turn it into a visual-flow test."
  • "Install this APK and run a smoke test."
  • "Run the flow, watch it live, and save the report."

Requirements

DependencyRequired forNotes
Node.js >= 20.11All platformsInstall via nvm or nodejs.org.
AI model API keyAll platformsAny Midscene-compatible vision model.
adbAndroidShips with Android SDK platform-tools. Ensure adb is on your PATH, or set ADB_BINARY_PATH.
Xcode + iproxyiOSXcode from the Mac App Store. iproxy ships with brew install libimobiledevice.
WebDriverAgentiOSBuild and deploy WebDriverAgent to your device, then set WDA_PROJECT_ROOT.
hdcHarmonyOSShips with DevEco Studio. Ensure hdc is on your PATH.

Model Configuration

Preflight loads model configuration from ~/.preflight/config.json, ~/.preflight/config.yaml, or ~/.preflight/config.yml. You can also rely on standard provider environment variables such as OPENAI_API_KEY or ANTHROPIC_API_KEY.

ProviderMIDSCENE_MODEL_BASE_URLExample MIDSCENE_MODEL_NAME
OpenAIhttps://api.openai.com/v1gpt-4o
Anthropichttps://api.anthropic.com/v1claude-sonnet-4-20250514
Doubao / Volcenginehttps://ark.cn-beijing.volces.com/api/v3doubao-seed-2-0-lite-260215

iOS Setup

iOS testing requires WebDriverAgent running on your device:

git clone https://github.com/facebook/WebDriverAgent.git
cd WebDriverAgent
./Scripts/bootstrap.sh
open WebDriverAgent.xcodeproj

Build the WebDriverAgentRunner scheme targeting your device. Then add the project path to ~/.preflight/config.json:

{
  "env": {
    "WDA_PROJECT_ROOT": "/path/to/WebDriverAgent",
    "WDA_SCHEME": "WebDriverAgentRunner"
  }
}

How It Works

Preflight connects your AI assistant to local device automation through MCP. The assistant does not need to write platform-specific automation scripts; it asks Preflight for device state, explores screens, validates visual-flow JSON, and runs the flow through the local runtime.

flowchart LR
    subgraph AI["AI Coding Assistant"]
        MCP["MCP Client"]
    end

    subgraph Preflight["Preflight MCP Server"]
        EXP["Exploration Tools"]
        IR["Visual Flow IR"]
        AGENT["Local Runtime"]
    end

    subgraph Midscene["Midscene SDK"]
        MS["Vision Agent"]
    end

    subgraph Device["Real Device"]
        SCREEN["Screen and UI Tree"]
    end

    AI <-->|stdio| MCP
    MCP --> EXP
    MCP --> IR
    EXP --> AGENT
    IR --> AGENT
    AGENT --> MS
    MS <-->|adb / WDA / hdc| Device
    SCREEN -.->|screenshots| MS

The main pieces are:

  1. Exploration tools help the assistant understand the current screen and choose what to test.
  2. Visual Flow IR captures a test as structured JSON with steps, assertions, and app context.
  3. Midscene SDK converts high-level visual instructions into device actions such as tap, type, swipe, wait, and assert.

MCP Tools

CategoryTools
Agentagent_health · start_agent · stop_agent · doctor · config_status
Devicelist_devices · install_app
Explorationexploration_start · exploration_end · exploration_get_page_summary · exploration_ai_act · exploration_ask_about_screen · exploration_screenshot · exploration_type · exploration_wait
Visual Flowget_visual_flow_ir_rules · validate_visual_flow · run_flow · watch_run · cancel_run · save_report · read_report

Reports

Runs write report assets under:

~/.preflight/midscene_run/report/<reportName>/

A report can include the HTML summary, execution JSON, screenshots, and compressed recordings when the platform recorder and ffmpeg are available.

Development

Clone the repository when you want to work on Preflight itself:

git clone https://github.com/zifengjiang/Preflight.git
cd Preflight
npm install
npm test
npm run check
npm run build

Register the local development MCP server:

npm run mcp:setup

Release

Releases are triggered by version tags:

git tag v1.1.1
git push origin v1.1.1

The release workflow publishes the npm package and creates a GitHub Release.

License

Apache 2.0

Ver o original no GitHub

Bom para

Relacionados