appium-mcp 1.72.15 → 1.72.16

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.72.16](https://github.com/appium/appium-mcp/compare/v1.72.15...v1.72.16) (2026-05-14)
+
+### Bug Fixes
+
+* **ai:** enforce find_element instruction via Zod schema ([#329](https://github.com/appium/appium-mcp/issues/329)) ([a3bfe83](https://github.com/appium/appium-mcp/commit/a3bfe83576c6be9ec1ffa9371ab67b44cc86cc80))
+
 ## [1.72.15](https://github.com/appium/appium-mcp/compare/v1.72.14...v1.72.15) (2026-05-14)
 
 ### Bug Fixes

package/dist/tools/ai/handlers/find-element.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-element.d.ts","sourceRoot":"","sources":["../../../../src/tools/ai/handlers/find-element.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAShE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAK3C,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,CA+CxB"}
+{"version":3,"file":"find-element.d.ts","sourceRoot":"","sources":["../../../../src/tools/ai/handlers/find-element.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAShE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAM3C,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,CA0CxB"}

package/dist/tools/ai/handlers/find-element.js

@@ -7,12 +7,11 @@ import { errorResult, textResultWithPrimaryElementId, toolErrorMessage, } from '
 // Creating a new AIVisionFinder() on every call would reset the cache each time.
 let _finderInstance = null;
 export async function handleFindElement(driver, args) {
-    if (!args.instruction) {
-        return errorResult('instruction is required for action=find_element. ' +
-            'Example: { action: "find_element", instruction: "yellow search button at bottom" }');
-    }
+    // `instruction` presence/non-emptiness is enforced at schema level via
+    // `aiSchema.superRefine`. Narrow the optional type here for downstream calls.
+    const instruction = args.instruction;
     try {
-        log.info(`Finding element using AI with instruction: "${args.instruction}"`);
+        log.info(`Finding element using AI with instruction: "${instruction}"`);
         const screenshotBase64 = await getScreenshot(driver);
         const imageBuffer = Buffer.from(screenshotBase64, 'base64');
         const sharp = imageUtil.requireSharp();
@@ -22,7 +21,7 @@ export async function handleFindElement(driver, args) {
         }
         const { width, height } = metadata;
         const finder = getAIVisionFinder();
-        const result = await finder.findElement(screenshotBase64, args.instruction, width, height);
+        const result = await finder.findElement(screenshotBase64, instruction, width, height);
         // Format: "ai-element:{x},{y}:{bbox}" — consumed by appium_gesture handlers.
         const elementUUID = `ai-element:${result.center.x},${result.center.y}:${result.bbox.join(',')}`;
         let detail = `Successfully found "${result.target}" at coordinates (${result.center.x}, ${result.center.y}) using AI vision.`;

package/dist/tools/ai/handlers/find-element.js.map

@@ -1 +1 @@
-{"version":3,"file":"find-element.js","sourceRoot":"","sources":["../../../../src/tools/ai/handlers/find-element.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,GAAG,MAAM,oBAAoB,CAAC;AACrC,OAAO,EACL,WAAW,EACX,8BAA8B,EAC9B,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAGhC,4EAA4E;AAC5E,iFAAiF;AACjF,IAAI,eAAe,GAA0B,IAAI,CAAC;AAClD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAsB,EACtB,IAAY;IAEZ,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO,WAAW,CAChB,mDAAmD;YACjD,oFAAoF,CACvF,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,GAAG,CAAC,IAAI,CACN,+CAA+C,IAAI,CAAC,WAAW,GAAG,CACnE,CAAC;QAEF,MAAM,gBAAgB,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;QAErD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,SAAS,CAAC,YAAY,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,CAAC;QAErD,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;QAEnC,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CACrC,gBAAgB,EAChB,IAAI,CAAC,WAAW,EAChB,KAAK,EACL,MAAM,CACP,CAAC;QAEF,6EAA6E;QAC7E,MAAM,WAAW,GAAG,cAAc,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAEhG,IAAI,MAAM,GAAG,uBAAuB,MAAM,CAAC,MAAM,qBAAqB,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,oBAAoB,CAAC;QAC9H,IAAI,MAAM,CAAC,kBAAkB,EAAE,CAAC;YAC9B,MAAM,IAAI,kBAAkB,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC1D,CAAC;QAED,OAAO,8BAA8B,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,YAAY,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QAC3C,GAAG,CAAC,KAAK,CAAC,yBAAyB,EAAE,YAAY,CAAC,CAAC;QACnD,OAAO,WAAW,CAAC,kCAAkC,YAAY,EAAE,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB;IACxB,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,eAAe,GAAG,IAAI,cAAc,EAAE,CAAC;IACzC,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC"}
+{"version":3,"file":"find-element.js","sourceRoot":"","sources":["../../../../src/tools/ai/handlers/find-element.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,GAAG,MAAM,oBAAoB,CAAC;AACrC,OAAO,EACL,WAAW,EACX,8BAA8B,EAC9B,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAGhC,4EAA4E;AAC5E,iFAAiF;AACjF,IAAI,eAAe,GAA0B,IAAI,CAAC;AAElD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAsB,EACtB,IAAY;IAEZ,uEAAuE;IACvE,8EAA8E;IAC9E,MAAM,WAAW,GAAG,IAAI,CAAC,WAAqB,CAAC;IAE/C,IAAI,CAAC;QACH,GAAG,CAAC,IAAI,CAAC,+CAA+C,WAAW,GAAG,CAAC,CAAC;QAExE,MAAM,gBAAgB,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;QAErD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,SAAS,CAAC,YAAY,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,CAAC;QAErD,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;QAEnC,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CACrC,gBAAgB,EAChB,WAAW,EACX,KAAK,EACL,MAAM,CACP,CAAC;QAEF,6EAA6E;QAC7E,MAAM,WAAW,GAAG,cAAc,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAEhG,IAAI,MAAM,GAAG,uBAAuB,MAAM,CAAC,MAAM,qBAAqB,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,oBAAoB,CAAC;QAC9H,IAAI,MAAM,CAAC,kBAAkB,EAAE,CAAC;YAC9B,MAAM,IAAI,kBAAkB,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC1D,CAAC;QAED,OAAO,8BAA8B,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,YAAY,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QAC3C,GAAG,CAAC,KAAK,CAAC,yBAAyB,EAAE,YAAY,CAAC,CAAC;QACnD,OAAO,WAAW,CAAC,kCAAkC,YAAY,EAAE,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB;IACxB,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,eAAe,GAAG,IAAI,cAAc,EAAE,CAAC;IACzC,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/tools/ai/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU,2BAA4B,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,QAAQ;;;;;;iBAsBnB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/tools/ai/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU,2BAA4B,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,QAAQ;;;;;;iBAoCjB,CAAC;AAEL,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC"}

package/dist/tools/ai/schema.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 export const AI_ACTIONS = ['find_element'];
-export const aiSchema = z.object({
+export const aiSchema = z
+    .object({
     action: z
         .enum(AI_ACTIONS)
         .describe(`AI capability to invoke. ` +
@@ -16,5 +17,17 @@ export const aiSchema = z.object({
         .string()
         .optional()
         .describe('Session ID to target. If omitted, uses the active session.'),
+})
+    .superRefine((data, ctx) => {
+    if (data.action === 'find_element') {
+        if (!data.instruction?.trim()) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'instruction is required and must be non-empty when action is find_element. ' +
+                    'Example: { "action": "find_element", "instruction": "yellow search button at bottom" }',
+                path: ['instruction'],
+            });
+        }
+    }
 });
 //# sourceMappingURL=schema.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/tools/ai/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,cAAc,CAAU,CAAC;AAGpD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,MAAM,EAAE,CAAC;SACN,IAAI,CAAC,UAAU,CAAC;SAChB,QAAQ,CACP,2BAA2B;QACzB,4FAA4F;QAC5F,iHAAiH,CACpH;IAEH,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,sDAAsD;QACpD,8BAA8B;QAC9B,iHAAiH,CACpH;IAEH,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,4DAA4D,CAAC;CAC1E,CAAC,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/tools/ai/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,cAAc,CAAU,CAAC;AAGpD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC;KACtB,MAAM,CAAC;IACN,MAAM,EAAE,CAAC;SACN,IAAI,CAAC,UAAU,CAAC;SAChB,QAAQ,CACP,2BAA2B;QACzB,4FAA4F;QAC5F,iHAAiH,CACpH;IAEH,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,sDAAsD;QACpD,8BAA8B;QAC9B,iHAAiH,CACpH;IAEH,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,4DAA4D,CAAC;CAC1E,CAAC;KACD,WAAW,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;IACzB,IAAI,IAAI,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,CAAC;YAC9B,GAAG,CAAC,QAAQ,CAAC;gBACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;gBAC3B,OAAO,EACL,6EAA6E;oBAC7E,wFAAwF;gBAC1F,IAAI,EAAE,CAAC,aAAa,CAAC;aACtB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC,CAAC,CAAC"}

package/package.json

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

package/src/tools/ai/handlers/find-element.ts

@@ -14,21 +14,17 @@ import type { AIArgs } from '../schema.js';
 // Module-level singleton: ensures the LRU cache persists across tool calls.
 // Creating a new AIVisionFinder() on every call would reset the cache each time.
 let _finderInstance: AIVisionFinder | null = null;
+
 export async function handleFindElement(
   driver: DriverInstance,
   args: AIArgs
 ): Promise<ContentResult> {
-  if (!args.instruction) {
-    return errorResult(
-      'instruction is required for action=find_element. ' +
-        'Example: { action: "find_element", instruction: "yellow search button at bottom" }'
-    );
-  }
+  // `instruction` presence/non-emptiness is enforced at schema level via
+  // `aiSchema.superRefine`. Narrow the optional type here for downstream calls.
+  const instruction = args.instruction as string;
 
   try {
-    log.info(
-      `Finding element using AI with instruction: "${args.instruction}"`
-    );
+    log.info(`Finding element using AI with instruction: "${instruction}"`);
 
     const screenshotBase64 = await getScreenshot(driver);
 
@@ -45,7 +41,7 @@ export async function handleFindElement(
     const finder = getAIVisionFinder();
     const result = await finder.findElement(
       screenshotBase64,
-      args.instruction,
+      instruction,
       width,
       height
     );

package/src/tools/ai/schema.ts

@@ -3,28 +3,42 @@ import { z } from 'zod';
 export const AI_ACTIONS = ['find_element'] as const;
 export type AIAction = (typeof AI_ACTIONS)[number];
 
-export const aiSchema = z.object({
-  action: z
-    .enum(AI_ACTIONS)
-    .describe(
-      `AI capability to invoke. ` +
-        `find_element: locate an element from a natural-language description using a vision model. ` +
-        `Returns a coordinate UUID (format: ai-element:x,y:bbox) usable with appium_gesture (tap/double_tap/long_press).`
-    ),
+export const aiSchema = z
+  .object({
+    action: z
+      .enum(AI_ACTIONS)
+      .describe(
+        `AI capability to invoke. ` +
+          `find_element: locate an element from a natural-language description using a vision model. ` +
+          `Returns a coordinate UUID (format: ai-element:x,y:bbox) usable with appium_gesture (tap/double_tap/long_press).`
+      ),
 
-  instruction: z
-    .string()
-    .optional()
-    .describe(
-      `Natural-language description of the target element. ` +
-        `Required for: find_element. ` +
-        `Examples: "yellow search button at bottom", "username input field at top", "settings icon in top-right corner".`
-    ),
+    instruction: z
+      .string()
+      .optional()
+      .describe(
+        `Natural-language description of the target element. ` +
+          `Required for: find_element. ` +
+          `Examples: "yellow search button at bottom", "username input field at top", "settings icon in top-right corner".`
+      ),
 
-  sessionId: z
-    .string()
-    .optional()
-    .describe('Session ID to target. If omitted, uses the active session.'),
-});
+    sessionId: z
+      .string()
+      .optional()
+      .describe('Session ID to target. If omitted, uses the active session.'),
+  })
+  .superRefine((data, ctx) => {
+    if (data.action === 'find_element') {
+      if (!data.instruction?.trim()) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'instruction is required and must be non-empty when action is find_element. ' +
+            'Example: { "action": "find_element", "instruction": "yellow search button at bottom" }',
+          path: ['instruction'],
+        });
+      }
+    }
+  });
 
 export type AIArgs = z.infer<typeof aiSchema>;