使用说明

mcp-appium-visual 是一个集成了模型上下文协议（MCP）的AI驱动的移动自动化平台。它通过Appium实现了对Android和iOS设备的无缝控制，具有智能视觉元素检测和恢复功能。

特性

与Appium集成以实现设备控制
视觉元素检测和恢复（基于AI）
MCP支持高级代理驱动的测试工作流程
支持Android和iOS平台
专为与AI代理配合使用而设计，实现智能自动化

先决条件

Node.js（v14或更高版本）
Java开发工具包（JDK）
Android SDK（用于Android测试）
Xcode（用于iOS测试，仅限macOS）
Appium服务器
安卓设备或模拟器/iOS设备或模拟器

环境设置

在执行任何命令之前，请确保您的环境变量已正确设置：

确保你的 .bash_profile, .zshrc 或其他shell配置文件包含必要的环境变量：

# Example environment variables in ~/.bash_profile
export JAVA_HOME=/path/to/your/java
export ANDROID_HOME=/path/to/your/android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

在运行MCP Appium之前获取环境文件：

source ~/.bash_profile  # For bash
# OR
source ~/.zshrc         # For zsh

备注：系统将尝试获取您的 .bash_profile 初始化驱动程序时会自动执行，但建议在新的终端会话中运行测试之前手动确保正确的环境设置。

Xcode命令行工具配置

对于iOS测试，正确的Xcode命令行工具配置至关重要：

如果尚未安装Xcode命令行工具，请安装：

xcode-select --install

验证安装并检查当前Xcode路径：

xcode-select -p

如果需要，请设置正确的Xcode路径（特别是如果您有多个Xcode版本）：

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

接受Xcode许可协议：

sudo xcodebuild -license accept

对于iOS真实设备测试，请确保您的Apple Developer帐户在Xcode中配置正确：
- 打开Xcode
- 转到“首选项”>“帐户”
- 如果尚未添加，请添加您的Apple ID
- 下载必要的配置文件
为iOS开发设置环境变量：

# Add these to your ~/.bash_profile or ~/.zshrc
export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
export PATH="$DEVELOPER_DIR/usr/bin:$PATH"

获取更新的配置：

source ~/.bash_profile  # For bash
# OR
source ~/.zshrc         # For zsh

设置

安装依赖项：

npm install

安装并启动Appium服务器：

npm install -g appium
appium

设置Android设备/模拟器：
- 在您的Android设备上启用开发人员选项
- 启用USB调试
- 通过USB连接设备或启动模拟器
- 使用验证设备是否已连接 adb devices
对于iOS测试（仅限macOS）：
- 确保安装了Xcode命令行工具： xcode-select --install
- 设置iOS模拟器或连接真实设备
- 如果使用真实设备，请信任iOS设备上的开发计算机

运行测试

构建项目：

npm run build

启动MCP服务器：

npm run dev

在新终端中，运行测试：

npm test

测试配置

Android配置

示例测试使用Android设置应用程序作为演示。要测试自己的应用程序：

编辑 examples/appium-test.ts:
- 更新 deviceName 匹配您的设备
- 集 app APK文件的路径，或
- 更新 appPackage 和 appActivity 对于已安装的应用程序
通用功能配置：

const capabilities: AppiumCapabilities = {
  platformName: "Android",
  deviceName: "YOUR_DEVICE_NAME",
  automationName: "UiAutomator2",
  // For installing and testing an APK:
  app: "./path/to/your/app.apk",
  // OR for testing an installed app:
  appPackage: "your.app.package",
  appActivity: ".MainActivity",
  noReset: true,
};

iOS配置

对于使用新Xcode命令行支持的iOS测试：

示例配置 examples/xcode-appium-example.ts:

const capabilities: AppiumCapabilities = {
  platformName: "iOS",
  deviceName: "iPhone 13", // Your simulator or device name
  automationName: "XCUITest",
  udid: "DEVICE_UDID", // Get this from XcodeCommands.getIosSimulators()
  // For installing and testing an app:
  app: "./path/to/your/app.app",
  // OR for testing an installed app:
  bundleId: "com.your.app",
  noReset: true,
};

可用操作

MCP服务器支持各种Appium操作：

元素交互：
- 查找元素
- 使用W3C Actions API点击/点击元素（请参阅“W3C标准手势”部分）
- 键入文本
- 使用W3C Actions API滚动到元素
- 长按
应用程序管理：
- 启动/关闭应用程序
- 重置应用程序
- 获取当前包/活动
设备控制：
- 屏幕方向
- 键盘操作
- 设备锁定/解锁
- 截图
- 电池信息
高级功能：
- 上下文切换（原生/WebView）
- 文件操作
- 通知
- 自定义手势
Xcode命令行工具（仅限iOS）：
- 管理iOS模拟器（启动、关闭）
- 在模拟器上安装/卸载应用程序
- 启动/终止应用程序
- 截图
- 录制视频
- 创建/删除模拟器
- 获取设备类型和运行时

