MCP Appium 服务器
使用 Appium 实现移动应用自动化的模型上下文协议 (MCP) 服务器实现。
先决条件
Node.js（v14 或更高版本）
Java 开发工具包 (JDK)
Android SDK（用于Android测试）
Xcode（用于 iOS 测试，仅限 macOS）
Appium 服务器
Android 设备或模拟器 / iOS 设备或模拟器
Related MCP server: DroidMind
环境设置
在执行任何命令之前，请确保您的环境变量已正确设置：
确保您的.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）：
运行测试
构建项目：
启动 MCP 服务器：
在新的终端中，运行测试：
测试配置
Android 配置
示例测试使用 Android 设置应用作为演示。要测试您自己的应用，请执行以下操作：
编辑examples/appium-test.ts ：
通用功能配置：
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 操作：
元素交互：
应用程序管理：
设备控制：
高级功能：
上下文切换（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 服务器正在运行
检查端口冲突
确保设置了正确的功能
iOS 模拟器问题：
贡献
请随意提交问题并请求附加功能或错误修复。
执照
麻省理工学院
