appium-mcp 1.66.0 → 1.67.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.67.0](https://github.com/appium/appium-mcp/compare/v1.66.0...v1.67.0) (2026-04-23)
+
+### Features
+
+* scroll-until-found for appium_find_element ([#277](https://github.com/appium/appium-mcp/issues/277)) ([f69eb71](https://github.com/appium/appium-mcp/commit/f69eb71f959d550d01619ec79fc832aa3f81a4db))
+
 ## [1.66.0](https://github.com/appium/appium-mcp/compare/v1.65.0...v1.66.0) (2026-04-23)
 
 ### Features

package/README.md

@@ -335,8 +335,8 @@ The default regex pattern allows any URL that starts with `http://` or `https://
 
 | Tool                  | Description                                                                                  |
 | --------------------- | -------------------------------------------------------------------------------------------- |
-| `appium_find_element` | Find a specific element using traditional locator strategies (xpath, id, accessibility id, etc.) **OR** AI-powered natural language descriptions (e.g., "yellow search button at bottom"). Supports both traditional and AI modes. |
-| `appium_gesture`      | Perform a touch gesture. `action` = `tap`, `double_tap`, `long_press`, `scroll`, `swipe`, `pinch_zoom`, or `scroll_to_element`. Supports element UUIDs (including AI-found `ai-element:` UUIDs) and raw coordinates. For swipe, use `speed` = `slow` \| `normal` \| `fast` (fast for pull-to-refresh). |
+| `appium_find_element` | Find a specific element using traditional locator strategies (xpath, id, accessibility id, etc.) **OR** AI-powered natural language descriptions (e.g., "yellow search button at bottom"). To scroll until an element appears, use **`appium_gesture`** with **`action=scroll_to_element`** (same `strategy` / `selector` as find). |
+| `appium_gesture`      | Perform a touch gesture. `action` = `tap`, `double_tap`, `long_press`, `scroll`, `swipe`, `pinch_zoom`, or **`scroll_to_element`**. **`scroll_to_element`** scrolls vertically (`direction` = `up` \| `down`) until the locator matches, **page source stops changing** after a scroll (end of list), or **`maxScrollAttempts`** (default 10, max 80). Optional **`scrollDistance`** (0.05–1) or **`scrollDistancePreset`** = `small` \| `medium` \| `large`. Supports element UUIDs and raw coordinates for other actions. For swipe, use `speed` = `slow` \| `normal` \| `fast` (fast for pull-to-refresh). |
 | `appium_drag_and_drop` | Perform a drag and drop gesture from a source location to a target location (supports element-to-element, element-to-coordinates, coordinates-to-element, and coordinates-to-coordinates) |
 | `appium_perform_actions` | Execute raw W3C Actions API sequences for custom multi-touch gestures (rotate, three-finger swipe, edge swipes, precise timing). Prefer `appium_gesture` for standard gestures. |
 | `appium_set_value`    | Enter text into an input field                                                               |
@@ -413,6 +413,23 @@ This example demonstrates a complete e-commerce checkout flow that can be automa
 }
 ```
 
+**Scroll until element is on screen (`appium_gesture` / `scroll_to_element`):**
+```json
+{
+  "tool": "appium_gesture",
+  "arguments": {
+    "action": "scroll_to_element",
+    "strategy": "xpath",
+    "selector": "//*[contains(@text,'My header')]",
+    "direction": "down",
+    "maxScrollAttempts": 40,
+    "scrollDistancePreset": "medium"
+  }
+}
+```
+
+Use **`scrollDistance`** (0.05–1) instead of **`scrollDistancePreset`** when you want an exact fraction. Then call **`appium_find_element`** with the same `strategy` / `selector` to obtain the element id.
+
 **AI Mode (Natural Language):**
 ```json
 {

package/dist/tools/gestures/handlers/scroll-to-element.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-to-element.d.ts","sourceRoot":"","sources":["../../../../src/tools/gestures/handlers/scroll-to-element.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAQhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAwDhD,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,aAAa,CAAC,CAiCxB"}
+{"version":3,"file":"scroll-to-element.d.ts","sourceRoot":"","sources":["../../../../src/tools/gestures/handlers/scroll-to-element.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAQhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAmChD,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,aAAa,CAAC,CA0DxB"}

package/dist/tools/gestures/handlers/scroll-to-element.js

@@ -1,7 +1,21 @@
-import { getPlatformName, PLATFORM } from '../../../session-store.js';
-import { execute, getWindowRect, performActions } from '../../../command.js';
+import { getPageSource } from '../../../command.js';
+import log from '../../../logger.js';
 import { errorResult, textResult, toolErrorMessage, } from '../../tool-response.js';
-const MAX_SCROLL_ATTEMPTS = 10;
+import { performVerticalScroll } from './swipe-scroll.js';
+const PRESET_TO_DISTANCE = {
+    small: 0.25,
+    medium: 0.45,
+    large: 1,
+};
+function resolveScrollDistance(args) {
+    if (args.scrollDistancePreset) {
+        return PRESET_TO_DISTANCE[args.scrollDistancePreset];
+    }
+    if (args.scrollDistance !== undefined) {
+        return args.scrollDistance;
+    }
+    return 0.45;
+}
 async function tryFindElement(driver, strategy, selector) {
     try {
         await driver.findElement(strategy, selector);
@@ -11,34 +25,6 @@ async function tryFindElement(driver, strategy, selector) {
         return false;
     }
 }
-async function performW3CScroll(driver, direction) {
-    const { width, height } = await getWindowRect(driver);
-    const startX = Math.floor(width / 2);
-    const startY = direction === 'down' ? Math.floor(height * 0.8) : Math.floor(height * 0.2);
-    const endY = direction === 'down' ? Math.floor(height * 0.2) : Math.floor(height * 0.8);
-    await performActions(driver, [
-        {
-            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: 600, x: startX, y: endY },
-                { type: 'pointerUp', button: 0 },
-            ],
-        },
-    ]);
-}
-async function scrollOnce(driver, direction) {
-    const platform = getPlatformName(driver);
-    if (platform === PLATFORM.ios) {
-        await execute(driver, 'mobile: scroll', { direction });
-        return;
-    }
-    await performW3CScroll(driver, direction);
-}
 export async function handleScrollToElement(driver, args) {
     if (!args.strategy || !args.selector) {
         return errorResult('scroll_to_element requires both strategy and selector.');
@@ -46,17 +32,34 @@ export async function handleScrollToElement(driver, args) {
     const direction = args.direction === 'up' || args.direction === 'down'
         ? args.direction
         : 'down';
+    const maxScroll = args.maxScrollAttempts;
+    if (args.scrollDistancePreset && args.scrollDistance !== undefined) {
+        log.warn('scroll_to_element: scrollDistancePreset is set; ignoring scrollDistance');
+    }
+    const distance = resolveScrollDistance(args);
     try {
         if (await tryFindElement(driver, args.strategy, args.selector)) {
             return textResult(`Element ${args.selector} is already visible on screen.`);
         }
-        for (let attempt = 1; attempt <= MAX_SCROLL_ATTEMPTS; attempt++) {
-            await scrollOnce(driver, direction);
+        let scrollsDone = 0;
+        while (scrollsDone < maxScroll) {
+            const xmlBefore = await getPageSource(driver);
+            try {
+                await performVerticalScroll(driver, { direction, distance });
+            }
+            catch (scrollErr) {
+                return errorResult(`Scroll failed during scroll_to_element: ${toolErrorMessage(scrollErr)}`);
+            }
+            const xmlAfter = await getPageSource(driver);
+            scrollsDone++;
             if (await tryFindElement(driver, args.strategy, args.selector)) {
-                return textResult(`Successfully scrolled to element ${args.selector} after ${attempt} scroll(s).`);
+                return textResult(`Successfully scrolled to element ${args.selector} after ${scrollsDone} scroll(s).`);
+            }
+            if (xmlBefore === xmlAfter) {
+                return errorResult(`Element not found; page source did not change after scroll (likely end of scrollable content). selector=${args.selector}`);
             }
         }
-        return errorResult(`Element ${args.selector} not found after ${MAX_SCROLL_ATTEMPTS} scrolls in direction '${direction}'.`);
+        return errorResult(`Element ${args.selector} not found after ${maxScroll} scroll(s) in direction '${direction}'.`);
     }
     catch (err) {
         return errorResult(`Failed to scroll_to_element. ${toolErrorMessage(err)}`);

package/dist/tools/gestures/handlers/scroll-to-element.js.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-to-element.js","sourceRoot":"","sources":["../../../../src/tools/gestures/handlers/scroll-to-element.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scroll-to-element.js","sourceRoot":"","sources":["../../../../src/tools/gestures/handlers/scroll-to-element.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,GAAG,MAAM,oBAAoB,CAAC;AACrC,OAAO,EACL,WAAW,EACX,UAAU,EACV,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,kBAAkB,GAGpB;IACF,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,IAAI;IACZ,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,SAAS,qBAAqB,CAAC,IAAiB;IAC9C,IAAI,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC9B,OAAO,kBAAkB,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,MAAsB,EACtB,QAAgB,EAChB,QAAgB;IAEhB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAsB,EACtB,IAAiB;IAEjB,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACrC,OAAO,WAAW,CAChB,wDAAwD,CACzD,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GACb,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,SAAS,KAAK,MAAM;QAClD,CAAC,CAAC,IAAI,CAAC,SAAS;QAChB,CAAC,CAAC,MAAM,CAAC;IAEb,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,CAAC;IACzC,IAAI,IAAI,CAAC,oBAAoB,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACnE,GAAG,CAAC,IAAI,CACN,yEAAyE,CAC1E,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAE7C,IAAI,CAAC;QACH,IAAI,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/D,OAAO,UAAU,CACf,WAAW,IAAI,CAAC,QAAQ,gCAAgC,CACzD,CAAC;QACJ,CAAC;QAED,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,OAAO,WAAW,GAAG,SAAS,EAAE,CAAC;YAC/B,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,CAAC;gBACH,MAAM,qBAAqB,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC/D,CAAC;YAAC,OAAO,SAAkB,EAAE,CAAC;gBAC5B,OAAO,WAAW,CAChB,2CAA2C,gBAAgB,CAAC,SAAS,CAAC,EAAE,CACzE,CAAC;YACJ,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;YAC7C,WAAW,EAAE,CAAC;YAEd,IAAI,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC/D,OAAO,UAAU,CACf,oCAAoC,IAAI,CAAC,QAAQ,UAAU,WAAW,aAAa,CACpF,CAAC;YACJ,CAAC;YAED,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;gBAC3B,OAAO,WAAW,CAChB,2GAA2G,IAAI,CAAC,QAAQ,EAAE,CAC3H,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,WAAW,CAChB,WAAW,IAAI,CAAC,QAAQ,oBAAoB,SAAS,4BAA4B,SAAS,IAAI,CAC/F,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,WAAW,CAAC,gCAAgC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC"}

package/dist/tools/gestures/handlers/swipe-scroll.d.ts

@@ -1,6 +1,15 @@
 import type { ContentResult } from 'fastmcp';
 import type { DriverInstance } from '../../../session-store.js';
 import type { GestureArgs } from '../schema.js';
+export type VerticalScrollOptions = {
+    direction: 'up' | 'down';
+    distance: number;
+};
+/**
+ * Vertical swipe in the middle of the window, scaled by `distance` (0.05–1).
+ * Used by `appium_gesture` `scroll_to_element`; matches legacy scroll distances.
+ */
+export declare function performVerticalScroll(driver: DriverInstance, options: VerticalScrollOptions): Promise<void>;
 export declare function handleScroll(driver: DriverInstance, args: GestureArgs): Promise<ContentResult>;
 export declare function handleSwipe(driver: DriverInstance, args: GestureArgs): Promise<ContentResult>;
 //# sourceMappingURL=swipe-scroll.d.ts.map

package/dist/tools/gestures/handlers/swipe-scroll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swipe-scroll.d.ts","sourceRoot":"","sources":["../../../../src/tools/gestures/handlers/swipe-scroll.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAahE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAqHhD,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,aAAa,CAAC,CA8BxB;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,aAAa,CAAC,CA+CxB"}
+{"version":3,"file":"swipe-scroll.d.ts","sourceRoot":"","sources":["../../../../src/tools/gestures/handlers/swipe-scroll.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAahE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAoChD,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAwGD,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,aAAa,CAAC,CA8BxB;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,aAAa,CAAC,CA+CxB"}

package/dist/tools/gestures/handlers/swipe-scroll.js

@@ -3,6 +3,65 @@ import { execute, getElementRect, getWindowRect, performActions, } from '../../.
 import { errorResult, textResult, toolErrorMessage, } from '../../tool-response.js';
 const SCROLL_DURATION_MS = 800;
 const SCROLL_INITIAL_PAUSE_MS = 250;
+/** Pointer move duration for programmatic vertical scroll (matches legacy appium_scroll). */
+const VERTICAL_SCROLL_MOVE_MS = 600;
+function verticalScrollYs(height, direction, distance) {
+    const mid = height * 0.5;
+    const halfSpan = height * 0.3 * distance;
+    if (direction === 'down') {
+        return {
+            startY: Math.floor(mid + halfSpan),
+            endY: Math.floor(mid - halfSpan),
+        };
+    }
+    return {
+        startY: Math.floor(mid - halfSpan),
+        endY: Math.floor(mid + halfSpan),
+    };
+}
+/**
+ * Vertical swipe in the middle of the window, scaled by `distance` (0.05–1).
+ * Used by `appium_gesture` `scroll_to_element`; matches legacy scroll distances.
+ */
+export async function performVerticalScroll(driver, options) {
+    const rect = await getWindowRect(driver);
+    const { width, height } = rect;
+    const startX = Math.floor(width / 2);
+    const { startY, endY } = verticalScrollYs(height, options.direction, options.distance);
+    if (getPlatformName(driver) === PLATFORM.android) {
+        await performActions(driver, [
+            {
+                type: 'pointer',
+                id: 'finger1',
+                parameters: { pointerType: 'touch' },
+                actions: [
+                    { type: 'pointerMove', duration: 0, x: startX, y: startY },
+                    { type: 'pointerDown', button: 0 },
+                    { type: 'pause', duration: SCROLL_INITIAL_PAUSE_MS },
+                    {
+                        type: 'pointerMove',
+                        duration: VERTICAL_SCROLL_MOVE_MS,
+                        x: startX,
+                        y: endY,
+                    },
+                    { type: 'pointerUp', button: 0 },
+                ],
+            },
+        ]);
+    }
+    else if (getPlatformName(driver) === PLATFORM.ios) {
+        await execute(driver, 'mobile: scroll', {
+            direction: options.direction,
+            startX,
+            startY,
+            endX: startX,
+            endY,
+        });
+    }
+    else {
+        throw new Error(`Unsupported platform: ${getPlatformName(driver)}. Only Android and iOS are supported.`);
+    }
+}
 const SWIPE_SPEED_PROFILES = {
     slow: { duration: 600, initialPause: 250 },
     normal: { duration: 300, initialPause: 200 },

package/dist/tools/gestures/handlers/swipe-scroll.js.map

@@ -1 +1 @@
-{"version":3,"file":"swipe-scroll.js","sourceRoot":"","sources":["../../../../src/tools/gestures/handlers/swipe-scroll.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"swipe-scroll.js","sourceRoot":"","sources":["../../../../src/tools/gestures/handlers/swipe-scroll.ts"],"names":[],"mappings":"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"}

package/dist/tools/gestures/schema.d.ts

@@ -3,6 +3,8 @@ export declare const GESTURE_ACTIONS: readonly ["tap", "double_tap", "long_press
 export type GestureAction = (typeof GESTURE_ACTIONS)[number];
 export declare const SWIPE_SPEEDS: readonly ["slow", "normal", "fast"];
 export type SwipeSpeed = (typeof SWIPE_SPEEDS)[number];
+export declare const SCROLL_DISTANCE_PRESETS: readonly ["small", "medium", "large"];
+export type ScrollDistancePreset = (typeof SCROLL_DISTANCE_PRESETS)[number];
 export declare const LOCATOR_STRATEGIES: readonly ["xpath", "id", "name", "class name", "accessibility id", "css selector", "-android uiautomator", "-ios predicate string", "-ios class chain"];
 export declare const gestureSchema: z.ZodObject<{
     action: z.ZodEnum<{
@@ -45,6 +47,13 @@ export declare const gestureSchema: z.ZodObject<{
         "css selector": "css selector";
     }>>;
     selector: z.ZodOptional<z.ZodString>;
+    maxScrollAttempts: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    scrollDistance: z.ZodOptional<z.ZodNumber>;
+    scrollDistancePreset: z.ZodOptional<z.ZodEnum<{
+        small: "small";
+        medium: "medium";
+        large: "large";
+    }>>;
     sessionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type GestureArgs = z.infer<typeof gestureSchema>;

package/dist/tools/gestures/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/tools/gestures/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,eAAe,oGAQlB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,eAAO,MAAM,YAAY,qCAAsC,CAAC;AAChE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,kBAAkB,yJAUrB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmHxB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/tools/gestures/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,eAAe,oGAQlB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,eAAO,MAAM,YAAY,qCAAsC,CAAC;AAChE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,uBAAuB,uCAAwC,CAAC;AAC7E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,kBAAkB,yJAUrB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkJxB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/tools/gestures/schema.js

@@ -10,6 +10,7 @@ export const GESTURE_ACTIONS = [
     'scroll_to_element',
 ];
 export const SWIPE_SPEEDS = ['slow', 'normal', 'fast'];
+export const SCROLL_DISTANCE_PRESETS = ['small', 'medium', 'large'];
 export const LOCATOR_STRATEGIES = [
     'xpath',
     'id',
@@ -31,7 +32,9 @@ export const gestureSchema = z.object({
         `scroll: browse a list, feed, or page to reveal content. ` +
         `swipe: dismiss a card, switch screens or tabs, navigate a carousel, or pull-to-refresh (use speed=fast). ` +
         `pinch_zoom: zoom in (scale > 1) or out (scale < 1) on maps, images, or any zoomable view. ` +
-        `scroll_to_element: scroll until a specific element is on screen.`),
+        `scroll_to_element: scroll until a specific element is on screen (strategy + selector + direction up|down). ` +
+        `Stops when the element is found, page source is unchanged after a scroll (end of scrollable content), or maxScrollAttempts is reached. ` +
+        `Optional scrollDistance (0.05–1) or scrollDistancePreset (small|medium|large).`),
     elementUUID: elementUUIDScheme
         .optional()
         .describe(`UUID of the element to act on. Supports AI coordinate UUIDs (format: ai-element:x,y:bbox). ` +
@@ -102,6 +105,26 @@ export const gestureSchema = z.object({
         .string()
         .optional()
         .describe(`Locator selector value. Required for: scroll_to_element.`),
+    maxScrollAttempts: z
+        .number()
+        .int()
+        .min(1)
+        .max(80)
+        .optional()
+        .default(10)
+        .describe(`scroll_to_element only: maximum scroll attempts after the element is not yet visible (default 10).`),
+    scrollDistance: z
+        .number()
+        .min(0.05)
+        .max(1)
+        .optional()
+        .describe(`scroll_to_element only: vertical swipe length as a fraction 0.05–1 (same scale as legacy scroll). ` +
+        `Ignored when scrollDistancePreset is set. Default 0.45 if neither preset nor scrollDistance is set.`),
+    scrollDistancePreset: z
+        .enum(SCROLL_DISTANCE_PRESETS)
+        .optional()
+        .describe(`scroll_to_element only: convenience preset — small ≈ light nudge (0.25), medium ≈ 0.45, large = full default swipe (1). ` +
+        `When set, overrides scrollDistance.`),
     sessionId: z
         .string()
         .optional()

package/dist/tools/gestures/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/tools/gestures/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/tools/gestures/schema.ts"],"names":[],"mappings":"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"}

package/dist/tools/interactions/find.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/find.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;iBA+B5B,CAAC;AAEH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA+GzD"}
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/find.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;iBA+B5B,CAAC;AAEH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAiHzD"}

package/dist/tools/interactions/find.js

@@ -60,7 +60,9 @@ export default function findElement(server) {
 - AI_VISION_API_BASE_URL: Vision model API endpoint (required)
 - AI_VISION_API_KEY: API authentication key (required)
 - AI_VISION_MODEL: Model name (optional, defaults to Qwen3-VL-235B-A22B-Instruct)
-- AI_VISION_COORD_TYPE: Coordinate type (optional, defaults to normalized)`,
+- AI_VISION_COORD_TYPE: Coordinate type (optional, defaults to normalized)
+
+**Scrolling until an element appears**: use \`appium_gesture\` with \`action=scroll_to_element\` (same strategy + selector), not this tool.`,
         parameters: findElementSchema,
         annotations: {
             readOnlyHint: true,

package/dist/tools/interactions/find.js.map

@@ -1 +1 @@
-{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../src/tools/interactions/find.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../src/tools/interactions/find.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appium-mcp",
   "mcpName": "io.github.appium/appium-mcp",
-  "version": "1.66.0",
+  "version": "1.67.0",
   "type": "module",
   "repository": {
     "type": "git",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.appium/appium-mcp",
   "title": "MCP Appium - Mobile Development and Automation Server",
   "description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
-  "version": "1.66.0",
+  "version": "1.67.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "appium-mcp",
-      "version": "1.66.0",
+      "version": "1.67.0",
       "transport": {
         "type": "stdio"
       }

package/src/tools/gestures/handlers/scroll-to-element.ts

@@ -1,15 +1,33 @@
 import type { ContentResult } from 'fastmcp';
 import type { DriverInstance } from '../../../session-store.js';
-import { getPlatformName, PLATFORM } from '../../../session-store.js';
-import { execute, getWindowRect, performActions } from '../../../command.js';
+import { getPageSource } from '../../../command.js';
+import log from '../../../logger.js';
 import {
   errorResult,
   textResult,
   toolErrorMessage,
 } from '../../tool-response.js';
 import type { GestureArgs } from '../schema.js';
+import { performVerticalScroll } from './swipe-scroll.js';
 
-const MAX_SCROLL_ATTEMPTS = 10;
+const PRESET_TO_DISTANCE: Record<
+  NonNullable<GestureArgs['scrollDistancePreset']>,
+  number
+> = {
+  small: 0.25,
+  medium: 0.45,
+  large: 1,
+};
+
+function resolveScrollDistance(args: GestureArgs): number {
+  if (args.scrollDistancePreset) {
+    return PRESET_TO_DISTANCE[args.scrollDistancePreset];
+  }
+  if (args.scrollDistance !== undefined) {
+    return args.scrollDistance;
+  }
+  return 0.45;
+}
 
 async function tryFindElement(
   driver: DriverInstance,
@@ -24,45 +42,6 @@ async function tryFindElement(
   }
 }
 
-async function performW3CScroll(
-  driver: DriverInstance,
-  direction: 'up' | 'down'
-): Promise<void> {
-  const { width, height } = await getWindowRect(driver);
-  const startX = Math.floor(width / 2);
-  const startY =
-    direction === 'down' ? Math.floor(height * 0.8) : Math.floor(height * 0.2);
-  const endY =
-    direction === 'down' ? Math.floor(height * 0.2) : Math.floor(height * 0.8);
-
-  await performActions(driver, [
-    {
-      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: 600, x: startX, y: endY },
-        { type: 'pointerUp', button: 0 },
-      ],
-    },
-  ]);
-}
-
-async function scrollOnce(
-  driver: DriverInstance,
-  direction: 'up' | 'down'
-): Promise<void> {
-  const platform = getPlatformName(driver);
-  if (platform === PLATFORM.ios) {
-    await execute(driver, 'mobile: scroll', { direction });
-    return;
-  }
-  await performW3CScroll(driver, direction);
-}
-
 export async function handleScrollToElement(
   driver: DriverInstance,
   args: GestureArgs
@@ -77,6 +56,14 @@ export async function handleScrollToElement(
       ? args.direction
       : 'down';
 
+  const maxScroll = args.maxScrollAttempts;
+  if (args.scrollDistancePreset && args.scrollDistance !== undefined) {
+    log.warn(
+      'scroll_to_element: scrollDistancePreset is set; ignoring scrollDistance'
+    );
+  }
+  const distance = resolveScrollDistance(args);
+
   try {
     if (await tryFindElement(driver, args.strategy, args.selector)) {
       return textResult(
@@ -84,17 +71,34 @@ export async function handleScrollToElement(
       );
     }
 
-    for (let attempt = 1; attempt <= MAX_SCROLL_ATTEMPTS; attempt++) {
-      await scrollOnce(driver, direction);
+    let scrollsDone = 0;
+    while (scrollsDone < maxScroll) {
+      const xmlBefore = await getPageSource(driver);
+      try {
+        await performVerticalScroll(driver, { direction, distance });
+      } catch (scrollErr: unknown) {
+        return errorResult(
+          `Scroll failed during scroll_to_element: ${toolErrorMessage(scrollErr)}`
+        );
+      }
+      const xmlAfter = await getPageSource(driver);
+      scrollsDone++;
+
       if (await tryFindElement(driver, args.strategy, args.selector)) {
         return textResult(
-          `Successfully scrolled to element ${args.selector} after ${attempt} scroll(s).`
+          `Successfully scrolled to element ${args.selector} after ${scrollsDone} scroll(s).`
+        );
+      }
+
+      if (xmlBefore === xmlAfter) {
+        return errorResult(
+          `Element not found; page source did not change after scroll (likely end of scrollable content). selector=${args.selector}`
         );
       }
     }
 
     return errorResult(
-      `Element ${args.selector} not found after ${MAX_SCROLL_ATTEMPTS} scrolls in direction '${direction}'.`
+      `Element ${args.selector} not found after ${maxScroll} scroll(s) in direction '${direction}'.`
     );
   } catch (err) {
     return errorResult(`Failed to scroll_to_element. ${toolErrorMessage(err)}`);

package/src/tools/gestures/handlers/swipe-scroll.ts

@@ -26,6 +26,84 @@ interface Rect {
 
 const SCROLL_DURATION_MS = 800;
 const SCROLL_INITIAL_PAUSE_MS = 250;
+/** Pointer move duration for programmatic vertical scroll (matches legacy appium_scroll). */
+const VERTICAL_SCROLL_MOVE_MS = 600;
+
+function verticalScrollYs(
+  height: number,
+  direction: 'up' | 'down',
+  distance: number
+): { startY: number; endY: number } {
+  const mid = height * 0.5;
+  const halfSpan = height * 0.3 * distance;
+  if (direction === 'down') {
+    return {
+      startY: Math.floor(mid + halfSpan),
+      endY: Math.floor(mid - halfSpan),
+    };
+  }
+  return {
+    startY: Math.floor(mid - halfSpan),
+    endY: Math.floor(mid + halfSpan),
+  };
+}
+
+export type VerticalScrollOptions = {
+  direction: 'up' | 'down';
+  distance: number;
+};
+
+/**
+ * Vertical swipe in the middle of the window, scaled by `distance` (0.05–1).
+ * Used by `appium_gesture` `scroll_to_element`; matches legacy scroll distances.
+ */
+export async function performVerticalScroll(
+  driver: DriverInstance,
+  options: VerticalScrollOptions
+): Promise<void> {
+  const rect = await getWindowRect(driver);
+  const { width, height } = rect;
+  const startX = Math.floor(width / 2);
+  const { startY, endY } = verticalScrollYs(
+    height,
+    options.direction,
+    options.distance
+  );
+
+  if (getPlatformName(driver) === PLATFORM.android) {
+    await performActions(driver, [
+      {
+        type: 'pointer',
+        id: 'finger1',
+        parameters: { pointerType: 'touch' },
+        actions: [
+          { type: 'pointerMove', duration: 0, x: startX, y: startY },
+          { type: 'pointerDown', button: 0 },
+          { type: 'pause', duration: SCROLL_INITIAL_PAUSE_MS },
+          {
+            type: 'pointerMove',
+            duration: VERTICAL_SCROLL_MOVE_MS,
+            x: startX,
+            y: endY,
+          },
+          { type: 'pointerUp', button: 0 },
+        ],
+      },
+    ]);
+  } else if (getPlatformName(driver) === PLATFORM.ios) {
+    await execute(driver, 'mobile: scroll', {
+      direction: options.direction,
+      startX,
+      startY,
+      endX: startX,
+      endY,
+    });
+  } else {
+    throw new Error(
+      `Unsupported platform: ${getPlatformName(driver)}. Only Android and iOS are supported.`
+    );
+  }
+}
 
 const SWIPE_SPEED_PROFILES = {
   slow: { duration: 600, initialPause: 250 },

package/src/tools/gestures/schema.ts

@@ -16,6 +16,9 @@ export type GestureAction = (typeof GESTURE_ACTIONS)[number];
 export const SWIPE_SPEEDS = ['slow', 'normal', 'fast'] as const;
 export type SwipeSpeed = (typeof SWIPE_SPEEDS)[number];
 
+export const SCROLL_DISTANCE_PRESETS = ['small', 'medium', 'large'] as const;
+export type ScrollDistancePreset = (typeof SCROLL_DISTANCE_PRESETS)[number];
+
 export const LOCATOR_STRATEGIES = [
   'xpath',
   'id',
@@ -39,7 +42,9 @@ export const gestureSchema = z.object({
         `scroll: browse a list, feed, or page to reveal content. ` +
         `swipe: dismiss a card, switch screens or tabs, navigate a carousel, or pull-to-refresh (use speed=fast). ` +
         `pinch_zoom: zoom in (scale > 1) or out (scale < 1) on maps, images, or any zoomable view. ` +
-        `scroll_to_element: scroll until a specific element is on screen.`
+        `scroll_to_element: scroll until a specific element is on screen (strategy + selector + direction up|down). ` +
+        `Stops when the element is found, page source is unchanged after a scroll (end of scrollable content), or maxScrollAttempts is reached. ` +
+        `Optional scrollDistance (0.05–1) or scrollDistancePreset (small|medium|large).`
     ),
 
   elementUUID: elementUUIDScheme
@@ -139,6 +144,35 @@ export const gestureSchema = z.object({
     .optional()
     .describe(`Locator selector value. Required for: scroll_to_element.`),
 
+  maxScrollAttempts: z
+    .number()
+    .int()
+    .min(1)
+    .max(80)
+    .optional()
+    .default(10)
+    .describe(
+      `scroll_to_element only: maximum scroll attempts after the element is not yet visible (default 10).`
+    ),
+
+  scrollDistance: z
+    .number()
+    .min(0.05)
+    .max(1)
+    .optional()
+    .describe(
+      `scroll_to_element only: vertical swipe length as a fraction 0.05–1 (same scale as legacy scroll). ` +
+        `Ignored when scrollDistancePreset is set. Default 0.45 if neither preset nor scrollDistance is set.`
+    ),
+
+  scrollDistancePreset: z
+    .enum(SCROLL_DISTANCE_PRESETS)
+    .optional()
+    .describe(
+      `scroll_to_element only: convenience preset — small ≈ light nudge (0.25), medium ≈ 0.45, large = full default swipe (1). ` +
+        `When set, overrides scrollDistance.`
+    ),
+
   sessionId: z
     .string()
     .optional()

package/src/tools/interactions/find.ts

@@ -74,7 +74,9 @@ export default function findElement(server: FastMCP): void {
 - AI_VISION_API_BASE_URL: Vision model API endpoint (required)
 - AI_VISION_API_KEY: API authentication key (required)
 - AI_VISION_MODEL: Model name (optional, defaults to Qwen3-VL-235B-A22B-Instruct)
-- AI_VISION_COORD_TYPE: Coordinate type (optional, defaults to normalized)`,
+- AI_VISION_COORD_TYPE: Coordinate type (optional, defaults to normalized)
+
+**Scrolling until an element appears**: use \`appium_gesture\` with \`action=scroll_to_element\` (same strategy + selector), not this tool.`,
     parameters: findElementSchema,
     annotations: {
       readOnlyHint: true,