W3C标准手势

MCP-Appium库现在实现了用于触摸手势的W3C WebDriver Actions API，这是移动自动化的现代标准。

W3C对Tap元素的操作

这 tapElement 方法现在使用W3C Actions API进行智能回退：

// The method will try in this order:
// 1. Standard WebdriverIO click()
// 2. W3C Actions API
// 3. Legacy TouchAction API (fallback for backward compatibility)
await appium.tapElement("//android.widget.Button[@text='OK']");
// or using the click alias
await appium.click("//android.widget.Button[@text='OK']");

W3C滚动操作

这 scrollToElement 方法现在使用W3C Actions API：

// Uses W3C Actions API for more reliable scrolling
await appium.scrollToElement(
  "//android.widget.TextView[@text='About phone']", // selector
  "down", // direction: "up", "down", "left", "right"
  "xpath", // strategy
  10 // maxScrolls
);

自定义W3C手势

您可以使用以下命令创建自己的自定义W3C手势 executeMobileCommand 方法：

// Create custom W3C Actions API gesture
const w3cActions = {
  actions: [
    {
      type: "pointer",
      id: "finger1",
      parameters: { pointerType: "touch" },
      actions: [
        // Move to start position
        { type: "pointerMove", duration: 0, x: startX, y: startY },
        // Press down
        { type: "pointerDown", button: 0 },
        // Move to end position over duration milliseconds
        {
          type: "pointerMove",
          duration: duration,
          origin: "viewport",
          x: endX,
          y: endY,
        },
        // Release
        { type: "pointerUp", button: 0 },
      ],
    },
  ],
};

// Execute the W3C Actions using executeScript
await appium.executeMobileCommand("performActions", [w3cActions.actions]);

看 examples/w3c-actions-swipe-demo.ts 了解W3C标准手势实现的更多示例。

使用Xcode命令行工具

新的 XcodeCommands 类为iOS测试提供了强大的工具：

import { XcodeCommands } from "../src/lib/xcode/xcodeCommands.js";

// Check if Xcode CLI tools are installed
const isInstalled = await XcodeCommands.isXcodeCliInstalled();

// Get available simulators
const simulators = await XcodeCommands.getIosSimulators();

// Boot a simulator
await XcodeCommands.bootSimulator("SIMULATOR_UDID");

// Install an app
await XcodeCommands.installApp("SIMULATOR_UDID", "/path/to/app.app");

// Launch an app
await XcodeCommands.launchApp("SIMULATOR_UDID", "com.example.app");

// Take a screenshot
await XcodeCommands.takeScreenshot("SIMULATOR_UDID", "/path/to/output.png");

// Shutdown a simulator
await XcodeCommands.shutdownSimulator("SIMULATOR_UDID");

使用点击功能

这 click() 该方法提供了一种更直观的替代方案 tapElement():

// Using the click method
await appium.click("//android.widget.Button[@text='OK']");

// This is equivalent to:
await appium.tapElement("//android.widget.Button[@text='OK']");

故障排除

未找到设备：
- 检查 adb devices 输出
- 验证USB调试是否已启用
- 尝试重新连接设备
应用程序未安装：
- 验证APK路径是否正确
- 检查设备是否有足够的存储空间
- 确保应用程序已签名以进行调试
未找到元素：
- 使用Appium检查器验证选择器
- 检查屏幕上是否可见元素
- 尝试不同的定位器策略
连接问题：
- 验证Appium服务器是否正在运行
- 检查端口冲突
- 确保设置了正确的功能
iOS模拟器问题：
- 验证Xcode命令行工具是否已安装： xcode-select -p
- 使用以下工具检查模拟器UDID是否正确 xcrun simctl list devices
- 如果模拟器变得无响应，请关闭并重新启动模拟器

贡献

请随时提交问题，并提取对其他功能或错误修复的请求。

许可证

麻省理工学院

使用说明

特性

先决条件

环境设置

Xcode命令行工具配置

设置

运行测试

测试配置

Android配置

iOS配置

可用操作

W3C标准手势

W3C对Tap元素的操作

W3C滚动操作

自定义W3C手势

使用Xcode命令行工具

使用点击功能

故障排除

贡献

许可证

相关 MCP

移动自动化MCP服务器

移动设备自动化服务

移动自动化服务器

移动设备GUI自动化服务器

AI设备操作环境

移动自动化测试工具