appium-mcp 1.71.5 → 1.71.6

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.71.6](https://github.com/appium/appium-mcp/compare/v1.71.5...v1.71.6) (2026-05-01)
+
+### Bug Fixes
+
+* add actions api to the java template ([#310](https://github.com/appium/appium-mcp/issues/310)) ([caebdd4](https://github.com/appium/appium-mcp/commit/caebdd41d21a51dbfaaa790952e2fc9ccc1e0c77))
+
 ## [1.71.5](https://github.com/appium/appium-mcp/compare/v1.71.4...v1.71.5) (2026-04-30)
 
 ### Bug Fixes

package/dist/resources/java/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../src/resources/java/template.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAAC,MAAM,EAAE,GAAG,QA+ExD"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../src/resources/java/template.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAAC,MAAM,EAAE,GAAG,QA6GxD"}

package/dist/resources/java/template.js

@@ -7,6 +7,7 @@ export default function javaTemplatesResource(server) {
         name: 'Generate Code With Locators',
         description: `Generate code for the current page with locators which was retrieved from generate_locators tool.
     The code should be generated in the same priorty order as the locators were generated.
+    Always use the actions API code from the template for the gestures.
     For iOS the priority order is:
       'id',
       'accessibility id',
@@ -73,6 +74,35 @@ public class locators {
     public locators(AppiumDriver driver) {
         PageFactory.initElements(new AppiumFieldDecorator(driver, Duration.ofSeconds(10)), this);
     }
+
+        @Test
+    public void sliderTest() {
+        WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
+        wait.until(ExpectedConditions.elementToBeClickable(AppiumBy.accessibilityId("login"))).click();
+        wait.until(ExpectedConditions.elementToBeClickable(AppiumBy.accessibilityId("slider1"))).click();
+
+        try { Thread.sleep(1000); } catch (InterruptedException e) {}
+
+        WebElement slider = wait.until(ExpectedConditions.visibilityOfElementLocated(AppiumBy.accessibilityId("slider")));
+
+        Point location = slider.getLocation();
+        Dimension size = slider.getSize();
+
+        // Swipe right: from left side of the slider to the right side
+        int startX = location.getX() + (int)(size.getWidth() * 0.1);
+        int endX = location.getX() + (int)(size.getWidth() * 0.9);
+        int y = location.getY() + size.getHeight() / 2;
+
+        PointerInput finger = new PointerInput(PointerInput.Kind.TOUCH, "finger");
+        Sequence swipe = new Sequence(finger, 1);
+
+        swipe.addAction(finger.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), startX, y));
+        swipe.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()));
+        swipe.addAction(finger.createPointerMove(Duration.ofMillis(600), PointerInput.Origin.viewport(), endX, y));
+        swipe.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
+
+        driver.perform(Collections.singletonList(swipe));
+    }
 }
     `,
             };

package/dist/resources/java/template.js.map

@@ -1 +1 @@
-{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/resources/java/template.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAAC,MAAW;IACvD,MAAM,CAAC,WAAW,CAAC;QACjB,GAAG,EAAE,+BAA+B;QACpC,IAAI,EAAE,6BAA6B;QACnC,WAAW,EAAE;;;;;;;;;;;;;;;sHAeqG;QAClH,QAAQ,EAAE,YAAY;QACtB,KAAK,CAAC,IAAI;YACR,uDAAuD;YACvD,OAAO;gBACL,OAAO,EACL,uFAAuF;gBACzF,WAAW,EACT,2DAA2D;gBAC7D,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA+CT;aACE,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/resources/java/template.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAAC,MAAW;IACvD,MAAM,CAAC,WAAW,CAAC;QACjB,GAAG,EAAE,+BAA+B;QACpC,IAAI,EAAE,6BAA6B;QACnC,WAAW,EAAE;;;;;;;;;;;;;;;;sHAgBqG;QAClH,QAAQ,EAAE,YAAY;QACtB,KAAK,CAAC,IAAI;YACR,uDAAuD;YACvD,OAAO;gBACL,OAAO,EACL,uFAAuF;gBACzF,WAAW,EACT,2DAA2D;gBAC7D,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4ET;aACE,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/test-generation/generate-tests.d.ts

@@ -1,3 +1,3 @@
-import { FastMCP } from 'fastmcp';
+import type { FastMCP } from 'fastmcp';
 export default function generateTest(server: FastMCP): void;
 //# sourceMappingURL=generate-tests.d.ts.map

package/dist/tools/test-generation/generate-tests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-tests.d.ts","sourceRoot":"","sources":["../../../src/tools/test-generation/generate-tests.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIlC,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAoC1D"}
+{"version":3,"file":"generate-tests.d.ts","sourceRoot":"","sources":["../../../src/tools/test-generation/generate-tests.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AAQtD,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAgD1D"}

package/dist/tools/test-generation/generate-tests.js

@@ -1,30 +1,42 @@
 import { z } from 'zod';
 import { textResult } from '../tool-response.js';
+const generateTestSchema = z.object({
+    steps: z.array(z.string()).describe('The steps of the test'),
+});
 export default function generateTest(server) {
-    const generateTestSchema = z.object({
-        steps: z.array(z.string()).describe('The steps of the test'),
-    });
     const instructions = (params) => [
         `## Instructions`,
         `- You are an Appium test generator.`,
-        `- You are given a scenario and you need to generate a appium test for it.`,
-        `- Request user to select the platform first using select_device tool and create a session`,
-        `- Use generate_locators tool to fetch all interactable elements from the current screen and use it to generate the tests`,
-        `- Element can only be clicked only if it is clickable.`,
-        `- Text can entered in the element only if it is focusable`,
-        `- If any interaction on element is failed, retry again with a differnt possible locator in the hierrarchy`,
-        `- Interact with the app using the tools provided and generate the test`,
-        '- DO NOT generate test code based on the scenario alone. DO run steps one by one using the tools provided instead.',
-        '- Only after all steps are completed, emit a Appium test based on message history',
-        '- Save generated test file in the tests directory',
-        `- Use generate://code-with-locators resource as reference for code generation`,
-        `- Always call find_element_tool to retrieve the element UUID before interacting with the element`,
+        `- You are given a scenario and you need to generate an Appium test for it.`,
+        ``,
+        `### Ordered workflow (use these exact MCP tool names)`,
+        `1. select_device — choose platform/device (local/embedded mode). Skip if the user already connected to a remote Appium URL (then use appium_session_management only).`,
+        `2. prepare_ios_simulator or appium_prepare_ios_real_device — only when iOS local setup requires it; otherwise skip.`,
+        `3. appium_session_management with action=create — start a driver session (match platform to select_device unless using remote server mode).`,
+        `4. appium_app_lifecycle or other session tools as needed (e.g. activate app, deep link) — only if the scenario requires it.`,
+        `5. Discover the target element — prefer appium_get_active_element when the focused field is enough; otherwise appium_find_element (strategy + selector, or ai_instruction when appropriate). Use generate_locators only for broad inspection/debugging, not for every step.`,
+        `6. Interact using the same tool names the server exposes, for example:`,
+        `   - appium_gesture with action=tap (or double_tap, long_press, scroll, swipe, scroll_to_element, pinch_zoom) — use the element id from appium_find_element when required`,
+        `   - appium_set_value — type into an element; optionally appium_mobile_press_key for special keys`,
+        `   - appium_get_text / appium_get_element_attribute when assertions need visible state`,
+        `- After appium_find_element, the first line of the response is elementId:<uuid> (or an ai-element coordinate token). Pass that value as elementUUID to gestures or appium_set_value as documented in each tool.`,
+        ``,
+        `- Use generate_locators to fetch interactable elements when you need full-screen locator lists for code generation; pairing with generate://code-with-locators is fine for templates.`,
+        `- An element can only be clicked if it is clickable.`,
+        `- Text can only be entered into an element if it is focusable (or use appium_set_value with w3cActions when typing into the focused element).`,
+        `- If an interaction fails, retry with a different possible locator in the hierarchy.`,
+        `- Interact with the app using the tools provided, then generate the test.`,
+        `- DO NOT generate test code from the scenario alone. DO run steps one by one with the tools listed above.`,
+        `- Only after all steps are completed, emit an Appium/WebdriverIO-style test based on the message history.`,
+        `- Save the generated test file in the tests directory.`,
+        `- Use the generate://code-with-locators resource as reference for code generation.`,
+        `- Always call appium_find_element (or appium_get_active_element when sufficient) to obtain elementId before tapping or setting value on a specific element.`,
         `Steps:`,
         ...params.steps.map((step, index) => `- ${index + 1}. ${step}`),
     ].join('\n');
     server.addTool({
         name: 'appium_generate_tests',
-        description: 'Generate tests for a given mobile app',
+        description: 'Generate tests for a mobile app: follow the returned instructions to drive the real session with MCP tools (select_device, appium_session_management, appium_find_element, appium_gesture, appium_set_value, etc.), then emit code. Use generate_locators only when you need a full locator snapshot; prefer appium_find_element for normal steps.',
         parameters: generateTestSchema,
         annotations: {
             readOnlyHint: false,

package/dist/tools/test-generation/generate-tests.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate-tests.js","sourceRoot":"","sources":["../../../src/tools/test-generation/generate-tests.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,MAAe;IAClD,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;QAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;KAC7D,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,CAAC,MAA2B,EAAE,EAAE,CACnD;QACE,iBAAiB;QACjB,qCAAqC;QACrC,2EAA2E;QAC3E,2FAA2F;QAC3F,0HAA0H;QAC1H,wDAAwD;QACxD,2DAA2D;QAC3D,2GAA2G;QAC3G,wEAAwE;QACxE,oHAAoH;QACpH,mFAAmF;QACnF,mDAAmD;QACnD,+EAA+E;QAC/E,kGAAkG;QAClG,QAAQ;QACR,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;KAChE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEf,MAAM,CAAC,OAAO,CAAC;QACb,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EAAE,uCAAuC;QACpD,UAAU,EAAE,kBAAkB;QAC9B,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,KAAK;SACrB;QACD,OAAO,EAAE,KAAK,EAAE,IAAS,EAAE,QAAa,EAAgB,EAAE,CACxD,UAAU,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;KAClD,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"generate-tests.js","sourceRoot":"","sources":["../../../src/tools/test-generation/generate-tests.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;CAC7D,CAAC,CAAC;AAEH,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,MAAe;IAClD,MAAM,YAAY,GAAG,CAAC,MAA2B,EAAE,EAAE,CACnD;QACE,iBAAiB;QACjB,qCAAqC;QACrC,4EAA4E;QAC5E,EAAE;QACF,uDAAuD;QACvD,uKAAuK;QACvK,qHAAqH;QACrH,6IAA6I;QAC7I,6HAA6H;QAC7H,6QAA6Q;QAC7Q,wEAAwE;QACxE,2KAA2K;QAC3K,mGAAmG;QACnG,wFAAwF;QACxF,iNAAiN;QACjN,EAAE;QACF,uLAAuL;QACvL,sDAAsD;QACtD,+IAA+I;QAC/I,sFAAsF;QACtF,2EAA2E;QAC3E,2GAA2G;QAC3G,2GAA2G;QAC3G,wDAAwD;QACxD,oFAAoF;QACpF,6JAA6J;QAC7J,QAAQ;QACR,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;KAChE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEf,MAAM,CAAC,OAAO,CAAC;QACb,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EACT,oVAAoV;QACtV,UAAU,EAAE,kBAAkB;QAC9B,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,KAAK;SACrB;QACD,OAAO,EAAE,KAAK,EACZ,IAAwC,EACxC,QAA6C,EACrB,EAAE,CAC1B,UAAU,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;KAClD,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appium-mcp",
   "mcpName": "io.github.appium/appium-mcp",
-  "version": "1.71.5",
+  "version": "1.71.6",
   "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.71.5",
+  "version": "1.71.6",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "appium-mcp",
-      "version": "1.71.5",
+      "version": "1.71.6",
       "transport": {
         "type": "stdio"
       }

package/src/resources/java/template.ts

@@ -7,6 +7,7 @@ export default function javaTemplatesResource(server: any) {
     name: 'Generate Code With Locators',
     description: `Generate code for the current page with locators which was retrieved from generate_locators tool.
     The code should be generated in the same priorty order as the locators were generated.
+    Always use the actions API code from the template for the gestures.
     For iOS the priority order is:
       'id',
       'accessibility id',
@@ -75,6 +76,35 @@ public class locators {
     public locators(AppiumDriver driver) {
         PageFactory.initElements(new AppiumFieldDecorator(driver, Duration.ofSeconds(10)), this);
     }
+
+        @Test
+    public void sliderTest() {
+        WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
+        wait.until(ExpectedConditions.elementToBeClickable(AppiumBy.accessibilityId("login"))).click();
+        wait.until(ExpectedConditions.elementToBeClickable(AppiumBy.accessibilityId("slider1"))).click();
+
+        try { Thread.sleep(1000); } catch (InterruptedException e) {}
+
+        WebElement slider = wait.until(ExpectedConditions.visibilityOfElementLocated(AppiumBy.accessibilityId("slider")));
+
+        Point location = slider.getLocation();
+        Dimension size = slider.getSize();
+
+        // Swipe right: from left side of the slider to the right side
+        int startX = location.getX() + (int)(size.getWidth() * 0.1);
+        int endX = location.getX() + (int)(size.getWidth() * 0.9);
+        int y = location.getY() + size.getHeight() / 2;
+
+        PointerInput finger = new PointerInput(PointerInput.Kind.TOUCH, "finger");
+        Sequence swipe = new Sequence(finger, 1);
+
+        swipe.addAction(finger.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), startX, y));
+        swipe.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()));
+        swipe.addAction(finger.createPointerMove(Duration.ofMillis(600), PointerInput.Origin.viewport(), endX, y));
+        swipe.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
+
+        driver.perform(Collections.singletonList(swipe));
+    }
 }
     `,
       };

package/src/tools/test-generation/generate-tests.ts

@@ -1,41 +1,57 @@
-import { FastMCP } from 'fastmcp';
+import type { ContentResult, FastMCP } from 'fastmcp';
 import { z } from 'zod';
 import { textResult } from '../tool-response.js';
 
-export default function generateTest(server: FastMCP): void {
-  const generateTestSchema = z.object({
-    steps: z.array(z.string()).describe('The steps of the test'),
-  });
+const generateTestSchema = z.object({
+  steps: z.array(z.string()).describe('The steps of the test'),
+});
 
+export default function generateTest(server: FastMCP): void {
   const instructions = (params: { steps: string[] }) =>
     [
       `## Instructions`,
       `- You are an Appium test generator.`,
-      `- You are given a scenario and you need to generate a appium test for it.`,
-      `- Request user to select the platform first using select_device tool and create a session`,
-      `- Use generate_locators tool to fetch all interactable elements from the current screen and use it to generate the tests`,
-      `- Element can only be clicked only if it is clickable.`,
-      `- Text can entered in the element only if it is focusable`,
-      `- If any interaction on element is failed, retry again with a differnt possible locator in the hierrarchy`,
-      `- Interact with the app using the tools provided and generate the test`,
-      '- DO NOT generate test code based on the scenario alone. DO run steps one by one using the tools provided instead.',
-      '- Only after all steps are completed, emit a Appium test based on message history',
-      '- Save generated test file in the tests directory',
-      `- Use generate://code-with-locators resource as reference for code generation`,
-      `- Always call find_element_tool to retrieve the element UUID before interacting with the element`,
+      `- You are given a scenario and you need to generate an Appium test for it.`,
+      ``,
+      `### Ordered workflow (use these exact MCP tool names)`,
+      `1. select_device — choose platform/device (local/embedded mode). Skip if the user already connected to a remote Appium URL (then use appium_session_management only).`,
+      `2. prepare_ios_simulator or appium_prepare_ios_real_device — only when iOS local setup requires it; otherwise skip.`,
+      `3. appium_session_management with action=create — start a driver session (match platform to select_device unless using remote server mode).`,
+      `4. appium_app_lifecycle or other session tools as needed (e.g. activate app, deep link) — only if the scenario requires it.`,
+      `5. Discover the target element — prefer appium_get_active_element when the focused field is enough; otherwise appium_find_element (strategy + selector, or ai_instruction when appropriate). Use generate_locators only for broad inspection/debugging, not for every step.`,
+      `6. Interact using the same tool names the server exposes, for example:`,
+      `   - appium_gesture with action=tap (or double_tap, long_press, scroll, swipe, scroll_to_element, pinch_zoom) — use the element id from appium_find_element when required`,
+      `   - appium_set_value — type into an element; optionally appium_mobile_press_key for special keys`,
+      `   - appium_get_text / appium_get_element_attribute when assertions need visible state`,
+      `- After appium_find_element, the first line of the response is elementId:<uuid> (or an ai-element coordinate token). Pass that value as elementUUID to gestures or appium_set_value as documented in each tool.`,
+      ``,
+      `- Use generate_locators to fetch interactable elements when you need full-screen locator lists for code generation; pairing with generate://code-with-locators is fine for templates.`,
+      `- An element can only be clicked if it is clickable.`,
+      `- Text can only be entered into an element if it is focusable (or use appium_set_value with w3cActions when typing into the focused element).`,
+      `- If an interaction fails, retry with a different possible locator in the hierarchy.`,
+      `- Interact with the app using the tools provided, then generate the test.`,
+      `- DO NOT generate test code from the scenario alone. DO run steps one by one with the tools listed above.`,
+      `- Only after all steps are completed, emit an Appium/WebdriverIO-style test based on the message history.`,
+      `- Save the generated test file in the tests directory.`,
+      `- Use the generate://code-with-locators resource as reference for code generation.`,
+      `- Always call appium_find_element (or appium_get_active_element when sufficient) to obtain elementId before tapping or setting value on a specific element.`,
       `Steps:`,
       ...params.steps.map((step, index) => `- ${index + 1}. ${step}`),
     ].join('\n');
 
   server.addTool({
     name: 'appium_generate_tests',
-    description: 'Generate tests for a given mobile app',
+    description:
+      'Generate tests for a mobile app: follow the returned instructions to drive the real session with MCP tools (select_device, appium_session_management, appium_find_element, appium_gesture, appium_set_value, etc.), then emit code. Use generate_locators only when you need a full locator snapshot; prefer appium_find_element for normal steps.',
     parameters: generateTestSchema,
     annotations: {
       readOnlyHint: false,
       openWorldHint: false,
     },
-    execute: async (args: any, _context: any): Promise<any> =>
+    execute: async (
+      args: z.infer<typeof generateTestSchema>,
+      _context: Record<string, unknown> | undefined
+    ): Promise<ContentResult> =>
       textResult(instructions({ steps: args.steps })),
   });
 }