@nbakka/mcp-appium 2.0.20 → 2.0.22

package/lib/app_context.txt

@@ -0,0 +1,21 @@
+When asked to open buy SRP, use deeplink to open https://housing.com/in/buy/mumbai/<locality name>. For example: if asked to open 'Mira Road East' buy SRP, then open this deeplink: https://housing.com/in/buy/mumbai/mira_road_east
+Homepage deeplink -> https://housing.com/in/buy/real-estate-mumbai
+Project dedicated page deeplink -> https://housing.com/in/buy/projects/page/319874-sunteck-sky-park-by-sunteck-realty-limited-in-mira-road-east
+Filters on the filter screen may initially be offscreen and require scrolling to view.
+Stop execution if any step fails.
+(Remember this properly - Very important) After the execution is successful/completed, do NOT analyze what you found or did; only generate Appium code.
+Print the Java/Appium code. In our framework, we use the following methods:
+- waitForElementToBeVisible("locator_key", Wait.SHORT); locator_key is locator key and wait can be SHORT, MEDIUM, or LONG.
+- scrollDown(n);  // n is the number of times to scroll.
+- navigateBack(); // for back action.
+- deepLink.OpenDeepLink("deeplink_key"); // deeplink_key is deeplink name.
+- getText("locator_key"); // to get text of element.
+Using the above, return code that looks like:
+deepLink.OpenDeepLink(deeplink); // deeplink -> https://housing.com
+waitForElementToBeVisible("view_on_map", Wait.LONG); // view_on_map=//android.widget.TextView[@text="View On Map"]; here xpath should be comments so it can be pasted in xpath sheet.
+When giving output, please remove escape characters before double quotes.
+Do similarly for click and sendKeys methods:
+- click("search_select")
+- sendKeys("locator_key", "string_to_be_passed", Wait.LONG)
+Figure out dynamic paths like //android.widget.TextView[@text="View 180 Properties"] here 180 is not constant so create a xpath like //android.widget.TextView[contains(@text,"View") and contains(@text,"Properties")]
+For repeating logic, create loops

package/lib/secret.json

@@ -0,0 +1,13 @@
+{
+  "type": "service_account",
+  "project_id": "gen-lang-client-0998595520",
+  "private_key_id": "99b60e861b2815a0b7e4946fa0697d70f157b4a6",
+  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCylqcylIgnlYFv\nSDSNA5w54FBTGKqwhg55bUYZoO3PYvXywgUDUO/q7jSLIYOLzQb+yiSKOBbJKTrs\ng/HP8Qr/vGoLJBXmEmhheh2YEip2uDERTeIaC9ilyWoDgRa8bWnj2DKUVlEAKK29\nK2cl7k3sejS9QNXW7b38ov3qb4uQK4tBy28rlUs2SpElNsMbO+RJOWxSuRqlWXER\nFD2alSmWB8ZB6ugHeOXsx5kKkNzDlS2wDKQJqZNWqga8LpSl+9lENrdi59qKuRgq\n053N5M/WLGJWyg8W2BWXMhZGCak1NcgPanQ/vFLO2mIljowb8mxtNML6rZfLawKp\nbFre03cZAgMBAAECggEAAJTwD4CfXu2kQc4M6cawvBmIeXTTnYaaRnf+Kfg1vh62\n6WcLaCLb3TqQbkGaMZrl4m+bJd4f6ODbAck+QOyqmgGtoMKp1ZmKwIKK1SN+Auv/\nsOw9h9MxDf01fLRvdAaxOR5Lr+MGGYeIZVzeVafMljAhutoauDwHCesoA5sAa+RP\nBzIa7+N6EmGt/FvAdKAvSuuZZsMUHLoOiHeB3knwjqoKJCHVMNWqpeMyqclIjR+O\nIv37jhlj2z7pbR0n6hfjYQLmGRfSRGvmw1hrDV1ije4RXeNs5/13gUokNf4kBhqn\nQ+t4eI6UEa82lgLS7Msmbcyyh2h2TfFG1Ygx6nYZHwKBgQDhUzdMjCtADBvQnSQw\nV+qWPzOJFdYzURgg1zMXUGnPws8vuUMjuCNEu3AUrtjvc5RVdePAIyN6o/j5HLAV\nt6qksoQkUas/daCzuRG9IWFw2eI0rhs+paMJVIUJQWXt60afgv61rsvLfIC/MBi9\ntl62xI8FNDWzPgSVWTXukIhOzwKBgQDK5p/3dr/S+oSk6E/y1bwejNm8b0VgqvwO\nP9OO2kmDEXTGSlXX5Mn1qW7Wg1n+z5NrDkA3IyRtEbILyylUELooGXVKiKPkiJpE\n+Qi+wsVqmThvqO6cYl8FW64/0UH88ZcvDjyDLfUsei4lY0hRjafTshaoqk0SOyq9\n4UOs3ioVlwKBgHYYtHoVWTHHZuivA+Gmopg+5dbqsArTbQ8BW5DTn7G5y/eaZRsa\njrmed/8PKTpPXKZyFH2GrTjBKmP+ajfnvLN3sRSMDXJER4cK78Yt8bFBMXMk8bii\n/dGND/Eq6q6JSsmd0bwNslijl6MdJUqBhCDM4pz6oU6hqatRR5gS/q43AoGBAIsp\nNGwQyS4V3mYQY80kpNq7NhdUpdvQSgIn6pzewG6hyVq63zes1oukQr3j5xSqH+zc\nIFTwyGn6KgiGtfjPZC5ej6CoKOh0fIJz33ies7ISFrAWyFj/6zYMlG12w3CN7mg6\ntmwuWCrCPeYsuwwcQRAj5ACYlTW82OrUlor48RpPAoGALtMf3SEALRuKvpSqDxpe\nw/XkD098Lq4g+uFbFfN0aL1gyuWvwQ4KtIkmMpENWYC/zFVH79AAWSA7gvEEWE0C\n3FP2lI29GgXPhG+EDS3/dvjY4UPcqDVMFYAen4Z4X0FnKa8Yr5rGPuYtZCsglGmh\nigkENMmOUL6T62YvJATeFd8=\n-----END PRIVATE KEY-----\n",
+  "client_email": "mcp-sheet-access@gen-lang-client-0998595520.iam.gserviceaccount.com",
+  "client_id": "104386077369721430122",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/mcp-sheet-access%40gen-lang-client-0998595520.iam.gserviceaccount.com",
+  "universe_domain": "googleapis.com"
+}

