From 9af0f684f0e0f1d808aceac407f4b924365b6285 Mon Sep 17 00:00:00 2001 From: Mohamed Mostafa Date: Wed, 26 Nov 2025 00:53:56 +0200 Subject: [PATCH] feat(navigation): add swipe tool for horizontal and vertical swiping - Support direction-based swipes (left, right, up, down) - Support custom coordinate-based swipes with configurable duration - Optimized horizontal swipe handling for Android RecyclerViews - Platform-specific implementations for Android and iOS - Updated documentation in README and tools README --- README.md | 1 + src/tools/README.md | 1 + src/tools/index.ts | 2 + src/tools/navigations/swipe.ts | 357 +++++++++++++++++++++++++++++++++ 4 files changed, 361 insertions(+) create mode 100644 src/tools/navigations/swipe.ts diff --git a/README.md b/README.md index b66b256..81150d6 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,7 @@ MCP Appium provides a comprehensive set of tools organized into the following ca | `appium_screenshot` | Take a screenshot of the current screen and save as PNG | | `appium_scroll` | Scroll the screen vertically (up or down) | | `appium_scroll_to_element` | Scroll until a specific element becomes visible | +| `appium_swipe` | Swipe the screen in a direction (left, right, up, down) or between custom coordinates | | `appium_get_page_source` | Get the page source (XML) from the current screen | ### App Management diff --git a/src/tools/README.md b/src/tools/README.md index 3b87732..8e80d7e 100644 --- a/src/tools/README.md +++ b/src/tools/README.md @@ -21,6 +21,7 @@ This directory contains all MCP tools available in MCP Appium. - `scroll.ts` - Scroll screens - `scroll-to-element.ts` - Scroll until element found +- `swipe.ts` - Swipe screens in any direction or between custom coordinates ### Element Interactions (`interactions/`) diff --git a/src/tools/index.ts b/src/tools/index.ts index f03d891..e442938 100644 --- a/src/tools/index.ts +++ b/src/tools/index.ts @@ -26,6 +26,7 @@ import installWDA from './ios/install-wda.js'; import generateTest from './test-generation/generate-tests.js'; import scroll from './navigations/scroll.js'; import scrollToElement from './navigations/scroll-to-element.js'; +import swipe from './navigations/swipe.js'; import findElement from './interactions/find.js'; import clickElement from './interactions/click.js'; import doubleTap from './interactions/double-tap.js'; @@ -120,6 +121,7 @@ export default function registerTools(server: FastMCP): void { // Navigation scroll(server); scrollToElement(server); + swipe(server); // Element Interactions findElement(server); diff --git a/src/tools/navigations/swipe.ts b/src/tools/navigations/swipe.ts new file mode 100644 index 0000000..95b5853 --- /dev/null +++ b/src/tools/navigations/swipe.ts @@ -0,0 +1,357 @@ +import { z } from 'zod'; +import { getDriver, getPlatformName } from '../../session-store.js'; +import log from '../../logger.js'; +import { elementUUIDScheme } from '../../schema.js'; + +function calculateSwipeCoordinates( + direction: 'left' | 'right' | 'up' | 'down', + width: number, + height: number +): { startX: number; startY: number; endX: number; endY: number } { + const centerX = Math.floor(width / 2); + const centerY = Math.floor(height / 2); + + switch (direction) { + case 'left': + return { + startX: Math.floor(width * 0.8), + startY: centerY, + endX: Math.floor(width * 0.2), + endY: centerY, + }; + case 'right': + return { + startX: Math.floor(width * 0.2), + startY: centerY, + endX: Math.floor(width * 0.8), + endY: centerY, + }; + case 'up': + return { + startX: centerX, + startY: Math.floor(height * 0.8), + endX: centerX, + endY: Math.floor(height * 0.2), + }; + case 'down': + return { + startX: centerX, + startY: Math.floor(height * 0.2), + endX: centerX, + endY: Math.floor(height * 0.8), + }; + default: + throw new Error(`Invalid direction: ${direction}`); + } +} + +async function performAndroidSwipe( + driver: any, + startX: number, + startY: number, + endX: number, + endY: number, + duration: number +): Promise { + await driver.performActions([ + { + type: 'pointer', + id: 'finger1', + parameters: { pointerType: 'touch' }, + actions: [ + { type: 'pointerMove', duration: 0, x: startX, y: startY }, + { type: 'pointerDown', button: 0 }, + { type: 'pause', duration: 250 }, + { type: 'pointerMove', duration: duration, x: endX, y: endY }, + { type: 'pointerUp', button: 0 }, + ], + }, + ]); +} + +async function performiOSSwipe( + driver: any, + startX: number, + startY: number, + endX: number, + endY: number, + duration: number +): Promise { + try { + await driver.execute('mobile: dragFromToForDuration', { + fromX: startX, + fromY: startY, + toX: endX, + toY: endY, + duration: duration / 1000, + }); + log.info('iOS swipe completed using mobile: dragFromToForDuration'); + } catch (dragError) { + log.info('mobile: dragFromToForDuration failed, trying performActions'); + await driver.performActions([ + { + type: 'pointer', + id: 'finger1', + parameters: { pointerType: 'touch' }, + actions: [ + { type: 'pointerMove', duration: 0, x: startX, y: startY }, + { type: 'pointerDown', button: 0 }, + { type: 'pause', duration: 200 }, + { type: 'pointerMove', duration: duration, x: endX, y: endY }, + { type: 'pause', duration: 50 }, + { type: 'pointerUp', button: 0 }, + ], + }, + ]); + log.info('iOS swipe completed using performActions'); + } +} + +export default function swipe(server: any): void { + server.addTool({ + name: 'appium_swipe', + description: `Swipe on the current screen in a specified direction or between custom coordinates. + Supports four directions: left, right, up, down. + Can also perform custom coordinate-based swipes for precise control. + This is useful for navigating carousels, switching tabs, dismissing elements, or navigating between screens.`, + parameters: z.object({ + direction: z + .enum(['left', 'right', 'up', 'down']) + .optional() + .describe( + 'Direction to swipe. If provided, coordinates will be calculated automatically based on screen size or, when elementUUID is set, relative to that element. Either direction OR custom coordinates must be provided.' + ), + elementUUID: elementUUIDScheme + .optional() + .describe( + 'Optional element to base the swipe on. When provided with direction, the swipe is calculated relative to this element instead of the whole screen.' + ), + startX: z + .number() + .int() + .min(0) + .optional() + .describe( + 'Starting X coordinate for custom swipe. Required if direction is not provided.' + ), + startY: z + .number() + .int() + .min(0) + .optional() + .describe( + 'Starting Y coordinate for custom swipe. Required if direction is not provided.' + ), + endX: z + .number() + .int() + .min(0) + .optional() + .describe( + 'Ending X coordinate for custom swipe. Required if direction is not provided.' + ), + endY: z + .number() + .int() + .min(0) + .optional() + .describe( + 'Ending Y coordinate for custom swipe. Required if direction is not provided.' + ), + duration: z + .number() + .int() + .min(0) + .max(5000) + .default(600) + .optional() + .describe( + 'Duration of the swipe gesture in milliseconds. Default is 600ms. Higher values create slower swipes.' + ), + }), + annotations: { + readOnlyHint: false, + openWorldHint: false, + }, + execute: async (args: any, context: any): Promise => { + const driver = getDriver(); + if (!driver) { + throw new Error( + 'No active driver session. Please create a session first.' + ); + } + + try { + const platform = getPlatformName(driver); + let startX: number, startY: number, endX: number, endY: number; + + if (args.direction) { + if (args.elementUUID) { + const rect = await (driver as any).getElementRect(args.elementUUID); + const elementCenterX = Math.floor(rect.x + rect.width / 2); + const elementCenterY = Math.floor(rect.y + rect.height / 2); + + switch (args.direction) { + case 'left': + startX = Math.floor(rect.x + rect.width * 0.8); + startY = elementCenterY; + endX = Math.floor(rect.x + rect.width * 0.2); + endY = elementCenterY; + break; + case 'right': + startX = Math.floor(rect.x + rect.width * 0.2); + startY = elementCenterY; + endX = Math.floor(rect.x + rect.width * 0.8); + endY = elementCenterY; + break; + case 'up': + startX = elementCenterX; + startY = Math.floor(rect.y + rect.height * 0.8); + endX = elementCenterX; + endY = Math.floor(rect.y + rect.height * 0.2); + break; + case 'down': + startX = elementCenterX; + startY = Math.floor(rect.y + rect.height * 0.2); + endX = elementCenterX; + endY = Math.floor(rect.y + rect.height * 0.8); + break; + default: + throw new Error(`Invalid direction: ${args.direction}`); + } + log.info('Calculated element-based swipe coordinates:', { + elementUUID: args.elementUUID, + startX, + startY, + endX, + endY, + }); + } else { + const { width, height } = await driver.getWindowSize(); + log.info('Device screen size:', { width, height }); + const coords = calculateSwipeCoordinates( + args.direction, + width, + height + ); + startX = coords.startX; + startY = coords.startY; + endX = coords.endX; + endY = coords.endY; + } + } else if ( + args.startX !== undefined && + args.startY !== undefined && + args.endX !== undefined && + args.endY !== undefined + ) { + startX = args.startX; + startY = args.startY; + endX = args.endX; + endY = args.endY; + } else { + throw new Error( + 'Either direction or all custom coordinates (startX, startY, endX, endY) must be provided.' + ); + } + + const duration = args.duration || 600; + + log.info('Swipe coordinates:', { + startX, + startY, + endX, + endY, + duration, + }); + + if (platform === 'Android') { + if (startX !== endX && Math.abs(startY - endY) < 50) { + const swipeDuration = Math.min(duration, 400); + await driver.performActions([ + { + type: 'pointer', + id: 'finger1', + parameters: { pointerType: 'touch' }, + actions: [ + { type: 'pointerMove', duration: 0, x: startX, y: startY }, + { type: 'pointerDown', button: 0 }, + { type: 'pause', duration: 200 }, + { + type: 'pointerMove', + duration: swipeDuration, + x: endX, + y: endY, + }, + { type: 'pause', duration: 50 }, + { type: 'pointerUp', button: 0 }, + ], + }, + ]); + log.info('Android horizontal swipe completed'); + } else { + await performAndroidSwipe( + driver, + startX, + startY, + endX, + endY, + duration + ); + } + log.info('Android swipe action completed successfully.'); + } else if (platform === 'iOS') { + if (args.direction) { + try { + await driver.execute('mobile: swipe', { + direction: args.direction, + }); + log.info( + `iOS swipe completed using mobile: swipe (${args.direction})` + ); + } catch (swipeError) { + log.info('mobile: swipe failed, trying dragFromToForDuration'); + await performiOSSwipe( + driver, + startX, + startY, + endX, + endY, + duration + ); + } + } else { + await performiOSSwipe(driver, startX, startY, endX, endY, duration); + } + log.info('iOS swipe action completed successfully.'); + } else { + throw new Error( + `Unsupported platform: ${platform}. Only Android and iOS are supported.` + ); + } + + const directionText = args.direction + ? ` ${args.direction}` + : ` from (${startX}, ${startY}) to (${endX}, ${endY})`; + + return { + content: [ + { + type: 'text', + text: `Swiped${directionText} successfully.`, + }, + ], + }; + } catch (err: any) { + return { + content: [ + { + type: 'text', + text: `Failed to perform swipe. Error: ${err.toString()}`, + }, + ], + }; + } + }, + }); +}