MCP Appium 服务器
使用 Appium 实现移动应用自动化的模型上下文协议 (MCP) 服务器实现。
先决条件
- Node.js（v14 或更高版本）
- Java 开发工具包 (JDK)
- Android SDK（用于Android测试）
- Xcode（用于 iOS 测试，仅限 macOS）
- Appium 服务器
- Android 设备或模拟器 / 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 路径：
- 如果需要，请设置正确的 Xcode 路径（特别是当您有多个 Xcode 版本时）：
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
- 接受 Xcode 许可协议：
sudo xcodebuild -license accept
- 对于 iOS 真实设备测试，请确保您的 Apple 开发者帐户在 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
设置
- 安装依赖项：
- 安装并启动 Appium 服务器：
npm install -g appium
appium
- 设置 Android 设备/模拟器：
- 在您的 Android 设备上启用开发者选项
- 启用 USB 调试
- 通过 USB 连接设备或启动模拟器
- 使用
adb devices验证设备是否已连接
- 对于 iOS 测试（仅限 macOS）：
- 确保安装了 Xcode 命令行工具：
xcode-select --install - 设置 iOS 模拟器或连接真实设备
- 如果使用真实设备，请信任 iOS 设备上的开发计算机
运行测试
- 构建项目：
- 启动 MCP 服务器：
- 在新的终端中，运行测试：
测试配置
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 滚动到元素
- 长按
- 应用程序管理：
- 设备控制：
- 高级功能：
- 上下文切换（Native/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 手势
您可以使用executeMobileCommand方法创建自己的自定义W3C手势：
// 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]);
有关 W3C 标准手势实现的更多示例，请参阅examples/w3c-actions-swipe-demo.ts 。
使用 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 Inspector 验证选择器
- 检查元素是否在屏幕上可见
- 尝试不同的定位器策略
- 连接问题：
- 验证 Appium 服务器正在运行
- 检查端口冲突
- 确保设置了正确的功能
- iOS 模拟器问题：
- 验证 Xcode 命令行工具是否已安装：
xcode-select -p - 使用
xcrun simctl list devices检查模拟器 UDID 是否正确 - 如果模拟器无响应，请关闭并重新启动
贡献
请随意提交问题并请求附加功能或错误修复。
执照
麻省理工学院