visiontest (Docer1990)

VisionTest-移动自动化MCP服务器

一个MCP服务器，允许AI代理与Android设备和iOS模拟器进行交互——点击、滑动、键入、读取UI元素和启动应用程序。

它做什么

• 安卓+iOS 通过单个MCP服务器实现自动化
• UI交互：点击、滑动、键入文本、查找元素、阅读屏幕层次结构
• 应用管理：列出、检查和启动应用程序
• 设备检测：自动查找已连接的Android设备和已启动的iOS模拟器
• 零配置iOS：安装时使用预构建的测试包，如果需要，则回退到源代码构建

先决条件

• JDK 17或更高版本
• macOS或Linux （臂64或x86_64）
• Android平台工具 （适用于Android自动化）： 下载
• Xcode命令行工具 （仅适用于iOS模拟器自动化，macOS）

安装

快速安装（推荐）

curl -fsSL https://github.com/docer1990/visiontest/releases/latest/download/install.sh | bash

这将：

• 检查是否安装了Java 17+
• 下载最新版本的JAR、Android APK和iOS测试包
• 创建一个 visiontest 命令输入 ~/.local/bin/
• 通过SHA-256校验和验证所有下载

您可以自定义安装目录：

VISIONTEST_DIR="$HOME/my-tools/visiontest" curl -fsSL https://github.com/docer1990/visiontest/releases/latest/download/install.sh | bash

要更新，请重新运行相同的命令。

配置您的AI编码工具

Claude Code

claude mcp add visiontest java -- -jar ~/.local/share/visiontest/visiontest.jar

Claude Desktop

编辑配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "visiontest": {
      "command": "java",
      "args": ["-jar", "/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar"]
    }
  }
}

注： 替换 /ABSOLUTE/PATH/TO 使用您的主目录（例如。 /Users/yourname 在macOS上， /home/yourname 在Linux上）。JSON无法扩展 ~.

GitHub Copilot CLI

添加 ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "visiontest": {
      "command": "java",
      "args": ["-jar", "/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar"],
      "type": "stdio"
    }
  }
}

OpenAI Codex CLI

codex mcp add visiontest -- java -jar ~/.local/share/visiontest/visiontest.jar

或添加到 ~/.codex/config.toml:

[mcp_servers.visiontest]
command = "java"
args = ["-jar", "/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar"]

OpenCode

添加 opencode.json （项目根或 ~/.config/opencode/opencode.json):

{
  "mcp": {
    "visiontest": {
      "type": "local",
      "command": ["java", "-jar", "/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar"]
    }
  }
}

从源代码构建

有关开发或贡献，请参阅 贡献.md.

用法

您的AI编码工具通过MCP自动发现所有可用工具。只需让它与设备交互，它就会使用正确的工具。

Android工作流

1. install_automation_server     →  Install APKs (one-time setup)
2. start_automation_server       →  Start the JSON-RPC server
3. get_interactive_elements      →  Get interactive elements with tap coordinates
4. android_tap_by_coordinates    →  Tap using centerX/centerY
5. android_input_text            →  Type text into focused field

iOS工作流程

1. ios_start_automation_server   →  Start XCUITest server (pre-built or source build)
2. ios_get_interactive_elements  →  Get interactive elements with tap coordinates
3. ios_tap_by_coordinates        →  Tap using centerX/centerY
4. ios_input_text                →  Type text into focused field

可用工具

设备管理： available_device_android, list_apps_android, info_app_android, launch_app_android, ios_available_device, ios_list_apps, ios_info_app, ios_launch_app

安卓自动化： install_automation_server, start_automation_server, automation_server_status, get_ui_hierarchy, get_interactive_elements, find_element, android_tap_by_coordinates, android_swipe, android_swipe_direction, android_swipe_on_element, android_get_device_info, android_input_text, android_press_back, android_press_home

iOS自动化： ios_start_automation_server, ios_automation_server_status, ios_get_ui_hierarchy, ios_get_interactive_elements, ios_find_element, ios_tap_by_coordinates, ios_swipe, ios_swipe_direction, ios_get_device_info, ios_input_text, ios_press_home, ios_stop_automation_server

CLI使用情况

同样的操作也可以作为直接CLI命令使用——不需要MCP客户端：

visiontest automation_server_status -p android
visiontest get_interactive_elements -p ios
visiontest tap_by_coordinates -p android 100 200
visiontest screenshot -p ios --output ./screenshot.png
visiontest swipe_direction -p android up --distance long --speed fast

每个命令都需要 --platform android 或 --platform ios （别名 -p).跑 visiontest --help 获取完整命令列表，或 visiontest --help 用于每个命令的使用。

没有争论， visiontest 启动MCP stdio服务器。

退出代码

配置

环境变量

港口

• 安卓：9008（需要ADB端口转发，自动设置）
• iOS：9009（无需端口转发——模拟器共享Mac的网络）

未来计划

• \[x\] 文本输入/打字支持
• \[x\] 通过UIAutomator/XCUITest捕获屏幕截图
• \[x\] CLI模式（无需MCP即可直接使用命令行）
• \[\]长压机操作
• \[\]等待/同步E2E测试操作
• \[\]多设备协调
• \[\]通用应用程序安装/卸载
• \[\]剪贴板操作（读/写）
• \[\]物理iOS设备支持
• \[\]WebSocket支持实时更新
• \[\]通知/状态栏交互
• \[\]权限对话框自动化
• \[\]自动化会话的视频录制
• \[\]单独的仅CLI工件（下载量较小，无MCP依赖关系）

贡献

看 贡献.md 用于构建源代码说明、架构详细信息、JSON-RPC API参考、测试指南以及如何扩展VisionTest。

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。