@browserstack/mcp-server 1.2.4 → 1.2.5

package/README.md

@@ -35,9 +35,12 @@ Manage, execute, debug tests, and even fix code using plain English prompts.
 #### Reduced context switching:
 Stay in flow—keep all project context in one place and trigger actions directly from your IDE or LLM.
 
-## ⚡️ One Click MCP Setup
+## ⚡️ One Click MCP Setup  
+
+Click on the buttons below to install MCP in your respective IDE:
+
+<a href="http://mcp.browserstack.com/one-click-setup?client=vscode"><img src="assets/one-click-vs-code.png" alt="Install in VS Code" width="160" height="80"></a>&nbsp;&nbsp;&nbsp;<a href="http://mcp.browserstack.com/one-click-setup?client=cursor"><img src="assets/one-click-cursor.png" alt="Install in Cursor" width="150" height="70"></a>
 
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](http://mcp.browserstack.com/one-click-setup?client=vscode) &nbsp; [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-24bfa5?style=flat-square&color=000000&logo=visualstudiocode&logoColor=white)](http://mcp.browserstack.com/one-click-setup?client=cursor)
 #### Note : Ensure you are using Node version >= `18.0` 
 - Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
 - To Upgrade Node :
@@ -156,8 +159,9 @@ Generate test cases from PRDs, convert manual tests to low-code automation, and
    
 ### **One Click MCP Setup**
 
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](http://mcp.browserstack.com/one-click-setup?client=vscode) &nbsp; [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-24bfa5?style=flat-square&color=000000&logo=visualstudiocode&logoColor=white)](http://mcp.browserstack.com/one-click-setup?client=cursor)
+Click on the buttons below to install MCP in your respective IDE:
 
+<a href="http://mcp.browserstack.com/one-click-setup?client=vscode"><img src="assets/one-click-vs-code.png" alt="Install in VS Code" width="160" height="80"></a>&nbsp;&nbsp;&nbsp;<a href="http://mcp.browserstack.com/one-click-setup?client=cursor"><img src="assets/one-click-cursor.png" alt="Install in Cursor" width="150" height="70"></a>
 
 ### **Alternate ways to Setup MCP server**
 
@@ -418,14 +422,14 @@ As of now we support 20 tools.
   **Prompt example**
 
   ```text
-  Take a screenshot of my app on Google Pixel 6 with Android 14 while testing on App Automate. App file path: /Users/xyz/app-debug.apk
+  Take a screenshot of my app on Google Pixel 6 with Android 12 while testing on App Automate. App file path: /Users/xyz/app-debug.apk
   ```
 
  15. `runAppTestsOnBrowserStack` — Run automated mobile tests (Espresso/XCUITest, etc.) on real devices.
   **Prompt example**
 
   ```text
-  Run Espresso tests from /tests/checkout.zip on Galaxy S21 and Pixel 6 with Android 14. App path is /apps/beta-release.apk under project 'Checkout Flow'
+  Run Espresso tests from /tests/checkout.zip on Galaxy S21 and Pixel 6 with Android 12. App path is /apps/beta-release.apk under project 'Checkout Flow'
   ```
 
 ---

package/dist/lib/apiClient.d.ts

@@ -4,6 +4,7 @@ type RequestOptions = {
     headers?: Record<string, string>;
     params?: Record<string, string | number>;
     body?: any;
+    timeout?: number;
     raise_error?: boolean;
 };
 declare class ApiResponse<T = any> {
@@ -20,12 +21,13 @@ declare class ApiResponse<T = any> {
 declare class ApiClient {
     private instance;
     private get axiosAgent();
+    private validateUrl;
     private requestWrapper;
-    get<T = any>({ url, headers, params, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
-    post<T = any>({ url, headers, body, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
-    put<T = any>({ url, headers, body, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
-    patch<T = any>({ url, headers, body, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
-    delete<T = any>({ url, headers, params, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    get<T = any>({ url, headers, params, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    post<T = any>({ url, headers, body, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    put<T = any>({ url, headers, body, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    patch<T = any>({ url, headers, body, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
+    delete<T = any>({ url, headers, params, timeout, raise_error, }: RequestOptions): Promise<ApiResponse<T>>;
 }
 export declare const apiClient: ApiClient;
 export type { ApiResponse, RequestOptions };

package/dist/lib/apiClient.js

@@ -4,6 +4,7 @@ const { HttpsProxyAgent } = httpsProxyAgentPkg;
 import * as https from "https";
 import * as fs from "fs";
 import config from "../config.js";
+import { isDataUrlPayloadTooLarge } from "../lib/utils.js";
 class ApiResponse {
     _response;
     constructor(response) {
@@ -77,8 +78,38 @@ class ApiClient {
     get axiosAgent() {
         return getAxiosAgent();
     }
-    async requestWrapper(fn, raise_error = true) {
+    validateUrl(url, options) {
         try {
+            const parsedUrl = new URL(url);
+            // Default safe limits
+            const maxContentLength = options?.maxContentLength ?? 20 * 1024 * 1024; // 20MB
+            const maxBodyLength = options?.maxBodyLength ?? 20 * 1024 * 1024; // 20MB
+            const maxUrlLength = 8000; // cutoff for URLs
+            // Check overall URL length
+            if (url.length > maxUrlLength) {
+                throw new Error(`URL length exceeds maxUrlLength (${maxUrlLength} chars)`);
+            }
+            if (parsedUrl.protocol === "data:") {
+                // Either reject completely OR check payload size
+                if (isDataUrlPayloadTooLarge(url, maxContentLength)) {
+                    throw new Error("data: URI payload too large or invalid");
+                }
+            }
+            else if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+                throw new Error(`Unsupported URL scheme: ${parsedUrl.protocol}`);
+            }
+            if (options?.data &&
+                Buffer.byteLength(JSON.stringify(options.data), "utf8") > maxBodyLength) {
+                throw new Error(`Request body exceeds maxBodyLength (${maxBodyLength} bytes)`);
+            }
+        }
+        catch (error) {
+            throw new Error(`Invalid URL: ${error.message}`);
+        }
+    }
+    async requestWrapper(fn, url, config, raise_error = true) {
+        try {
+            this.validateUrl(url, config);
             const res = await fn(this.axiosAgent);
             return new ApiResponse(res);
         }
@@ -89,20 +120,50 @@ class ApiClient {
             throw error;
         }
     }
-    async get({ url, headers, params, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.get(url, { headers, params, httpsAgent: agent }), raise_error);
-    }
-    async post({ url, headers, body, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.post(url, body, { headers, httpsAgent: agent }), raise_error);
-    }
-    async put({ url, headers, body, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.put(url, body, { headers, httpsAgent: agent }), raise_error);
-    }
-    async patch({ url, headers, body, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.patch(url, body, { headers, httpsAgent: agent }), raise_error);
-    }
-    async delete({ url, headers, params, raise_error = true, }) {
-        return this.requestWrapper((agent) => this.instance.delete(url, { headers, params, httpsAgent: agent }), raise_error);
+    async get({ url, headers, params, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            params,
+            timeout,
+            httpsAgent: this.axiosAgent,
+        };
+        return this.requestWrapper(() => this.instance.get(url, config), url, config, raise_error);
+    }
+    async post({ url, headers, body, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            timeout,
+            httpsAgent: this.axiosAgent,
+            data: body,
+        };
+        return this.requestWrapper(() => this.instance.post(url, config.data, config), url, config, raise_error);
+    }
+    async put({ url, headers, body, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            timeout,
+            httpsAgent: this.axiosAgent,
+            data: body,
+        };
+        return this.requestWrapper(() => this.instance.put(url, config.data, config), url, config, raise_error);
+    }
+    async patch({ url, headers, body, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            timeout,
+            httpsAgent: this.axiosAgent,
+            data: body,
+        };
+        return this.requestWrapper(() => this.instance.patch(url, config.data, config), url, config, raise_error);
+    }
+    async delete({ url, headers, params, timeout, raise_error = true, }) {
+        const config = {
+            headers,
+            params,
+            timeout,
+            httpsAgent: this.axiosAgent,
+        };
+        return this.requestWrapper(() => this.instance.delete(url, config), url, config, raise_error);
     }
 }
 export const apiClient = new ApiClient();

package/dist/lib/device-cache.d.ts

@@ -1,7 +1,9 @@
 export declare enum BrowserStackProducts {
     LIVE = "live",
     APP_LIVE = "app_live",
-    APP_AUTOMATE = "app_automate"
+    APP_AUTOMATE = "app_automate",
+    SELENIUM_AUTOMATE = "selenium_automate",
+    PLAYWRIGHT_AUTOMATE = "playwright_automate"
 }
 /**
  * Fetches and caches BrowserStack datasets (live + app_live + app_automate) with a shared TTL.

package/dist/lib/device-cache.js

@@ -12,11 +12,15 @@ export var BrowserStackProducts;
     BrowserStackProducts["LIVE"] = "live";
     BrowserStackProducts["APP_LIVE"] = "app_live";
     BrowserStackProducts["APP_AUTOMATE"] = "app_automate";
+    BrowserStackProducts["SELENIUM_AUTOMATE"] = "selenium_automate";
+    BrowserStackProducts["PLAYWRIGHT_AUTOMATE"] = "playwright_automate";
 })(BrowserStackProducts || (BrowserStackProducts = {}));
 const URLS = {
     [BrowserStackProducts.LIVE]: "https://www.browserstack.com/list-of-browsers-and-platforms/live.json",
     [BrowserStackProducts.APP_LIVE]: "https://www.browserstack.com/list-of-browsers-and-platforms/app_live.json",
     [BrowserStackProducts.APP_AUTOMATE]: "https://www.browserstack.com/list-of-browsers-and-platforms/app_automate.json",
+    [BrowserStackProducts.SELENIUM_AUTOMATE]: "https://www.browserstack.com/list-of-browsers-and-platforms/automate.json",
+    [BrowserStackProducts.PLAYWRIGHT_AUTOMATE]: "https://www.browserstack.com/list-of-browsers-and-platforms/playwright.json",
 };
 /**
  * Fetches and caches BrowserStack datasets (live + app_live + app_automate) with a shared TTL.

package/dist/lib/instrumentation.js

@@ -3,7 +3,7 @@ import { getBrowserStackAuth } from "./get-auth.js";
 import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 const packageJson = require("../../package.json");
-import axios from "axios";
+import { apiClient } from "./apiClient.js";
 import globalConfig from "../config.js";
 export function trackMCP(toolName, clientInfo, error, config) {
     const instrumentationEndpoint = "https://api.browserstack.com/sdk/v1/event";
@@ -38,13 +38,16 @@ export function trackMCP(toolName, clientInfo, error, config) {
         const authString = getBrowserStackAuth(config);
         authHeader = `Basic ${Buffer.from(authString).toString("base64")}`;
     }
-    axios
-        .post(instrumentationEndpoint, event, {
+    apiClient
+        .post({
+        url: instrumentationEndpoint,
+        body: event,
         headers: {
             "Content-Type": "application/json",
             ...(authHeader ? { Authorization: authHeader } : {}),
         },
         timeout: 2000,
+        raise_error: false,
     })
         .catch(() => { });
 }

package/dist/lib/utils.d.ts

@@ -1,9 +1,82 @@
 import type { ApiResponse } from "./apiClient.js";
 import { BrowserStackConfig } from "./types.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 export declare function sanitizeUrlParam(param: string): string;
 export declare function maybeCompressBase64(base64: string): Promise<string>;
 export declare function assertOkResponse(response: Response | ApiResponse, action: string): Promise<void>;
 export declare function fetchFromBrowserStackAPI(url: string, config: BrowserStackConfig): Promise<any>;
-export declare function handleMCPError(toolName: string, server: McpServer, config: BrowserStackConfig, error: unknown): CallToolResult;
+export declare function handleMCPError(toolName: string, server: McpServer, config: BrowserStackConfig, error: unknown): {
+    [x: string]: unknown;
+    content: ({
+        [x: string]: unknown;
+        type: "text";
+        text: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "image";
+        data: string;
+        mimeType: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "audio";
+        data: string;
+        mimeType: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "resource_link";
+        name: string;
+        uri: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        mimeType?: string | undefined;
+        title?: string | undefined;
+        description?: string | undefined;
+        icons?: {
+            [x: string]: unknown;
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string | undefined;
+        }[] | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "resource";
+        resource: {
+            [x: string]: unknown;
+            text: string;
+            uri: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            mimeType?: string | undefined;
+        } | {
+            [x: string]: unknown;
+            uri: string;
+            blob: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            mimeType?: string | undefined;
+        };
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    })[];
+    _meta?: {
+        [x: string]: unknown;
+    } | undefined;
+    structuredContent?: {
+        [x: string]: unknown;
+    } | undefined;
+    isError?: boolean | undefined;
+};
+export declare function isDataUrlPayloadTooLarge(dataUrl: string, maxBytes: number): boolean;

package/dist/lib/utils.js

@@ -51,3 +51,23 @@ export function handleMCPError(toolName, server, config, error) {
     const readableToolName = toolName.replace(/([A-Z])/g, " $1").toLowerCase();
     return errorContent(`Failed to ${readableToolName}: ${errorMessage}. Please open an issue on GitHub if the problem persists`);
 }
+export function isDataUrlPayloadTooLarge(dataUrl, maxBytes) {
+    const commaIndex = dataUrl.indexOf(",");
+    if (commaIndex === -1)
+        return true; // malformed
+    const meta = dataUrl.slice(0, commaIndex);
+    const payload = dataUrl.slice(commaIndex + 1);
+    const isBase64 = /;base64$/i.test(meta);
+    if (!isBase64) {
+        try {
+            const decoded = decodeURIComponent(payload);
+            return Buffer.byteLength(decoded, "utf8") > maxBytes;
+        }
+        catch {
+            return true;
+        }
+    }
+    const padding = payload.endsWith("==") ? 2 : payload.endsWith("=") ? 1 : 0;
+    const decodedBytes = Math.floor((payload.length * 3) / 4) - padding;
+    return decodedBytes > maxBytes;
+}

package/dist/lib/version-resolver.js

@@ -20,26 +20,38 @@ export function resolveVersion(requested, available) {
         const lex = uniq.slice().sort();
         return requested === "latest" ? lex[lex.length - 1] : lex[0];
     }
-    // exact?
+    // exact match?
     if (uniq.includes(requested)) {
         return requested;
     }
-    // try closest numeric
+    // Try major version matching (e.g., "14" matches "14.0", "14.1", etc.)
     const reqNum = parseFloat(requested);
-    const nums = uniq
-        .map((v) => ({ v, n: parseFloat(v) }))
-        .filter((x) => !isNaN(x.n));
-    if (!isNaN(reqNum) && nums.length) {
-        let best = nums[0], bestDiff = Math.abs(nums[0].n - reqNum);
-        for (const x of nums) {
-            const d = Math.abs(x.n - reqNum);
-            if (d < bestDiff) {
-                best = x;
-                bestDiff = d;
+    if (!isNaN(reqNum)) {
+        const majorVersionMatches = uniq.filter((v) => {
+            const vNum = parseFloat(v);
+            return !isNaN(vNum) && Math.floor(vNum) === Math.floor(reqNum);
+        });
+        if (majorVersionMatches.length > 0) {
+            // If multiple matches, prefer the most common format or latest
+            const exactMatch = majorVersionMatches.find((v) => v === `${Math.floor(reqNum)}.0`);
+            if (exactMatch) {
+                return exactMatch;
             }
+            // Return the first match (usually the most common format)
+            return majorVersionMatches[0];
         }
-        return best.v;
     }
-    // final fallback
+    // Fuzzy matching: find the closest version
+    const reqNumForFuzzy = parseFloat(requested);
+    if (!isNaN(reqNumForFuzzy)) {
+        const numericVersions = uniq
+            .map((v) => ({ v, n: parseFloat(v) }))
+            .filter((x) => !isNaN(x.n))
+            .sort((a, b) => Math.abs(a.n - reqNumForFuzzy) - Math.abs(b.n - reqNumForFuzzy));
+        if (numericVersions.length > 0) {
+            return numericVersions[0].v;
+        }
+    }
+    // Fallback: return the first available version
     return uniq[0];
 }

package/dist/tools/appautomate-utils/appium-sdk/config-generator.d.ts

@@ -1 +1,7 @@
-export declare function generateAppBrowserStackYMLInstructions(platforms: string[], username: string, accessKey: string, appPath: string | undefined, testingFramework: string): string;
+import { ValidatedEnvironment } from "../../sdk-utils/common/device-validator.js";
+export declare function generateAppBrowserStackYMLInstructions(config: {
+    validatedEnvironments?: ValidatedEnvironment[];
+    platforms?: string[];
+    testingFramework?: string;
+    projectName?: string;
+}, username: string, accessKey: string, appPath?: string): string;

package/dist/tools/appautomate-utils/appium-sdk/config-generator.js

@@ -1,26 +1,17 @@
-// Configuration utilities for BrowserStack App SDK
 import { APP_DEVICE_CONFIGS, AppSDKSupportedTestingFrameworkEnum, DEFAULT_APP_PATH, createStep, } from "./index.js";
-export function generateAppBrowserStackYMLInstructions(platforms, username, accessKey, appPath = DEFAULT_APP_PATH, testingFramework) {
-    if (testingFramework === AppSDKSupportedTestingFrameworkEnum.nightwatch ||
-        testingFramework === AppSDKSupportedTestingFrameworkEnum.webdriverio ||
-        testingFramework === AppSDKSupportedTestingFrameworkEnum.cucumberRuby) {
+export function generateAppBrowserStackYMLInstructions(config, username, accessKey, appPath = DEFAULT_APP_PATH) {
+    if (config.testingFramework ===
+        AppSDKSupportedTestingFrameworkEnum.nightwatch ||
+        config.testingFramework ===
+            AppSDKSupportedTestingFrameworkEnum.webdriverio ||
+        config.testingFramework === AppSDKSupportedTestingFrameworkEnum.cucumberRuby) {
         return "";
     }
-    // Generate platform and device configurations
-    const platformConfigs = platforms
-        .map((platform) => {
-        const devices = APP_DEVICE_CONFIGS[platform];
-        if (!devices)
-            return "";
-        return devices
-            .map((device) => `  - platformName: ${platform}
-    deviceName: ${device.deviceName}
-    platformVersion: "${device.platformVersion}"`)
-            .join("\n");
-    })
-        .filter(Boolean)
-        .join("\n");
-    // Construct YAML content
+    const platformConfigs = generatePlatformConfigs(config);
+    const projectName = config.projectName || "BrowserStack Sample";
+    const buildName = config.projectName
+        ? `${config.projectName}-AppAutomate-Build`
+        : "bstack-demo";
     const configContent = `\`\`\`yaml
 userName: ${username}
 accessKey: ${accessKey}
@@ -29,8 +20,9 @@ platforms:
 ${platformConfigs}
 parallelsPerPlatform: 1
 browserstackLocal: true
-buildName: bstack-demo
-projectName: BrowserStack Sample
+// TODO: replace projectName and buildName according to actual project
+projectName: ${projectName}
+buildName: ${buildName}
 debug: true
 networkLogs: true
 percy: false
@@ -43,8 +35,36 @@ accessibility: false
 - You can upload your app using BrowserStack's App Upload API or manually through the dashboard
 - Set \`browserstackLocal: true\` if you need to test with local/staging servers
 - Adjust \`parallelsPerPlatform\` based on your subscription limits`;
-    // Return formatted step for instructions
-    return createStep("Update browserstack.yml file with App Automate configuration:", `Create or update the browserstack.yml file in your project root with the following content:
-
-${configContent}`);
+    const stepTitle = "Update browserstack.yml file with App Automate configuration:";
+    const stepDescription = `Create or update the browserstack.yml file in your project root with the following content:
+  ${configContent}`;
+    return createStep(stepTitle, stepDescription);
+}
+function generatePlatformConfigs(config) {
+    if (config.validatedEnvironments && config.validatedEnvironments.length > 0) {
+        return config.validatedEnvironments
+            .filter((env) => env.platform === "android" || env.platform === "ios")
+            .map((env) => {
+            return `  - platformName: ${env.platform}
+    deviceName: "${env.deviceName}"
+    platformVersion: "${env.osVersion}"`;
+        })
+            .join("\n");
+    }
+    else if (config.platforms && config.platforms.length > 0) {
+        return config.platforms
+            .map((platform) => {
+            const devices = APP_DEVICE_CONFIGS[platform];
+            if (!devices)
+                return "";
+            return devices
+                .map((device) => `  - platformName: ${platform}
+    deviceName: ${device.deviceName}
+    platformVersion: "${device.platformVersion}"`)
+                .join("\n");
+        })
+            .filter(Boolean)
+            .join("\n");
+    }
+    return "";
 }

package/dist/tools/appautomate-utils/appium-sdk/constants.d.ts

@@ -17,7 +17,7 @@ export declare const SETUP_APP_AUTOMATE_SCHEMA: {
     detectedFramework: z.ZodNativeEnum<typeof AppSDKSupportedFrameworkEnum>;
     detectedTestingFramework: z.ZodNativeEnum<typeof AppSDKSupportedTestingFrameworkEnum>;
     detectedLanguage: z.ZodNativeEnum<typeof AppSDKSupportedLanguageEnum>;
-    desiredPlatforms: z.ZodArray<z.ZodNativeEnum<typeof AppSDKSupportedPlatformEnum>, "many">;
+    devices: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<AppSDKSupportedPlatformEnum.android>, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<AppSDKSupportedPlatformEnum.ios>, z.ZodString, z.ZodString], null>]>, "many">>;
     appPath: z.ZodString;
     project: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 };

package/dist/tools/appautomate-utils/appium-sdk/constants.js

@@ -29,9 +29,30 @@ export const SETUP_APP_AUTOMATE_SCHEMA = {
     detectedLanguage: z
         .nativeEnum(AppSDKSupportedLanguageEnum)
         .describe("The programming language used in the project. Supports Java and C#. Example: 'java', 'csharp'"),
-    desiredPlatforms: z
-        .array(z.nativeEnum(AppSDKSupportedPlatformEnum))
-        .describe("The mobile platforms the user wants to test on. Always ask this to the user, do not try to infer this. Example: ['android', 'ios']"),
+    devices: z
+        .array(z.union([
+        // Android: [android, deviceName, osVersion]
+        z.tuple([
+            z
+                .literal(AppSDKSupportedPlatformEnum.android)
+                .describe("Platform identifier: 'android'"),
+            z
+                .string()
+                .describe("Device name, e.g. 'Samsung Galaxy S24', 'Google Pixel 8'"),
+            z.string().describe("Android version, e.g. '14', '16', 'latest'"),
+        ]),
+        // iOS: [ios, deviceName, osVersion]
+        z.tuple([
+            z
+                .literal(AppSDKSupportedPlatformEnum.ios)
+                .describe("Platform identifier: 'ios'"),
+            z.string().describe("Device name, e.g. 'iPhone 15', 'iPhone 14 Pro'"),
+            z.string().describe("iOS version, e.g. '17', '16', 'latest'"),
+        ]),
+    ]))
+        .max(3)
+        .default([])
+        .describe("Tuples describing target mobile devices. Add device only when user asks explicitly for it. Defaults to [] . Example: [['android', 'Samsung Galaxy S24', '14'], ['ios', 'iPhone 15', '17']]"),
     appPath: z
         .string()
         .describe("Path to the mobile app file (.apk for Android, .ipa for iOS). Can be a local file path or a BrowserStack app URL (bs://)"),

package/dist/tools/appautomate-utils/appium-sdk/handler.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { getBrowserStackAuth } from "../../../lib/get-auth.js";
+import { validateAppAutomateDevices } from "../../sdk-utils/common/device-validator.js";
 import { getAppUploadInstruction, validateSupportforAppAutomate, } from "./utils.js";
 import { getAppSDKPrefixCommand, generateAppBrowserStackYMLInstructions, } from "./index.js";
 import { formatAppInstructionsWithNumbers, getAppInstructionsForProjectConfiguration, SETUP_APP_AUTOMATE_SCHEMA, } from "./index.js";
@@ -11,18 +12,31 @@ export async function setupAppAutomateHandler(rawInput, config) {
     // Use variables for all major input properties
     const testingFramework = input.detectedTestingFramework;
     const language = input.detectedLanguage;
-    const platforms = input.desiredPlatforms ?? ["android"];
+    const inputDevices = input.devices ?? [];
     const appPath = input.appPath;
     const framework = input.detectedFramework;
     //Validating if supported framework or not
     validateSupportforAppAutomate(framework, language, testingFramework);
+    // Use default mobile devices when array is empty
+    const devices = inputDevices.length === 0
+        ? [["android", "Samsung Galaxy S24", "latest"]]
+        : inputDevices;
+    // Validate devices against real BrowserStack device data
+    const validatedEnvironments = await validateAppAutomateDevices(devices);
+    // Extract platforms for backward compatibility (if needed)
+    const platforms = validatedEnvironments.map((env) => env.platform);
     // Step 1: Generate SDK setup command
     const sdkCommand = getAppSDKPrefixCommand(language, testingFramework, username, accessKey, appPath);
     if (sdkCommand) {
         instructions.push({ content: sdkCommand, type: "setup" });
     }
     // Step 2: Generate browserstack.yml configuration
-    const configInstructions = generateAppBrowserStackYMLInstructions(platforms, username, accessKey, appPath, testingFramework);
+    const configInstructions = generateAppBrowserStackYMLInstructions({
+        validatedEnvironments,
+        platforms,
+        testingFramework,
+        projectName: input.project,
+    }, username, accessKey, appPath);
     if (configInstructions) {
         instructions.push({ content: configInstructions, type: "config" });
     }

package/dist/tools/appautomate-utils/appium-sdk/languages/java.d.ts

@@ -1,8 +1,10 @@
 export declare const MAVEN_ARCHETYPE_GROUP_ID = "com.browserstack";
 export declare const MAVEN_ARCHETYPE_ARTIFACT_ID = "junit-archetype-integrate";
 export declare const MAVEN_ARCHETYPE_VERSION = "1.0";
+export declare const JAVA_APP_FRAMEWORK_VERSION_MAP: Record<string, string>;
 export declare const JAVA_APP_FRAMEWORK_MAP: Record<string, string>;
 export declare const GRADLE_APP_SETUP_INSTRUCTIONS = "\n**For Gradle setup:**\n1. Add browserstack-java-sdk to dependencies:\n   compileOnly 'com.browserstack:browserstack-java-sdk:latest.release'\n\n2. Add browserstackSDK path variable:\n   def browserstackSDKArtifact = configurations.compileClasspath.resolvedConfiguration.resolvedArtifacts.find { it.name == 'browserstack-java-sdk' }\n\n3. Add javaagent to gradle tasks:\n   jvmArgs \"-javaagent:${browserstackSDKArtifact.file}\"\n";
 export declare function getJavaAppInstructions(): string;
 export declare function getJavaAppFrameworkForMaven(framework: string): string;
+export declare function getJavaAppFrameworkVersion(framework: string): string;
 export declare function getJavaSDKCommand(framework: string, username: string, accessKey: string, appPath?: string): string;