Appium-MCP

Name: Appium-MCP
Author: Rahulec08

作者：Rahulec0849 星标更新：2025-07-30

安装使用来源：spider==github.com

项目介绍

【技术文档摘要】：

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

功能

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

先决条件

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

环境设置

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

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

# 示例环境变量在 ~/.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  # 对于 bash
# 或者
source ~/.zshrc         # 对于 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 开发环境变量：

# 将这些添加到您的 ~/.bash_profile 或 ~/.zshrc 中
export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
export PATH="$DEVELOPER_DIR/usr/bin:$PATH"

加载更新的配置：

source ~/.bash_profile  # 对于 bash
# 或者
source ~/.zshrc         # 对于 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",
  // 对于安装和测试 APK：
  app: "./path/to/your/app.apk",
  // 或者对于测试已安装的应用：
  appPackage: "your.app.package",
  appActivity: ".MainActivity",
  noReset: true,
};

iOS 配置

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

示例配置在 examples/xcode-appium-example.ts 中：

const capabilities: AppiumCapabilities = {
  platformName: "iOS",
  deviceName: "iPhone 13", // 您的模拟器或设备名称
  automationName: "XCUITest",
  udid: "DEVICE_UDID", // 从 XcodeCommands.getIosSimulators() 获取
  // 对于安装和测试应用：
  app: "./path/to/your/app.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 动作用于点击元素

tapElement 方法现在使用 W3C Actions API，并带有智能回退：

// 方法将按以下顺序尝试：
// 1. 标准 WebdriverIO 点击()
// 2. W3C Actions API
// 3. 遗留 TouchAction API（为了向后兼容性）
await appium.tapElement("//android.widget.Button[@text='OK']");
// 或者使用点击别名
await appium.click("//android.widget.Button[@text='OK']");

W3C 动作用于滚动

scrollToElement 方法现在使用 W3C Actions API：

// 使用 W3C Actions API 进行更可靠的滚动
await appium.scrollToElement(
  "//android.widget.TextView[@text='关于手机']", // 选择器
  "down", // 方向："up"、"down"、"left"、"right"
  "xpath", // 策略
  10 // 最大滚动次数
);

自定义 W3C 手势

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

// 创建自定义 W3C Actions API 手势
const w3cActions = {
  actions: [
    {
      type: "pointer",
      id: "finger1",
      parameters: { pointerType: "touch" },
      actions: [
        // 移动到起始位置
        { type: "pointerMove", duration: 0, x: startX, y: startY },
        // 按下
        { type: "pointerDown", button: 1 },
        // 在持续时间毫秒内移动到结束位置
        {
          type: "pointerMove",
          duration: duration,
          origin: "viewport",
          x: endX,
          y: endY,
        },
        // 释放
        { type: "pointerUp", button: 1 },
      ],
    },
  ],
};

// 使用 executeScript 执行 W3C Actions
await appium.executeMobileCommand("performActions", [w3cActions.actions]);

查看 examples/w3c-actions-swipe-demo.ts 以获取更多 W3C 标准手势实现示例。

使用 Xcode 命令行工具

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

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

// 检查 Xcode CLI 工具是否已安装
const isInstalled = await XcodeCommands.isXcodeCliInstalled();

// 获取可用模拟器
const simulators = await XcodeCommands.getIosSimulators();

// 启动模拟器
await XcodeCommands.bootSimulator("SIMULATOR_UDID");

// 安装应用
await XcodeCommands.installApp("SIMULATOR_UDID", "/path/to/app.app");

// 启动应用
await XcodeCommands.launchApp("SIMULATOR_UDID", "com.example.app");

// 截图
await XcodeCommands.takeScreenshot("SIMULATOR_UDID", "/path/to/output.png");

// 关闭模拟器
await XcodeCommands.shutdownSimulator("SIMULATOR_UDID");

使用点击函数

click() 方法提供了一个比 tapElement() 更直观的替代方案：

// 使用点击方法
await appium.click("//android.widget.Button[@text='OK']");

// 这相当于：
await appium.tapElement("//android.widget.Button[@text='OK']");

故障排除

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

贡献

欢迎提交问题和拉取请求以增加新功能或修复错误。

许可证

MIT