@browserstack/mcp-server 1.2.4 → 1.2.5

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

@@ -0,0 +1,368 @@
+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);
+    }
+    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,6 +1,18 @@
 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>;
@@ -14,7 +26,11 @@ export declare const RunTestsOnBrowserStackParamsShape: {
     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;
@@ -43,19 +59,23 @@ export declare const RunTestsOnBrowserStackSchema: z.ZodObject<{
     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),
@@ -20,9 +33,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.js

@@ -69,8 +69,9 @@ 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"}
 Please open an issue on GitHub if the problem persists.`;

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>;

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

@@ -9,16 +9,11 @@ import { runPercyWithBrowserstackSDK } from "./percy-bstack/handler.js";
 import { checkPercyIntegrationSupport } from "./common/utils.js";
 import { SetUpPercySchema, RunTestsOnBrowserStackSchema, } from "./common/schema.js";
 import { getBootstrapFailedMessage, percyUnsupportedResult, } from "./common/utils.js";
+import { PERCY_SIMULATE_INSTRUCTION, PERCY_REPLACE_REGEX, PERCY_SIMULATION_DRIVER_INSTRUCTION, PERCY_VERIFICATION_REGEX, } from "./common/constants.js";
 export async function runTestsOnBrowserStackHandler(rawInput, config) {
-    try {
-        const input = RunTestsOnBrowserStackSchema.parse(rawInput);
-        // Only handle BrowserStack SDK setup for functional/integration tests.
-        const result = runBstackSDKOnly(input, config);
-        return await formatToolResult(result);
-    }
-    catch (error) {
-        throw new Error(getBootstrapFailedMessage(error, { config }));
-    }
+    const input = RunTestsOnBrowserStackSchema.parse(rawInput);
+    const result = await runBstackSDKOnly(input, config);
+    return await formatToolResult(result);
 }
 export async function setUpPercyHandler(rawInput, config) {
     try {
@@ -47,7 +42,7 @@ export async function setUpPercyHandler(rawInput, config) {
             // First try Percy with BrowserStack SDK
             const percyWithBrowserstackSDKResult = runPercyWithBrowserstackSDK({
                 ...percyInput,
-                desiredPlatforms: [],
+                devices: [],
             }, config);
             const hasPercySDKError = percyWithBrowserstackSDKResult.steps &&
                 percyWithBrowserstackSDKResult.steps.some((step) => step.isError);
@@ -77,9 +72,9 @@ export async function setUpPercyHandler(rawInput, config) {
                     detectedLanguage: input.detectedLanguage,
                     detectedBrowserAutomationFramework: input.detectedBrowserAutomationFramework,
                     detectedTestingFramework: input.detectedTestingFramework,
-                    desiredPlatforms: [],
+                    devices: [],
                 };
-                const sdkResult = runBstackSDKOnly(sdkInput, config, true);
+                const sdkResult = await runBstackSDKOnly(sdkInput, config, true);
                 // Percy Automate instructions
                 const percyToken = await fetchPercyToken(input.projectName, authorization, { type: PercyIntegrationTypeEnum.AUTOMATE });
                 const percyAutomateResult = runPercyAutomateOnly(percyInput, percyToken);
@@ -117,3 +112,36 @@ export async function setUpPercyHandler(rawInput, config) {
         throw new Error(getBootstrapFailedMessage(error, { config }));
     }
 }
+export async function simulatePercyChangeHandler(rawInput, config) {
+    try {
+        let percyInstruction;
+        try {
+            percyInstruction = await setUpPercyHandler(rawInput, config);
+        }
+        catch {
+            throw new Error("Failed to set up Percy");
+        }
+        if (percyInstruction.isError) {
+            return percyInstruction;
+        }
+        if (Array.isArray(percyInstruction.content)) {
+            percyInstruction.content = percyInstruction.content.map((item) => {
+                if (typeof item.text === "string") {
+                    const updatedText = item.text
+                        .replace(PERCY_REPLACE_REGEX, PERCY_SIMULATE_INSTRUCTION)
+                        .replace(PERCY_VERIFICATION_REGEX, "");
+                    return { ...item, text: updatedText };
+                }
+                return item;
+            });
+        }
+        percyInstruction.content?.push({
+            type: "text",
+            text: PERCY_SIMULATION_DRIVER_INSTRUCTION,
+        });
+        return percyInstruction;
+    }
+    catch (error) {
+        throw new Error(getBootstrapFailedMessage(error, { config }));
+    }
+}

package/dist/tools/sdk-utils/percy-bstack/handler.js

@@ -63,7 +63,11 @@ export function runPercyWithBrowserstackSDK(input, config) {
             content: sdkSetupCommand,
         });
     }
-    const ymlInstructions = generateBrowserStackYMLInstructions(input.desiredPlatforms, true, input.projectName);
+    const ymlInstructions = generateBrowserStackYMLInstructions({
+        platforms: input.devices?.map((t) => t.join(" ")) || [],
+        enablePercy: true,
+        projectName: input.projectName,
+    });
     if (ymlInstructions) {
         steps.push({
             type: "instruction",

package/dist/tools/sdk-utils/percy-web/handler.js

@@ -12,7 +12,9 @@ export function runPercyWeb(input, percyToken) {
     steps.push({
         type: "instruction",
         title: "Set Percy Token in Environment",
-        content: `Here is percy token if required {${percyToken}}`,
+        content: `Set the environment variable for your project:
+        export PERCY_TOKEN="${percyToken}"
+        (For Windows: use 'setx PERCY_TOKEN "${percyToken}"' or 'set PERCY_TOKEN=${percyToken}' as appropriate.)`,
     });
     steps.push({
         type: "instruction",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.4",
+    "@modelcontextprotocol/sdk": "^1.18.1",
     "@types/form-data": "^2.5.2",
     "axios": "^1.8.4",
     "browserstack-local": "^1.5.6",