package/lib/server.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMcpServer = void 0;
+const fs = require('fs').promises;
+const path = require('path');
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const zod_1 = require("zod");
 const logger_1 = require("./logger");
@@ -10,28 +12,15 @@ const iphone_simulator_1 = require("./iphone-simulator");
 const ios_1 = require("./ios");
 const png_1 = require("./png");
 const image_utils_1 = require("./image-utils");
+const { google } = require('googleapis');
 const getAgentVersion = () => {
     const json = require("../package.json");
     return json.version;
 };
-
-const getLatestAgentVersion = async () => {
-    const response = await fetch("https://api.github.com/repos/mobile-next/mobile-mcp/tags?per_page=1");
-    const json = await response.json();
-    return json[0].name;
-};
-const checkForLatestAgentVersion = async () => {
-    try {
-        const latestVersion = await getLatestAgentVersion();
-        const currentVersion = getAgentVersion();
-        if (latestVersion !== currentVersion) {
-            (0, logger_1.trace)(`You are running an older version of the agent. Please update to the latest version: ${latestVersion}.`);
-        }
-    }
-    catch (error) {
-        // ignore
-    }
+const selectedSheetContext = {
+  sheetName: null,
 };
+
 const createMcpServer = () => {
     const server = new mcp_js_1.McpServer({
         name: "mobile-mcp",
@@ -41,6 +30,7 @@ const createMcpServer = () => {
             tools: {},
         },
     });
+
     const tool = (name, description, paramsSchema, cb) => {
         const wrappedCb = async (args) => {
             try {
@@ -76,6 +66,7 @@ const createMcpServer = () => {
             throw new robot_1.ActionableError("No device selected. Use the mobile_use_device tool to select a device.");
         }
     };
+
     tool("mobile_list_available_devices", "List all available devices. This includes both physical devices and simulators. If there is more than one device returned, you need to let the user select one of them.", {}, async ({}) => {
         const iosManager = new ios_1.IosManager();
         const androidManager = new android_1.AndroidDeviceManager();
@@ -101,6 +92,7 @@ const createMcpServer = () => {
         }
         return resp.join("\n");
     });
+
     tool("mobile_use_device", "Select a device to use. This can be a simulator or an Android device. Use the list_available_devices tool to get a list of available devices.", {
         device: zod_1.z.string().describe("The name of the device to select"),
         deviceType: zod_1.z.enum(["simulator", "ios", "android"]).describe("The type of device to select"),
@@ -118,11 +110,13 @@ const createMcpServer = () => {
         }
         return `Selected device: ${device}`;
     });
+
     tool("mobile_list_apps", "List all the installed apps on the device", {}, async ({}) => {
         requireRobot();
         const result = await robot.listApps();
         return `Found these apps on device: ${result.map(app => `${app.appName} (${app.packageName})`).join(", ")}`;
     });
+
     tool("mobile_launch_app", "Launch an app on mobile device. Use this to open a specific app. You can find the package name of the app by calling list_apps_on_device.", {
         packageName: zod_1.z.string().describe("The package name of the app to launch"),
     }, async ({ packageName }) => {
@@ -130,6 +124,7 @@ const createMcpServer = () => {
         await robot.launchApp(packageName);
         return `Launched app ${packageName}`;
     });
+
     tool("mobile_terminate_app", "Stop and terminate an app on mobile device", {
         packageName: zod_1.z.string().describe("The package name of the app to terminate"),
     }, async ({ packageName }) => {
@@ -137,54 +132,67 @@ const createMcpServer = () => {
         await robot.terminateApp(packageName);
         return `Terminated app ${packageName}`;
     });
+
     tool("mobile_get_screen_size", "Get the screen size of the mobile device in pixels", {}, async ({}) => {
         requireRobot();
         const screenSize = await robot.getScreenSize();
         return `Screen size is ${screenSize.width}x${screenSize.height} pixels`;
     });
-tool(
-  "mobile_learn_current_app_context",
-  "Follow this instructions strictly to navigate through the app. This should be the first step after launching the app and before performing any tests.",
-  {},
-  async () => {
-    const context = {
-      notes: ["when asked to open buy srp use deeeplink to open https://housing.com/in/buy/mumbai/<locality name> For eg: if asked to open 'Mira Road East' buy srp then open following deep link https://housing.com/in/buy/mumbai/mira_road_east", "homepade deeplink-> https://housing.com/in/buy/real-estate-mumbai and project dedicated page deeplink -> https://housing.com/in/buy/projects/page/319874-sunteck-sky-park-by-sunteck-realty-limited-in-mira-road-east",
-        "Filters on the filter screen may initially be offscreen and require scrolling to view.",
-"Stop execution if any step fails", "(Remember this properly - Very important)After the execution is successful/completed, no need to analyze what you found or what you did, only generate appium code",
-"print the java/appium code, in our framework we use following methods waitForElementToBeVisible(\"locator_key\", Wait.SHORT); locator_key is locator key and wait can be SHORT, MEDIUM and LONG, scrollDown(n); -> n is number of times to scroll, navigateBack() for back action, deepLink.OpenDeepLink(\"deeplink_key\") -> deeplink_key is deep link name, getText(\"locator_key\") -> to get text of element. Using the above return code that looks like deepLink.OpenDeepLink(deeplink); //deeplink -> https://housing.com \n waitForElementToBeVisible(\"view_on_map\", Wait.LONG); //view_on_map=//android.widget.TextView[@text=\"View On Map\"]; here xpath should be comments so that I can paste this in xpath sheet and when giving output please remove escape characters before double quotes, do similar for click and sendKeys methods click(\"search_select\") and sendKeys(\"locator_key\", \"string_to_be_passed\", Wait.LONG)",
-
-      ],
-    };
 
-    return `App context learned: ${JSON.stringify(context)}`;
-  }
-);
+    const fs = require('fs').promises;
+    const path = require('path');
 
+    tool(
+      "mobile_learn_current_app_context",
+      "Follow this instructions strictly to navigate through the app. This should be the first step after launching the app and before performing any tests.",
+      {},
+      async () => {
+        try {
+          // Read file from config folder
+          const filePath = path.join(__dirname, 'lib', 'app_context.txt');
+          const fileContent = await fs.readFile(filePath, 'utf-8');
 
-tool("mobile_list_elements_on_screen", "List elements on screen and their coordinates, with display text or accessibility label. Do not cache this result.", {}, async ({}) => {
-        requireRobot();
-        const elements = await robot.getElementsOnScreen();
-        const result = elements.map(element => {
-            const out = {
-                type: element.type,
-                text: element.text,
-                label: element.label,
-                name: element.name,
-                value: element.value,
-                coordinates: {
-                    x: element.rect.x,
-                    y: element.rect.y,
-                    width: element.rect.width,
-                    height: element.rect.height,
-                },
-            };
-            if (element.focused) {
-                out.focused = true;
-            }
-            return out;
+          // Assuming each note is separated by a newline
+          // Trim to remove empty lines, filter out blank lines
+          const notes = fileContent
+            .split('\n')
+            .map(line => line.trim())
+            .filter(line => line.length > 0);
+
+          const context = { notes };
+
+          return `App context learned: ${JSON.stringify(context)}`;
+        } catch (error) {
+          // Handle file read errors gracefully
+          return `Error reading app context notes: ${error.message}`;
+        }
+      }
+    );
+
+    tool("mobile_list_elements_on_screen", "List elements on screen and their coordinates, with display text or accessibility label. Do not cache this result.", {}, async ({}) => {
+            requireRobot();
+            const elements = await robot.getElementsOnScreen();
+            const result = elements.map(element => {
+                const out = {
+                    type: element.type,
+                    text: element.text,
+                    label: element.label,
+                    name: element.name,
+                    value: element.value,
+                    coordinates: {
+                        x: element.rect.x,
+                        y: element.rect.y,
+                        width: element.rect.width,
+                        height: element.rect.height,
+                    },
+                };
+                if (element.focused) {
+                    out.focused = true;
+                }
+                return out;
+            });
+            return `Found these elements on screen: ${JSON.stringify(result)}`;
         });
-        return `Found these elements on screen: ${JSON.stringify(result)}`;
-    });
 
     tool("mobile_press_button", "Press a button on device", {
         button: zod_1.z.string().describe("The button to press. Supported buttons: BACK (android only), HOME, VOLUME_UP, VOLUME_DOWN, ENTER, DPAD_CENTER (android tv only), DPAD_UP (android tv only), DPAD_DOWN (android tv only), DPAD_LEFT (android tv only), DPAD_RIGHT (android tv only)"),
@@ -193,14 +201,16 @@ tool("mobile_list_elements_on_screen", "List elements on screen and their coordi
         await robot.pressButton(button);
         return `Pressed the button: ${button}`;
     });
+
     tool("mobile_open_url", "Open a URL in browser on device", {
         url: zod_1.z.string().describe("The URL to open"),
     }, async ({ url }) => {
         requireRobot();
         await robot.openUrl(url);
-await new Promise(resolve => setTimeout(resolve, 5000));
+        await new Promise(resolve => setTimeout(resolve, 5000));
         return `Opened URL: ${url}`;
     });
+
     tool("swipe_on_screen", "Swipe on the screen", {
         direction: zod_1.z.enum(["up", "down"]).describe("The direction to swipe, up direction means it will from bottom part of the screen to top part of screen, essentially moving the screen content up and opposite happens for down"),
     }, async ({ direction }) => {
@@ -208,6 +218,7 @@ await new Promise(resolve => setTimeout(resolve, 5000));
         await robot.swipe(direction);
         return `Swiped ${direction} on screen`;
     });
+
     tool("mobile_type_keys", "Type text into the focused element", {
         text: zod_1.z.string().describe("The text to type"),
         submit: zod_1.z.boolean().describe("Whether to submit the text. If true, the text will be submitted as if the user pressed the enter key."),
@@ -219,6 +230,7 @@ await new Promise(resolve => setTimeout(resolve, 5000));
         }
         return `Typed text: ${text}`;
     });
+
     tool("mobile_set_orientation", "Change the screen orientation of the device", {
         orientation: zod_1.z.enum(["portrait", "landscape"]).describe("The desired orientation"),
     }, async ({ orientation }) => {
@@ -226,44 +238,119 @@ await new Promise(resolve => setTimeout(resolve, 5000));
         await robot.setOrientation(orientation);
         return `Changed device orientation to ${orientation}`;
     });
+
     tool("mobile_get_orientation", "Get the current screen orientation of the device", {}, async () => {
         requireRobot();
         const orientation = await robot.getOrientation();
         return `Current device orientation is ${orientation}`;
     });
-tool(
-  "mobile_tap_by_text",
-  "Tap an element on screen by its displayed text or accessibility label using ADB tap",
-  {
-    text: zod_1.z.string().describe("The exact text or label of the element to tap"),
-  },
-  async ({ text }) => {
-    if (!text) throw new Error("Input text is required");
-
-    requireRobot(); // ensure robot instance available
-    const elements = await robot.getElementsOnScreen();
-
-    // Find element by exact match on text or label
-    const element = elements.find(
-      el => el.text === text || el.label === text
+
+    tool(
+      "mobile_tap_by_text",
+      "Tap an element on screen by its displayed text or accessibility label using ADB tap",
+      {
+        text: zod_1.z.string().describe("The exact text or label of the element to tap"),
+      },
+      async ({ text }) => {
+        if (!text) throw new Error("Input text is required");
+
+        requireRobot(); // ensure robot instance available
+        const elements = await robot.getElementsOnScreen();
+
+        // Find element by exact match on text or label
+        const element = elements.find(
+          el => el.text === text || el.label === text
+        );
+
+        if (!element) throw new Error(`Element with text or label "${text}" not found`);
+
+        // Calculate center coordinates
+        const rect = element.rect;
+        const x = Math.floor(rect.x + rect.width / 2);
+        const y = Math.floor(rect.y + rect.height / 2);
+
+        // Execute adb tap
+        const { execSync } = require("child_process");
+        execSync(`adb shell input tap ${x} ${y}`);
+
+        return `Tapped element with text/label "${text}" at (${x},${y})`;
+      }
     );
 
-    if (!element) throw new Error(`Element with text or label "${text}" not found`);
+    tool(
+      "select_google_sheet",
+      "MUST be called after mobile_learn_current_app_context to set the Google Sheet name to be used by fetch_google_sheet_locators.",
+      {
+        sheetName: { type: "string", description: "Name of the sheet/tab to fetch from" }
+      },
+      async ({ sheetName }) => {
+        if (!sheetName) {
+          return "Error: sheetName is required.";
+        }
+        selectedSheetContext.sheetName = sheetName.trim();
+        return `Sheet name "${selectedSheetContext.sheetName}" saved. Now call fetch_google_sheet_locators to fetch data.`;
+      }
+    );
 
-    // Calculate center coordinates
-    const rect = element.rect;
-    const x = Math.floor(rect.x + rect.width / 2);
-    const y = Math.floor(rect.y + rect.height / 2);
+    // Tool 2: fetch locator data using previously selected sheet name
+    tool(
+      "fetch_google_sheet_locators",
+      "MUST be called after select_google_sheet. Fetch locatorName and androidLocator from the sheet set by select_google_sheet. Please call select_google_sheet first.",
+      {},
+      async () => {
+        const sheetName = selectedSheetContext.sheetName;
+        if (!sheetName) {
+          return "Error: Sheet name not set. Please call select_google_sheet first.";
+        }
+
+        try {
+          const fs = require('fs').promises;
+          const path = require('path');
+          const { google } = require('googleapis');
+
+          // Load credentials
+          const keyFile = path.join(__dirname, 'lib', 'secret.json');
+          const credentials = JSON.parse(await fs.readFile(keyFile, 'utf-8'));
+
+          const auth = new google.auth.GoogleAuth({
+            credentials,
+            scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'],
+          });
+
+          const authClient = await auth.getClient();
+          const sheets = google.sheets({ version: 'v4', auth: authClient });
+          const spreadsheetId = '1UapR81AxaztDUlPGDV-_EwHo2hWXkKCZXl8ALsvIyxA';
+
+          const range = `${sheetName}!A1:Z1000`;
+          const res = await sheets.spreadsheets.values.get({ spreadsheetId, range });
+          const rows = res.data.values;
 
-    // Execute adb tap
-    const { execSync } = require("child_process");
-    execSync(`adb shell input tap ${x} ${y}`);
+          if (!rows || rows.length === 0) {
+            return `Sheet "${sheetName}" is empty or does not exist.`;
+          }
+
+          const header = rows[0].map(h => h.toString().toLowerCase());
+          const locatorNameIdx = header.indexOf('locatorName');
+          const androidLocatorIdx = header.findIndex(h => h === 'android xpath' || h === 'androidLocator');
+
+          if (locatorNameIdx === -1 || androidLocatorIdx === -1) {
+            return `Required columns "locatorName" and/or "androidXpath" not found in sheet "${sheetName}".`;
+          }
+
+          const extracted = rows.slice(1)
+            .filter(row => row[locatorNameIdx] && row[androidLocatorIdx])
+            .map(row => ({
+              locatorName: row[locatorNameIdx],
+              androidLocator: row[androidLocatorIdx],
+            }));
+
+          return extracted;
+        } catch (error) {
+          return `Error fetching data from Google Sheets: ${error.message}`;
+        }
+      }
+    );
 
-    return `Tapped element with text/label "${text}" at (${x},${y})`;
-  }
-);
-    // async check for latest agent version
-    checkForLatestAgentVersion().then();
     return server;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nbakka/mcp-appium",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Appium MCP",
   "engines": {
     "node": ">=18"
@@ -20,7 +20,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.6.1",
     "fast-xml-parser": "^5.0.9",
-    "zod-to-json-schema": "^3.24.4"
+    "zod-to-json-schema": "^3.24.4",
+    "googleapis": "^39.2.0"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",