@browserstack/mcp-server 1.2.4 → 1.2.6-beta.1

package/dist/tools/sdk-utils/common/device-validator.js

@@ -0,0 +1,375 @@
+import { getDevicesAndBrowsers, BrowserStackProducts, } from "../../../lib/device-cache.js";
+import { resolveVersion } from "../../../lib/version-resolver.js";
+import { customFuzzySearch } from "../../../lib/fuzzy.js";
+import { SDKSupportedBrowserAutomationFrameworkEnum } from "./types.js";
+const DEFAULTS = {
+    windows: { browser: "chrome" },
+    macos: { browser: "safari" },
+    android: { device: "Samsung Galaxy S24", browser: "chrome" },
+    ios: { device: "iPhone 15", browser: "safari" },
+};
+// ============================================================================
+// AUTOMATE SECTION (Desktop + Mobile for BrowserStack SDK)
+// ============================================================================
+// Helper functions to build device entries and eliminate duplication
+function buildDesktopEntries(automateData) {
+    if (!automateData.desktop) {
+        return [];
+    }
+    return automateData.desktop.flatMap((platform) => platform.browsers.map((browser) => ({
+        os: platform.os,
+        os_version: platform.os_version,
+        browser: browser.browser,
+        browser_version: browser.browser_version,
+    })));
+}
+function buildMobileEntries(appAutomateData, platform) {
+    if (!appAutomateData.mobile) {
+        return [];
+    }
+    return appAutomateData.mobile
+        .filter((group) => group.os === platform)
+        .flatMap((group) => group.devices.map((device) => ({
+        os: group.os,
+        os_version: device.os_version,
+        display_name: device.display_name,
+        browsers: device.browsers || [
+            {
+                browser: device.browser || (platform === "android" ? "chrome" : "safari"),
+            },
+        ],
+    })));
+}
+// Performance optimization: Create indexed maps for faster lookups
+function createDesktopIndex(entries) {
+    const byOS = new Map();
+    const byOSVersion = new Map();
+    const byBrowser = new Map();
+    const nested = new Map();
+    for (const entry of entries) {
+        // Index by OS
+        if (!byOS.has(entry.os)) {
+            byOS.set(entry.os, []);
+        }
+        byOS.get(entry.os).push(entry);
+        // Index by OS version
+        if (!byOSVersion.has(entry.os_version)) {
+            byOSVersion.set(entry.os_version, []);
+        }
+        byOSVersion.get(entry.os_version).push(entry);
+        // Index by browser
+        if (!byBrowser.has(entry.browser)) {
+            byBrowser.set(entry.browser, []);
+        }
+        byBrowser.get(entry.browser).push(entry);
+        // Build nested index: Map<os, Map<os_version, Map<browser, DesktopBrowserEntry[]>>>
+        if (!nested.has(entry.os)) {
+            nested.set(entry.os, new Map());
+        }
+        const osMap = nested.get(entry.os);
+        if (!osMap.has(entry.os_version)) {
+            osMap.set(entry.os_version, new Map());
+        }
+        const osVersionMap = osMap.get(entry.os_version);
+        if (!osVersionMap.has(entry.browser)) {
+            osVersionMap.set(entry.browser, []);
+        }
+        osVersionMap.get(entry.browser).push(entry);
+    }
+    return { byOS, byOSVersion, byBrowser, nested };
+}
+function createMobileIndex(entries) {
+    const byPlatform = new Map();
+    const byDeviceName = new Map();
+    const byOSVersion = new Map();
+    for (const entry of entries) {
+        // Index by platform
+        if (!byPlatform.has(entry.os)) {
+            byPlatform.set(entry.os, []);
+        }
+        byPlatform.get(entry.os).push(entry);
+        // Index by device name (case-insensitive)
+        const deviceKey = entry.display_name.toLowerCase();
+        if (!byDeviceName.has(deviceKey)) {
+            byDeviceName.set(deviceKey, []);
+        }
+        byDeviceName.get(deviceKey).push(entry);
+        // Index by OS version
+        if (!byOSVersion.has(entry.os_version)) {
+            byOSVersion.set(entry.os_version, []);
+        }
+        byOSVersion.get(entry.os_version).push(entry);
+    }
+    return { byPlatform, byDeviceName, byOSVersion };
+}
+export async function validateDevices(devices, framework) {
+    const validatedEnvironments = [];
+    if (!devices || devices.length === 0) {
+        // Use centralized default fallback
+        return [
+            {
+                platform: "windows",
+                osVersion: "11",
+                browser: DEFAULTS.windows.browser,
+                browserVersion: "latest",
+            },
+        ];
+    }
+    // Determine what data we need to fetch
+    const needsDesktop = devices.some((env) => ["windows", "macos"].includes((env[0] || "").toLowerCase()));
+    const needsMobile = devices.some((env) => ["android", "ios"].includes((env[0] || "").toLowerCase()));
+    // Fetch data using framework-specific endpoint for both desktop and mobile
+    let deviceData = null;
+    try {
+        if (needsDesktop || needsMobile) {
+            if (framework === SDKSupportedBrowserAutomationFrameworkEnum.playwright) {
+                deviceData = (await getDevicesAndBrowsers(BrowserStackProducts.PLAYWRIGHT_AUTOMATE));
+            }
+            else {
+                deviceData = (await getDevicesAndBrowsers(BrowserStackProducts.SELENIUM_AUTOMATE));
+            }
+        }
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch device data: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Preprocess data into indexed maps for better performance
+    let desktopIndex = null;
+    let androidIndex = null;
+    let iosIndex = null;
+    if (needsDesktop && deviceData) {
+        const desktopEntries = buildDesktopEntries(deviceData);
+        desktopIndex = createDesktopIndex(desktopEntries);
+    }
+    if (needsMobile && deviceData) {
+        const androidEntries = buildMobileEntries(deviceData, "android");
+        const iosEntries = buildMobileEntries(deviceData, "ios");
+        androidIndex = createMobileIndex(androidEntries);
+        iosIndex = createMobileIndex(iosEntries);
+    }
+    for (const env of devices) {
+        const discriminator = (env[0] || "").toLowerCase();
+        let validatedEnv;
+        if (discriminator === "windows") {
+            validatedEnv = validateDesktopEnvironment(env, desktopIndex, "windows", DEFAULTS.windows.browser);
+        }
+        else if (discriminator === "macos") {
+            validatedEnv = validateDesktopEnvironment(env, desktopIndex, "macos", DEFAULTS.macos.browser);
+        }
+        else if (discriminator === "android") {
+            validatedEnv = validateMobileEnvironment(env, androidIndex, "android", DEFAULTS.android.device, DEFAULTS.android.browser);
+        }
+        else if (discriminator === "ios") {
+            validatedEnv = validateMobileEnvironment(env, iosIndex, "ios", DEFAULTS.ios.device, DEFAULTS.ios.browser);
+        }
+        else {
+            throw new Error(`Unsupported platform: ${discriminator}`);
+        }
+        validatedEnvironments.push(validatedEnv);
+    }
+    if (framework === SDKSupportedBrowserAutomationFrameworkEnum.playwright) {
+        validatedEnvironments.forEach((env) => {
+            if (env.browser) {
+                env.browser = env.browser.toLowerCase();
+            }
+        });
+    }
+    return validatedEnvironments;
+}
+// Optimized desktop validation using nested indexed maps for O(1) lookups
+function validateDesktopEnvironment(env, index, platform, defaultBrowser) {
+    const [, osVersion, browser, browserVersion] = env;
+    const osKey = platform === "windows" ? "Windows" : "OS X";
+    // Use nested index for O(1) lookup instead of filtering
+    const osMap = index.nested.get(osKey);
+    if (!osMap) {
+        throw new Error(`No ${platform} devices available`);
+    }
+    // Get available OS versions for this platform
+    const availableOSVersions = Array.from(osMap.keys());
+    const validatedOSVersion = resolveVersion(osVersion || "latest", availableOSVersions);
+    // Use nested index for O(1) lookup
+    const osVersionMap = osMap.get(validatedOSVersion);
+    if (!osVersionMap) {
+        throw new Error(`OS version "${validatedOSVersion}" not available for ${platform}`);
+    }
+    // Get available browsers for this OS version
+    const availableBrowsers = Array.from(osVersionMap.keys());
+    const validatedBrowser = validateBrowserExact(browser || defaultBrowser, availableBrowsers);
+    // Use nested index for O(1) lookup
+    const browserEntries = osVersionMap.get(validatedBrowser);
+    if (!browserEntries || browserEntries.length === 0) {
+        throw new Error(`Browser "${validatedBrowser}" not available for ${platform} ${validatedOSVersion}`);
+    }
+    const availableBrowserVersions = [
+        ...new Set(browserEntries.map((e) => e.browser_version)),
+    ];
+    const validatedBrowserVersion = resolveVersion(browserVersion || "latest", availableBrowserVersions);
+    return {
+        platform,
+        osVersion: validatedOSVersion,
+        browser: validatedBrowser,
+        browserVersion: validatedBrowserVersion,
+    };
+}
+// Optimized mobile validation using indexed maps
+function validateMobileEnvironment(env, index, platform, defaultDevice, defaultBrowser) {
+    const [, deviceName, osVersion, browser] = env;
+    const platformEntries = index.byPlatform.get(platform) || [];
+    if (platformEntries.length === 0) {
+        throw new Error(`No ${platform} devices available`);
+    }
+    // Use fuzzy search only for device names (as suggested in feedback)
+    const deviceMatches = customFuzzySearch(platformEntries, ["display_name"], deviceName || defaultDevice, 5);
+    if (deviceMatches.length === 0) {
+        throw new Error(`No ${platform} devices matching "${deviceName}". Available devices: ${platformEntries
+            .map((d) => d.display_name || "unknown")
+            .slice(0, 5)
+            .join(", ")}`);
+    }
+    // Try to find exact match first
+    const exactMatch = deviceMatches.find((m) => m.display_name.toLowerCase() === (deviceName || "").toLowerCase());
+    // If no exact match, throw error instead of using fuzzy match
+    if (!exactMatch) {
+        const suggestions = deviceMatches.map((m) => m.display_name).join(", ");
+        throw new Error(`Device "${deviceName}" not found exactly for ${platform}. Available similar devices: ${suggestions}. Please use the exact device name.`);
+    }
+    // Use index for faster filtering
+    const deviceKey = exactMatch.display_name.toLowerCase();
+    const deviceFiltered = index.byDeviceName.get(deviceKey) || [];
+    const availableOSVersions = [
+        ...new Set(deviceFiltered.map((d) => d.os_version)),
+    ];
+    const validatedOSVersion = resolveVersion(osVersion || "latest", availableOSVersions);
+    // Use index for faster filtering
+    const osVersionEntries = index.byOSVersion.get(validatedOSVersion) || [];
+    const osFiltered = osVersionEntries.filter((d) => d.display_name.toLowerCase() === deviceKey);
+    // Validate browser if provided - use exact matching for browsers
+    let validatedBrowser = browser || defaultBrowser;
+    if (browser && osFiltered.length > 0) {
+        // Extract browsers more carefully - handle different possible structures
+        const availableBrowsers = [
+            ...new Set(osFiltered.flatMap((d) => {
+                if (d.browsers && Array.isArray(d.browsers)) {
+                    // If browsers is an array of objects with browser property
+                    return d.browsers
+                        .map((b) => {
+                        // Use display_name for user-friendly browser names, fallback to browser field
+                        return b.display_name || b.browser;
+                    })
+                        .filter(Boolean);
+                }
+                // For mobile devices, provide default browsers if none found
+                return platform === "android" ? ["chrome"] : ["safari"];
+            })),
+        ].filter(Boolean);
+        if (availableBrowsers.length > 0) {
+            try {
+                validatedBrowser = validateBrowserExact(browser, availableBrowsers);
+            }
+            catch (error) {
+                // Add more context to browser validation errors
+                throw new Error(`Failed to validate browser "${browser}" for ${platform} device "${exactMatch.display_name}" on OS version "${validatedOSVersion}". ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        else {
+            // For mobile, if no specific browsers found, just use the requested browser
+            // as most mobile devices support standard browsers
+            validatedBrowser = browser || defaultBrowser;
+        }
+    }
+    return {
+        platform,
+        osVersion: validatedOSVersion,
+        deviceName: exactMatch.display_name,
+        browser: validatedBrowser,
+    };
+}
+// ============================================================================
+// APP AUTOMATE SECTION (Mobile devices for App Automate)
+// ============================================================================
+export async function validateAppAutomateDevices(devices) {
+    const validatedDevices = [];
+    if (!devices || devices.length === 0) {
+        // Use centralized default fallback
+        return [
+            {
+                platform: "android",
+                osVersion: "latest",
+                deviceName: DEFAULTS.android.device,
+            },
+        ];
+    }
+    let appAutomateData;
+    try {
+        // Fetch app automate device data
+        appAutomateData = (await getDevicesAndBrowsers(BrowserStackProducts.APP_AUTOMATE));
+    }
+    catch (error) {
+        // Only wrap fetch-related errors
+        throw new Error(`Failed to fetch device data: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const device of devices) {
+        // Parse device array in format ["android", "Device Name", "OS Version"]
+        const [platform, deviceName, osVersion] = device;
+        // Find matching device in the data
+        let validatedDevice = null;
+        if (!appAutomateData.mobile) {
+            throw new Error("No mobile device data available");
+        }
+        // Filter by platform first
+        const platformGroup = appAutomateData.mobile.find((group) => group.os === platform.toLowerCase());
+        if (!platformGroup) {
+            throw new Error(`Platform "${platform}" not supported for App Automate`);
+        }
+        const platformDevices = platformGroup.devices;
+        // Find exact device name match (case-insensitive)
+        const exactMatch = platformDevices.find((d) => d.display_name.toLowerCase() === deviceName.toLowerCase());
+        if (exactMatch) {
+            // Check if the OS version is available for this device
+            const deviceVersions = platformDevices
+                .filter((d) => d.display_name === exactMatch.display_name)
+                .map((d) => d.os_version);
+            const validatedOSVersion = resolveVersion(osVersion || "latest", deviceVersions);
+            validatedDevice = {
+                platform: platformGroup.os,
+                osVersion: validatedOSVersion,
+                deviceName: exactMatch.display_name,
+            };
+        }
+        if (!validatedDevice) {
+            // If no exact match found, suggest similar devices from the SAME platform only
+            const platformDevicesForSearch = platformDevices.map((d) => ({
+                ...d,
+                platform: platformGroup.os,
+            }));
+            // Try fuzzy search with a more lenient threshold
+            const deviceMatches = customFuzzySearch(platformDevicesForSearch, ["display_name"], deviceName, 5, 0.8);
+            const suggestions = deviceMatches
+                .map((m) => `${m.display_name}`)
+                .join(", ");
+            // If no fuzzy matches, show some available devices as fallback
+            const fallbackDevices = platformDevicesForSearch
+                .slice(0, 5)
+                .map((d) => d.display_name)
+                .join(", ");
+            const errorMessage = suggestions
+                ? `Device "${deviceName}" not found for platform "${platform}".\nAvailable similar devices: ${suggestions}`
+                : `Device "${deviceName}" not found for platform "${platform}".\nAvailable devices: ${fallbackDevices}`;
+            throw new Error(errorMessage);
+        }
+        validatedDevices.push(validatedDevice);
+    }
+    return validatedDevices;
+}
+// ============================================================================
+// SHARED UTILITY FUNCTIONS
+// ============================================================================
+// Exact browser validation (preferred for structured fields)
+function validateBrowserExact(requestedBrowser, availableBrowsers) {
+    const exactMatch = availableBrowsers.find((b) => b.toLowerCase() === requestedBrowser.toLowerCase());
+    if (exactMatch) {
+        return exactMatch;
+    }
+    throw new Error(`Browser "${requestedBrowser}" not found. Available options: ${availableBrowsers.join(", ")}`);
+}

package/dist/tools/sdk-utils/common/schema.d.ts

@@ -1,20 +1,37 @@
 import { z } from "zod";
 import { PercyIntegrationTypeEnum } from "./types.js";
 import { SDKSupportedBrowserAutomationFrameworkEnum, SDKSupportedTestingFrameworkEnum, SDKSupportedLanguageEnum } from "./types.js";
+export declare const PlatformEnum: {
+    readonly WINDOWS: "windows";
+    readonly MACOS: "macos";
+    readonly ANDROID: "android";
+    readonly IOS: "ios";
+};
+export declare const WindowsPlatformEnum: {
+    readonly WINDOWS: "windows";
+};
+export declare const MacOSPlatformEnum: {
+    readonly MACOS: "macos";
+};
 export declare const SetUpPercyParamsShape: {
     projectName: z.ZodString;
     detectedLanguage: z.ZodNativeEnum<typeof SDKSupportedLanguageEnum>;
     detectedBrowserAutomationFramework: z.ZodNativeEnum<typeof SDKSupportedBrowserAutomationFrameworkEnum>;
     detectedTestingFramework: z.ZodNativeEnum<typeof SDKSupportedTestingFrameworkEnum>;
     integrationType: z.ZodNativeEnum<typeof PercyIntegrationTypeEnum>;
-    folderPaths: z.ZodArray<z.ZodString, "many">;
+    folderPaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    filePaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 };
 export declare const RunTestsOnBrowserStackParamsShape: {
     projectName: z.ZodString;
     detectedLanguage: z.ZodNativeEnum<typeof SDKSupportedLanguageEnum>;
     detectedBrowserAutomationFramework: z.ZodNativeEnum<typeof SDKSupportedBrowserAutomationFrameworkEnum>;
     detectedTestingFramework: z.ZodNativeEnum<typeof SDKSupportedTestingFrameworkEnum>;
-    desiredPlatforms: z.ZodArray<z.ZodEnum<["windows", "macos", "android", "ios"]>, "many">;
+    devices: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodTuple<[z.ZodNativeEnum<{
+        readonly WINDOWS: "windows";
+    }>, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"android">, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"ios">, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodNativeEnum<{
+        readonly MACOS: "macos";
+    }>, z.ZodString, z.ZodString, z.ZodString], null>]>, "many">>;
 };
 export declare const SetUpPercySchema: z.ZodObject<{
     projectName: z.ZodString;
@@ -22,40 +39,47 @@ export declare const SetUpPercySchema: z.ZodObject<{
     detectedBrowserAutomationFramework: z.ZodNativeEnum<typeof SDKSupportedBrowserAutomationFrameworkEnum>;
     detectedTestingFramework: z.ZodNativeEnum<typeof SDKSupportedTestingFrameworkEnum>;
     integrationType: z.ZodNativeEnum<typeof PercyIntegrationTypeEnum>;
-    folderPaths: z.ZodArray<z.ZodString, "many">;
+    folderPaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    filePaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     projectName: string;
     detectedLanguage: SDKSupportedLanguageEnum;
     detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
     detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
     integrationType: PercyIntegrationTypeEnum;
-    folderPaths: string[];
+    folderPaths?: string[] | undefined;
+    filePaths?: string[] | undefined;
 }, {
     projectName: string;
     detectedLanguage: SDKSupportedLanguageEnum;
     detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
     detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
     integrationType: PercyIntegrationTypeEnum;
-    folderPaths: string[];
+    folderPaths?: string[] | undefined;
+    filePaths?: string[] | undefined;
 }>;
 export declare const RunTestsOnBrowserStackSchema: z.ZodObject<{
     projectName: z.ZodString;
     detectedLanguage: z.ZodNativeEnum<typeof SDKSupportedLanguageEnum>;
     detectedBrowserAutomationFramework: z.ZodNativeEnum<typeof SDKSupportedBrowserAutomationFrameworkEnum>;
     detectedTestingFramework: z.ZodNativeEnum<typeof SDKSupportedTestingFrameworkEnum>;
-    desiredPlatforms: z.ZodArray<z.ZodEnum<["windows", "macos", "android", "ios"]>, "many">;
+    devices: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodTuple<[z.ZodNativeEnum<{
+        readonly WINDOWS: "windows";
+    }>, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"android">, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"ios">, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodNativeEnum<{
+        readonly MACOS: "macos";
+    }>, z.ZodString, z.ZodString, z.ZodString], null>]>, "many">>;
 }, "strip", z.ZodTypeAny, {
     projectName: string;
     detectedLanguage: SDKSupportedLanguageEnum;
     detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
     detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
-    desiredPlatforms: ("android" | "windows" | "macos" | "ios")[];
+    devices: (["windows", string, string, string] | ["android", string, string, string] | ["ios", string, string, string] | ["macos", string, string, string])[];
 }, {
     projectName: string;
     detectedLanguage: SDKSupportedLanguageEnum;
     detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
     detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
-    desiredPlatforms: ("android" | "windows" | "macos" | "ios")[];
+    devices?: (["windows", string, string, string] | ["android", string, string, string] | ["ios", string, string, string] | ["macos", string, string, string])[] | undefined;
 }>;
 export type SetUpPercyInput = z.infer<typeof SetUpPercySchema>;
 export type RunTestsOnBrowserStackInput = z.infer<typeof RunTestsOnBrowserStackSchema>;

package/dist/tools/sdk-utils/common/schema.js

@@ -1,6 +1,19 @@
 import { z } from "zod";
 import { PercyIntegrationTypeEnum } from "./types.js";
 import { SDKSupportedBrowserAutomationFrameworkEnum, SDKSupportedTestingFrameworkEnum, SDKSupportedLanguageEnum, } from "./types.js";
+// Platform enums for better validation
+export const PlatformEnum = {
+    WINDOWS: "windows",
+    MACOS: "macos",
+    ANDROID: "android",
+    IOS: "ios",
+};
+export const WindowsPlatformEnum = {
+    WINDOWS: "windows",
+};
+export const MacOSPlatformEnum = {
+    MACOS: "macos",
+};
 export const SetUpPercyParamsShape = {
     projectName: z.string().describe("A unique name for your Percy project."),
     detectedLanguage: z.nativeEnum(SDKSupportedLanguageEnum),
@@ -11,7 +24,12 @@ export const SetUpPercyParamsShape = {
         .describe("Specify the Percy integration type: web (Percy Web) or automate (Percy Automate). If not provided, always prompt the user with: 'Please specify the Percy integration type.' Do not proceed without an explicit selection. Never use a default."),
     folderPaths: z
         .array(z.string())
+        .optional()
         .describe("An array of absolute folder paths containing UI test files. If not provided, analyze codebase for UI test folders by scanning for test patterns which contain UI test cases as per framework. Return empty array if none found."),
+    filePaths: z
+        .array(z.string())
+        .optional()
+        .describe("An array of absolute file paths to specific UI test files. Use this when you want to target specific test files rather than entire folders. If not provided, will use folderPaths instead."),
 };
 export const RunTestsOnBrowserStackParamsShape = {
     projectName: z
@@ -20,9 +38,50 @@ export const RunTestsOnBrowserStackParamsShape = {
     detectedLanguage: z.nativeEnum(SDKSupportedLanguageEnum),
     detectedBrowserAutomationFramework: z.nativeEnum(SDKSupportedBrowserAutomationFrameworkEnum),
     detectedTestingFramework: z.nativeEnum(SDKSupportedTestingFrameworkEnum),
-    desiredPlatforms: z
-        .array(z.enum(["windows", "macos", "android", "ios"]))
-        .describe("An array of platforms to run tests on."),
+    devices: z
+        .array(z.union([
+        // Windows: [windows, osVersion, browser, browserVersion]
+        z.tuple([
+            z
+                .nativeEnum(WindowsPlatformEnum)
+                .describe("Platform identifier: 'windows'"),
+            z.string().describe("Windows version, e.g. '10', '11'"),
+            z.string().describe("Browser name, e.g. 'chrome', 'firefox', 'edge'"),
+            z
+                .string()
+                .describe("Browser version, e.g. '132', 'latest', 'oldest'"),
+        ]),
+        // Android: [android, name, model, osVersion, browser]
+        z.tuple([
+            z
+                .literal(PlatformEnum.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'"),
+            z.string().describe("Browser name, e.g. 'chrome', 'samsung browser'"),
+        ]),
+        // iOS: [ios, name, model, osVersion, browser]
+        z.tuple([
+            z.literal(PlatformEnum.IOS).describe("Platform identifier: 'ios'"),
+            z.string().describe("Device name, e.g. 'iPhone 12 Pro'"),
+            z.string().describe("iOS version, e.g. '17', 'latest'"),
+            z.string().describe("Browser name, typically 'safari'"),
+        ]),
+        // macOS: [mac|macos, name, model, browser, browserVersion]
+        z.tuple([
+            z
+                .nativeEnum(MacOSPlatformEnum)
+                .describe("Platform identifier: 'mac' or 'macos'"),
+            z.string().describe("macOS version name, e.g. 'Sequoia', 'Ventura'"),
+            z.string().describe("Browser name, e.g. 'safari', 'chrome'"),
+            z.string().describe("Browser version, e.g. 'latest'"),
+        ]),
+    ]))
+        .max(3)
+        .default([])
+        .describe("Preferred tuples of target devices.Add device only when user asks explicitly for it. Defaults to [] . Example: [['windows', '11', 'chrome', 'latest']]"),
 };
 export const SetUpPercySchema = z.object(SetUpPercyParamsShape);
 export const RunTestsOnBrowserStackSchema = z.object(RunTestsOnBrowserStackParamsShape);

package/dist/tools/sdk-utils/common/utils.d.ts

@@ -18,8 +18,8 @@ export declare function getPercyAutomateNotImplementedMessage(type: PercyAutomat
 export declare function getBootstrapFailedMessage(error: unknown, context: {
     config: unknown;
     percyMode?: string;
-    sdkVersion?: string;
 }): string;
 export declare function percyUnsupportedResult(integrationType: PercyIntegrationTypeEnum, supportCheck?: {
     errorMessage?: string;
 }): CallToolResult;
+export declare function validatePercyPathandFolders(input: any): void;

package/dist/tools/sdk-utils/common/utils.js

@@ -4,6 +4,7 @@ import { isPercyWebFrameworkSupported } from "../percy-web/frameworks.js";
 import { formatInstructionsWithNumbers, generateVerificationMessage, } from "./formatUtils.js";
 import { PercyAutomateNotImplementedType, } from "./types.js";
 import { IMPORTANT_SETUP_WARNING } from "./index.js";
+import { PackageJsonVersion } from "../../../index.js";
 export function checkPercyIntegrationSupport(input) {
     if (input.integrationType === PercyIntegrationTypeEnum.AUTOMATE) {
         const isSupported = isPercyAutomateFrameworkSupported(input.detectedLanguage, input.detectedBrowserAutomationFramework || "", input.detectedTestingFramework || "");
@@ -69,10 +70,11 @@ export function getPercyAutomateNotImplementedMessage(type, input, supported) {
     }
 }
 export function getBootstrapFailedMessage(error, context) {
+    const error_message = error instanceof Error ? error.message : "unknown error";
     return `Failed to bootstrap project with BrowserStack SDK.
-Error: ${error}
+Error: ${error_message}
 Percy Mode: ${context.percyMode ?? "automate"}
-SDK Version: ${context.sdkVersion ?? "N/A"}
+MCP Version: ${PackageJsonVersion}
 Please open an issue on GitHub if the problem persists.`;
 }
 export function percyUnsupportedResult(integrationType, supportCheck) {
@@ -88,3 +90,13 @@ export function percyUnsupportedResult(integrationType, supportCheck) {
         shouldSkipFormatting: true,
     };
 }
+export function validatePercyPathandFolders(input) {
+    const hasFolderPaths = input.folderPaths && input.folderPaths.length > 0;
+    const hasFilePaths = input.filePaths && input.filePaths.length > 0;
+    if (!hasFolderPaths && !hasFilePaths) {
+        throw new Error("Please provide either:\n" +
+            "• folderPaths: Array of directory paths containing test files\n" +
+            "• filePaths: Array of specific test file paths\n\n" +
+            "Example: { filePaths: ['/path/to/test.spec.js'] }");
+    }
+}

package/dist/tools/sdk-utils/handler.d.ts

@@ -2,3 +2,4 @@ import { BrowserStackConfig } from "../../lib/types.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 export declare function runTestsOnBrowserStackHandler(rawInput: unknown, config: BrowserStackConfig): Promise<CallToolResult>;
 export declare function setUpPercyHandler(rawInput: unknown, config: BrowserStackConfig): Promise<CallToolResult>;
+export declare function simulatePercyChangeHandler(rawInput: unknown, config: BrowserStackConfig): Promise<CallToolResult>;