@browserstack/mcp-server 1.2.1 → 1.2.2-beta.1

package/dist/tools/sdk-utils/bstack/sdkHandler.js

@@ -0,0 +1,74 @@
+import { getBrowserStackAuth } from "../../../lib/get-auth.js";
+import { getSDKPrefixCommand } from "./commands.js";
+import { generateBrowserStackYMLInstructions } from "./configUtils.js";
+import { getInstructionsForProjectConfiguration } from "../common/instructionUtils.js";
+export function runBstackSDKOnly(input, config, isPercyAutomate = false) {
+    const steps = [];
+    const authString = getBrowserStackAuth(config);
+    const [username, accessKey] = authString.split(":");
+    // Handle frameworks with unique setup instructions that don't use browserstack.yml
+    if (input.detectedBrowserAutomationFramework === "cypress" ||
+        input.detectedTestingFramework === "webdriverio") {
+        const frameworkInstructions = getInstructionsForProjectConfiguration(input.detectedBrowserAutomationFramework, input.detectedTestingFramework, input.detectedLanguage, username, accessKey);
+        if (frameworkInstructions) {
+            if (frameworkInstructions.setup) {
+                steps.push({
+                    type: "instruction",
+                    title: "Framework-Specific Setup",
+                    content: frameworkInstructions.setup,
+                });
+            }
+            if (frameworkInstructions.run && !isPercyAutomate) {
+                steps.push({
+                    type: "instruction",
+                    title: "Run the tests",
+                    content: frameworkInstructions.run,
+                });
+            }
+        }
+        return {
+            steps,
+            requiresPercy: false,
+            missingDependencies: [],
+        };
+    }
+    // Default flow using browserstack.yml
+    const sdkSetupCommand = getSDKPrefixCommand(input.detectedLanguage, input.detectedTestingFramework, username, accessKey);
+    if (sdkSetupCommand) {
+        steps.push({
+            type: "instruction",
+            title: "Install BrowserStack SDK",
+            content: sdkSetupCommand,
+        });
+    }
+    const ymlInstructions = generateBrowserStackYMLInstructions(input.desiredPlatforms, false, input.projectName);
+    if (ymlInstructions) {
+        steps.push({
+            type: "instruction",
+            title: "Configure browserstack.yml",
+            content: ymlInstructions,
+        });
+    }
+    const frameworkInstructions = getInstructionsForProjectConfiguration(input.detectedBrowserAutomationFramework, input.detectedTestingFramework, input.detectedLanguage, username, accessKey);
+    if (frameworkInstructions) {
+        if (frameworkInstructions.setup) {
+            steps.push({
+                type: "instruction",
+                title: "Framework-Specific Setup",
+                content: frameworkInstructions.setup,
+            });
+        }
+        if (frameworkInstructions.run && !isPercyAutomate) {
+            steps.push({
+                type: "instruction",
+                title: "Run the tests",
+                content: frameworkInstructions.run,
+            });
+        }
+    }
+    return {
+        steps,
+        requiresPercy: false,
+        missingDependencies: [],
+    };
+}

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

@@ -0,0 +1,10 @@
+export declare const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup.";
+export declare const SETUP_PERCY_DESCRIPTION = "Set up Percy visual testing for your project. This supports both Percy Web Standalone and Percy Automate.";
+export declare const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
+export declare const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";
+export declare const RUN_ON_BROWSERSTACK_DESCRIPTION = "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use this tool for functional or integration test setup on BrowserStack only. For any visual testing or Percy integration, use the dedicated Percy setup tool. Example prompts: run this test on browserstack; set up this project for browserstack.";
+export declare const SIMULATE_PERCY_CHANGE_DESCRIPTION = "This tool helps new users simulate a Percy visual change by guiding them to make a visible UI modification, rerun Percy, and verify that the change is detected. Only Percy web is supported";
+export declare const PERCY_REPLACE_REGEX: RegExp;
+export declare const PERCY_SNAPSHOT_INSTRUCTION = "\nInvoke listTestFiles() with the provided directories from user to gather all test files in memory and obtain the generated UUID ---STEP---\nProcess files in STRICT sequential order using tool addPercySnapshotCommands() with below instructions:\n- Start with index 0\n- Then index 1  \n- Then index 2\n- Continue sequentially until the last index\n- DO NOT skip any index numbers\n- DO NOT jump to random indices like 10, 20, 30\n- DO NOT worry about time consuming and any constraints.\n- DO NOT STOP until you add commands in all the files or you reach end of the files.\n";
+export declare const PERCY_SIMULATE_INSTRUCTION = "\nMANDATORY: Aggressive, Accurate Percy Snapshots Integration\n\nPrerequisite: Before making any code changes in the user's repo, switch to a branch named temp-percy (run git init first if the repo is not yet initialized).\n\nYou MUST follow these steps with NO EXCEPTIONS:\n1. Identify 4-5 key test files in the project that are critical for visual testing.\n2. For EACH identified test file, analyze the code to find EVERY location where a Percy snapshot should be called (e.g., after each navigation, UI change, or significant state in tests).\n3. Insert snapshot calls at ALL such points, not just the first or most obvious one.\n\nIteratively update every selected test file with percy snapshot calls at all identified points, ensuring comprehensive coverage of visual changes.";
+export declare const PERCY_SIMULATION_DRIVER_INSTRUCTION = "\nMANDATORY: Step-by-Step Percy Visual Change Simulation\nYou MUST follow these steps with NO EXCEPTIONS:\n\nSTEP 1: At this case we have added Percy snapshot commands to the test files at the appropriate locations (e.g., after navigation, UI change, or significant state). \n- Use ONLY existing snapshot names.\n- Do NOT add any popup injection or visual changes yet.\n- Do NOT run any Percy builds at this stage.\n\nSTEP 2: Run ONE comprehensive baseline Percy build that executes ALL tests containing Percy snapshots in a SINGLE build. This creates one baseline build with all snapshots for comparison. Use a command like: npx percy exec -- python -m pytest tests/ -k 'test_name1 or test_name2 or test_name3' -v to run multiple specific tests in one build.\"\n\nSTEP 3: Modify your test to inject a visible UI change (such as a popup) IMMEDIATELY BEFORE an EXISTING snapshot command (e.g., before percy_snapshot(self.driver, \"screenshot name\")).\n- Do NOT add a new snapshot name for the popup.\n- The popup must appear in an existing snapshot, not a new one.\n- Add this popup code in some test files before the percy_snapshot command you've added, to display the visual changes.\n\n```Javascript\npopup_script = `\nvar popup = document.createElement('div');\npopup.id = 'percy-test-popup';\npopup.style.cssText = popup.style.cssText = `\n  /* TODO: Add styles to make the popup large, centered, and visually noticeable.\n     Suggested properties: position: fixed; top/left; transform; background; color; font-size; padding; z-index; animation, etc. */\n`;\npopup.innerHTML = 'PERCY TEST<br>VISUAL CHANGE<br>DETECTED!';\ndocument.body.appendChild(popup);\n`;\n\n# Insert this just before the EXISTING snapshot command:\ndriver.execute_script(popup_script)\npercy_snapshot(self.driver, \"Before Adding to Cart\")  # (Do NOT change the snapshot name, keep existing one)\n```\n\nSTEP 4: Run a second Percy build.\n- The snapshot names must remain the same as in the baseline.\n- The visual change should now appear in the same snapshot as before.\n- Use the same build command you ran for the baseline.\n\nSTEP 5: Compare the two Percy builds to see the detected visual difference.\n\nSTEP 6: Now ask user if they want to setup percy for full project coverage? If yes, call the \"setupPercyVisualTesting\" tool to enable complete coverage for the entire project.\n\nCONSTRAINTS:\n- Do NOT run any builds until explicitly instructed in the steps.\n- Do NOT add new snapshot names\u2014only use existing ones.\n- Do NOT add popup injection until the baseline is established.\n- Visual changes must appear in EXISTING snapshots, not new ones.\n\nVALIDATION CHECKPOINTS (before proceeding to the next step):\n- Are you adding only snapshot commands (not running builds)?\n- Are you reusing existing snapshot names (not creating new ones)?\n- Have you established the baseline first (before adding visual changes)\n\nCRITICAL: \nDo NOT run tests separately or create multiple builds during baseline establishment. The goal is to have exactly TWO builds total: (1) baseline build with all original snapshots, (2) modified build with the same tests but visual changes injected.\n";

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

@@ -0,0 +1,86 @@
+export const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup.";
+export const SETUP_PERCY_DESCRIPTION = "Set up Percy visual testing for your project. This supports both Percy Web Standalone and Percy Automate.";
+export const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
+export const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";
+export const RUN_ON_BROWSERSTACK_DESCRIPTION = "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use this tool for functional or integration test setup on BrowserStack only. For any visual testing or Percy integration, use the dedicated Percy setup tool. Example prompts: run this test on browserstack; set up this project for browserstack.";
+export const SIMULATE_PERCY_CHANGE_DESCRIPTION = "This tool helps new users simulate a Percy visual change by guiding them to make a visible UI modification, rerun Percy, and verify that the change is detected. Only Percy web is supported";
+export const PERCY_REPLACE_REGEX = /Invoke listTestFiles\(\) with the provided directories[\s\S]*?- DO NOT STOP until you add commands in all the files or you reach end of the files\./;
+export const PERCY_SNAPSHOT_INSTRUCTION = `
+Invoke listTestFiles() with the provided directories from user to gather all test files in memory and obtain the generated UUID ---STEP---
+Process files in STRICT sequential order using tool addPercySnapshotCommands() with below instructions:
+- Start with index 0
+- Then index 1  
+- Then index 2
+- Continue sequentially until the last index
+- DO NOT skip any index numbers
+- DO NOT jump to random indices like 10, 20, 30
+- DO NOT worry about time consuming and any constraints.
+- DO NOT STOP until you add commands in all the files or you reach end of the files.
+`;
+export const PERCY_SIMULATE_INSTRUCTION = `
+MANDATORY: Aggressive, Accurate Percy Snapshots Integration
+
+Prerequisite: Before making any code changes in the user's repo, switch to a branch named temp-percy (run git init first if the repo is not yet initialized).
+
+You MUST follow these steps with NO EXCEPTIONS:
+1. Identify 4-5 key test files in the project that are critical for visual testing.
+2. For EACH identified test file, analyze the code to find EVERY location where a Percy snapshot should be called (e.g., after each navigation, UI change, or significant state in tests).
+3. Insert snapshot calls at ALL such points, not just the first or most obvious one.
+
+Iteratively update every selected test file with percy snapshot calls at all identified points, ensuring comprehensive coverage of visual changes.`;
+export const PERCY_SIMULATION_DRIVER_INSTRUCTION = `
+MANDATORY: Step-by-Step Percy Visual Change Simulation
+You MUST follow these steps with NO EXCEPTIONS:
+
+STEP 1: At this case we have added Percy snapshot commands to the test files at the appropriate locations (e.g., after navigation, UI change, or significant state). 
+- Use ONLY existing snapshot names.
+- Do NOT add any popup injection or visual changes yet.
+- Do NOT run any Percy builds at this stage.
+
+STEP 2: Run ONE comprehensive baseline Percy build that executes ALL tests containing Percy snapshots in a SINGLE build. This creates one baseline build with all snapshots for comparison. Use a command like: npx percy exec -- python -m pytest tests/ -k 'test_name1 or test_name2 or test_name3' -v to run multiple specific tests in one build."
+
+STEP 3: Modify your test to inject a visible UI change (such as a popup) IMMEDIATELY BEFORE an EXISTING snapshot command (e.g., before percy_snapshot(self.driver, "screenshot name")).
+- Do NOT add a new snapshot name for the popup.
+- The popup must appear in an existing snapshot, not a new one.
+- Add this popup code in some test files before the percy_snapshot command you've added, to display the visual changes.
+
+\`\`\`Javascript
+popup_script = \`
+var popup = document.createElement('div');
+popup.id = 'percy-test-popup';
+popup.style.cssText = popup.style.cssText = \`
+  /* TODO: Add styles to make the popup large, centered, and visually noticeable.
+     Suggested properties: position: fixed; top/left; transform; background; color; font-size; padding; z-index; animation, etc. */
+\`;
+popup.innerHTML = 'PERCY TEST<br>VISUAL CHANGE<br>DETECTED!';
+document.body.appendChild(popup);
+\`;
+
+# Insert this just before the EXISTING snapshot command:
+driver.execute_script(popup_script)
+percy_snapshot(self.driver, "Before Adding to Cart")  # (Do NOT change the snapshot name, keep existing one)
+\`\`\`
+
+STEP 4: Run a second Percy build.
+- The snapshot names must remain the same as in the baseline.
+- The visual change should now appear in the same snapshot as before.
+- Use the same build command you ran for the baseline.
+
+STEP 5: Compare the two Percy builds to see the detected visual difference.
+
+STEP 6: Now ask user if they want to setup percy for full project coverage? If yes, call the "setupPercyVisualTesting" tool to enable complete coverage for the entire project.
+
+CONSTRAINTS:
+- Do NOT run any builds until explicitly instructed in the steps.
+- Do NOT add new snapshot names—only use existing ones.
+- Do NOT add popup injection until the baseline is established.
+- Visual changes must appear in EXISTING snapshots, not new ones.
+
+VALIDATION CHECKPOINTS (before proceeding to the next step):
+- Are you adding only snapshot commands (not running builds)?
+- Are you reusing existing snapshot names (not creating new ones)?
+- Have you established the baseline first (before adding visual changes)
+
+CRITICAL: 
+Do NOT run tests separately or create multiple builds during baseline establishment. The goal is to have exactly TWO builds total: (1) baseline build with all original snapshots, (2) modified build with the same tests but visual changes injected.
+`;

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

@@ -0,0 +1,5 @@
+export declare function formatInstructionsWithNumbers(instructionText: string, separator?: string): {
+    formattedSteps: string;
+    stepCount: number;
+};
+export declare function generateVerificationMessage(stepCount: number): string;

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

@@ -0,0 +1,27 @@
+export function formatInstructionsWithNumbers(instructionText, separator = "---STEP---") {
+    // Split the instructions by the separator
+    const steps = instructionText
+        .split(separator)
+        .map((step) => step.trim())
+        .filter((step) => step.length > 0);
+    // If no separators found, treat the entire text as one step
+    if (steps.length === 1 && !instructionText.includes(separator)) {
+        return {
+            formattedSteps: `**Step 1:**\n${instructionText.trim()}`,
+            stepCount: 1,
+        };
+    }
+    // Format each step with numbering
+    const formattedSteps = steps
+        .map((step, index) => {
+        return `**Step ${index + 1}:**\n${step.trim()}`;
+    })
+        .join("\n\n");
+    return {
+        formattedSteps,
+        stepCount: steps.length,
+    };
+}
+export function generateVerificationMessage(stepCount) {
+    return `**✅ Verification:**\nPlease verify that you have completed all ${stepCount} steps above to ensure proper setup. If you encounter any issues, double-check each step and ensure all commands executed successfully.`;
+}

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

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./constants.js";
+export * from "./formatUtils.js";

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

@@ -0,0 +1,4 @@
+// Common utilities and types for SDK tools
+export * from "./types.js";
+export * from "./constants.js";
+export * from "./formatUtils.js";

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

@@ -0,0 +1,8 @@
+/**
+ * Core instruction configuration utilities for runTestsOnBrowserStack tool.
+ */
+import { SDKSupportedLanguage, SDKSupportedBrowserAutomationFramework, SDKSupportedTestingFramework } from "./types.js";
+export declare const getInstructionsForProjectConfiguration: (detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFramework, detectedTestingFramework: SDKSupportedTestingFramework, detectedLanguage: SDKSupportedLanguage, username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};

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

@@ -0,0 +1,20 @@
+/**
+ * Core instruction configuration utilities for runTestsOnBrowserStack tool.
+ */
+import { SUPPORTED_CONFIGURATIONS } from "../bstack/frameworks.js";
+const errorMessageSuffix = "Please open an issue at our Github repo: https://github.com/browserstack/browserstack-mcp-server/issues to request support for your project configuration";
+export const getInstructionsForProjectConfiguration = (detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, username, accessKey) => {
+    const configuration = SUPPORTED_CONFIGURATIONS[detectedLanguage];
+    if (!configuration) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    if (!configuration[detectedBrowserAutomationFramework]) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedBrowserAutomationFramework} for ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    if (!configuration[detectedBrowserAutomationFramework][detectedTestingFramework]) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedTestingFramework} for ${detectedBrowserAutomationFramework} on ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    const instructionFunction = configuration[detectedBrowserAutomationFramework][detectedTestingFramework]
+        .instructions;
+    return instructionFunction(username, accessKey);
+};

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

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { SDKSupportedBrowserAutomationFrameworkEnum, SDKSupportedTestingFrameworkEnum, SDKSupportedLanguageEnum } from "./types.js";
+import { PercyIntegrationTypeEnum } from "./types.js";
+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">;
+};
+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">;
+};
+export declare const SetUpPercySchema: z.ZodObject<{
+    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">;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    detectedLanguage: SDKSupportedLanguageEnum;
+    detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
+    detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
+    integrationType: PercyIntegrationTypeEnum;
+    folderPaths: string[];
+}, {
+    projectName: string;
+    detectedLanguage: SDKSupportedLanguageEnum;
+    detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
+    detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
+    integrationType: PercyIntegrationTypeEnum;
+    folderPaths: string[];
+}>;
+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">;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    detectedLanguage: SDKSupportedLanguageEnum;
+    detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
+    detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
+    desiredPlatforms: ("android" | "windows" | "macos" | "ios")[];
+}, {
+    projectName: string;
+    detectedLanguage: SDKSupportedLanguageEnum;
+    detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
+    detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
+    desiredPlatforms: ("android" | "windows" | "macos" | "ios")[];
+}>;
+export type SetUpPercyInput = z.infer<typeof SetUpPercySchema>;
+export type RunTestsOnBrowserStackInput = z.infer<typeof RunTestsOnBrowserStackSchema>;

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

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { SDKSupportedBrowserAutomationFrameworkEnum, SDKSupportedTestingFrameworkEnum, SDKSupportedLanguageEnum, } from "./types.js";
+import { PercyIntegrationTypeEnum } from "./types.js";
+export const SetUpPercyParamsShape = {
+    projectName: z.string().describe("A unique name for your Percy project."),
+    detectedLanguage: z.nativeEnum(SDKSupportedLanguageEnum),
+    detectedBrowserAutomationFramework: z.nativeEnum(SDKSupportedBrowserAutomationFrameworkEnum),
+    detectedTestingFramework: z.nativeEnum(SDKSupportedTestingFrameworkEnum),
+    integrationType: z
+        .nativeEnum(PercyIntegrationTypeEnum)
+        .describe("Specifies whether to integrate with Percy Web or Percy Automate. If not explicitly provided, prompt the user to select the desired integration type."),
+    folderPaths: z
+        .array(z.string())
+        .describe("An array of folder paths to include in which Percy will be integrated. If not provided, strictly inspect the code and return the folders which contain UI test cases."),
+};
+export const RunTestsOnBrowserStackParamsShape = {
+    projectName: z
+        .string()
+        .describe("A single name for your project to organize all your tests. This is required for Percy."),
+    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."),
+};
+export const SetUpPercySchema = z.object(SetUpPercyParamsShape);
+export const RunTestsOnBrowserStackSchema = z.object(RunTestsOnBrowserStackParamsShape);

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

@@ -0,0 +1,66 @@
+export declare enum PercyIntegrationTypeEnum {
+    WEB = "web",
+    AUTOMATE = "automate"
+}
+export declare enum SDKSupportedLanguageEnum {
+    nodejs = "nodejs",
+    python = "python",
+    java = "java",
+    csharp = "csharp",
+    ruby = "ruby"
+}
+export type SDKSupportedLanguage = keyof typeof SDKSupportedLanguageEnum;
+export declare enum SDKSupportedBrowserAutomationFrameworkEnum {
+    playwright = "playwright",
+    selenium = "selenium",
+    cypress = "cypress"
+}
+export type SDKSupportedBrowserAutomationFramework = keyof typeof SDKSupportedBrowserAutomationFrameworkEnum;
+export declare enum SDKSupportedTestingFrameworkEnum {
+    jest = "jest",
+    codeceptjs = "codeceptjs",
+    playwright = "playwright",
+    pytest = "pytest",
+    robot = "robot",
+    behave = "behave",
+    cucumber = "cucumber",
+    nightwatch = "nightwatch",
+    webdriverio = "webdriverio",
+    mocha = "mocha",
+    junit4 = "junit4",
+    junit5 = "junit5",
+    testng = "testng",
+    cypress = "cypress",
+    nunit = "nunit",
+    mstest = "mstest",
+    xunit = "xunit",
+    specflow = "specflow",
+    reqnroll = "reqnroll",
+    rspec = "rspec",
+    serenity = "serenity"
+}
+export declare const SDKSupportedLanguages: SDKSupportedLanguageEnum[];
+export type SDKSupportedTestingFramework = keyof typeof SDKSupportedTestingFrameworkEnum;
+export declare const SDKSupportedTestingFrameworks: SDKSupportedTestingFrameworkEnum[];
+export type ConfigMapping = Partial<Record<SDKSupportedLanguageEnum, Partial<Record<SDKSupportedBrowserAutomationFrameworkEnum, Partial<Record<SDKSupportedTestingFrameworkEnum, {
+    instructions: (username: string, accessKey: string) => {
+        setup: string;
+        run: string;
+    };
+}>>>>>>;
+export interface RunTestsStep {
+    type: "instruction" | "error" | "warning";
+    title: string;
+    content: string;
+    isError?: boolean;
+}
+export interface RunTestsInstructionResult {
+    steps: RunTestsStep[];
+    requiresPercy: boolean;
+    missingDependencies: string[];
+    shouldSkipFormatting?: boolean;
+}
+export declare enum PercyAutomateNotImplementedType {
+    LANGUAGE = "language",
+    FRAMEWORK = "framework"
+}

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

@@ -0,0 +1,50 @@
+export var PercyIntegrationTypeEnum;
+(function (PercyIntegrationTypeEnum) {
+    PercyIntegrationTypeEnum["WEB"] = "web";
+    PercyIntegrationTypeEnum["AUTOMATE"] = "automate";
+})(PercyIntegrationTypeEnum || (PercyIntegrationTypeEnum = {}));
+export var SDKSupportedLanguageEnum;
+(function (SDKSupportedLanguageEnum) {
+    SDKSupportedLanguageEnum["nodejs"] = "nodejs";
+    SDKSupportedLanguageEnum["python"] = "python";
+    SDKSupportedLanguageEnum["java"] = "java";
+    SDKSupportedLanguageEnum["csharp"] = "csharp";
+    SDKSupportedLanguageEnum["ruby"] = "ruby";
+})(SDKSupportedLanguageEnum || (SDKSupportedLanguageEnum = {}));
+export var SDKSupportedBrowserAutomationFrameworkEnum;
+(function (SDKSupportedBrowserAutomationFrameworkEnum) {
+    SDKSupportedBrowserAutomationFrameworkEnum["playwright"] = "playwright";
+    SDKSupportedBrowserAutomationFrameworkEnum["selenium"] = "selenium";
+    SDKSupportedBrowserAutomationFrameworkEnum["cypress"] = "cypress";
+})(SDKSupportedBrowserAutomationFrameworkEnum || (SDKSupportedBrowserAutomationFrameworkEnum = {}));
+export var SDKSupportedTestingFrameworkEnum;
+(function (SDKSupportedTestingFrameworkEnum) {
+    SDKSupportedTestingFrameworkEnum["jest"] = "jest";
+    SDKSupportedTestingFrameworkEnum["codeceptjs"] = "codeceptjs";
+    SDKSupportedTestingFrameworkEnum["playwright"] = "playwright";
+    SDKSupportedTestingFrameworkEnum["pytest"] = "pytest";
+    SDKSupportedTestingFrameworkEnum["robot"] = "robot";
+    SDKSupportedTestingFrameworkEnum["behave"] = "behave";
+    SDKSupportedTestingFrameworkEnum["cucumber"] = "cucumber";
+    SDKSupportedTestingFrameworkEnum["nightwatch"] = "nightwatch";
+    SDKSupportedTestingFrameworkEnum["webdriverio"] = "webdriverio";
+    SDKSupportedTestingFrameworkEnum["mocha"] = "mocha";
+    SDKSupportedTestingFrameworkEnum["junit4"] = "junit4";
+    SDKSupportedTestingFrameworkEnum["junit5"] = "junit5";
+    SDKSupportedTestingFrameworkEnum["testng"] = "testng";
+    SDKSupportedTestingFrameworkEnum["cypress"] = "cypress";
+    SDKSupportedTestingFrameworkEnum["nunit"] = "nunit";
+    SDKSupportedTestingFrameworkEnum["mstest"] = "mstest";
+    SDKSupportedTestingFrameworkEnum["xunit"] = "xunit";
+    SDKSupportedTestingFrameworkEnum["specflow"] = "specflow";
+    SDKSupportedTestingFrameworkEnum["reqnroll"] = "reqnroll";
+    SDKSupportedTestingFrameworkEnum["rspec"] = "rspec";
+    SDKSupportedTestingFrameworkEnum["serenity"] = "serenity";
+})(SDKSupportedTestingFrameworkEnum || (SDKSupportedTestingFrameworkEnum = {}));
+export const SDKSupportedLanguages = Object.values(SDKSupportedLanguageEnum);
+export const SDKSupportedTestingFrameworks = Object.values(SDKSupportedTestingFrameworkEnum);
+export var PercyAutomateNotImplementedType;
+(function (PercyAutomateNotImplementedType) {
+    PercyAutomateNotImplementedType["LANGUAGE"] = "language";
+    PercyAutomateNotImplementedType["FRAMEWORK"] = "framework";
+})(PercyAutomateNotImplementedType || (PercyAutomateNotImplementedType = {}));

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

@@ -0,0 +1,25 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { PercyIntegrationTypeEnum } from "../common/types.js";
+import { RunTestsInstructionResult, PercyAutomateNotImplementedType } from "./types.js";
+export declare function checkPercyIntegrationSupport(input: {
+    integrationType: string;
+    detectedLanguage: string;
+    detectedTestingFramework?: string;
+    detectedBrowserAutomationFramework?: string;
+}): {
+    supported: boolean;
+    errorMessage?: string;
+};
+export declare function formatToolResult(resultPromise: Promise<RunTestsInstructionResult> | RunTestsInstructionResult): Promise<CallToolResult>;
+export declare function getPercyAutomateNotImplementedMessage(type: PercyAutomateNotImplementedType, input: {
+    detectedLanguage: string;
+    detectedBrowserAutomationFramework: string;
+}, supported: string[]): string;
+export declare function getBootstrapFailedMessage(error: unknown, context: {
+    config: unknown;
+    percyMode?: string;
+    sdkVersion?: string;
+}): string;
+export declare function percyUnsupportedResult(integrationType: PercyIntegrationTypeEnum, supportCheck?: {
+    errorMessage?: string;
+}): CallToolResult;

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

@@ -0,0 +1,84 @@
+import { PercyIntegrationTypeEnum } from "../common/types.js";
+import { isPercyAutomateFrameworkSupported } from "../percy-automate/frameworks.js";
+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";
+export function checkPercyIntegrationSupport(input) {
+    if (input.integrationType === PercyIntegrationTypeEnum.AUTOMATE) {
+        const isSupported = isPercyAutomateFrameworkSupported(input.detectedLanguage, input.detectedBrowserAutomationFramework || "", input.detectedTestingFramework || "");
+        if (!isSupported) {
+            return {
+                supported: false,
+                errorMessage: `Percy Automate is not supported for this configuration. Language: ${input.detectedLanguage} Testing Framework: ${input.detectedTestingFramework}`,
+            };
+        }
+    }
+    else if (input.integrationType === PercyIntegrationTypeEnum.WEB) {
+        const isSupported = isPercyWebFrameworkSupported(input.detectedLanguage, input.detectedBrowserAutomationFramework || "");
+        if (!isSupported) {
+            return {
+                supported: false,
+                errorMessage: `Percy Web is not supported for this configuration. Language: ${input.detectedLanguage} Browser Automation Framework: ${input.detectedBrowserAutomationFramework}`,
+            };
+        }
+    }
+    return { supported: true };
+}
+export async function formatToolResult(resultPromise) {
+    const { steps, requiresPercy, missingDependencies, shouldSkipFormatting } = await resultPromise;
+    if (shouldSkipFormatting) {
+        return {
+            content: steps.map((step) => ({
+                type: "text",
+                text: step.content,
+            })),
+            isError: steps.some((s) => s.isError),
+            steps,
+            requiresPercy,
+            missingDependencies,
+        };
+    }
+    const combinedInstructions = steps.map((step) => step.content).join("\n");
+    const { formattedSteps, stepCount } = formatInstructionsWithNumbers(combinedInstructions);
+    const verificationMessage = generateVerificationMessage(stepCount);
+    const finalContent = [
+        { type: "text", text: IMPORTANT_SETUP_WARNING },
+        { type: "text", text: formattedSteps },
+        { type: "text", text: verificationMessage },
+    ];
+    return {
+        content: finalContent,
+        isError: steps.some((s) => s.isError),
+        requiresPercy,
+        missingDependencies,
+    };
+}
+export function getPercyAutomateNotImplementedMessage(type, input, supported) {
+    if (type === PercyAutomateNotImplementedType.LANGUAGE) {
+        return `Percy Automate does not support the language: ${input.detectedLanguage}. Supported languages are: ${supported.join(", ")}.`;
+    }
+    else {
+        return `Percy Automate does not support ${input.detectedBrowserAutomationFramework} for ${input.detectedLanguage}. Supported frameworks for ${input.detectedLanguage} are: ${supported.join(", ")}.`;
+    }
+}
+export function getBootstrapFailedMessage(error, context) {
+    return `Failed to bootstrap project with BrowserStack SDK.
+Error: ${error}
+Percy Mode: ${context.percyMode ?? "automate"}
+SDK Version: ${context.sdkVersion ?? "N/A"}
+Please open an issue on GitHub if the problem persists.`;
+}
+export function percyUnsupportedResult(integrationType, supportCheck) {
+    const defaultMessage = `Percy ${integrationType} integration is not supported for this configuration.`;
+    return {
+        content: [
+            {
+                type: "text",
+                text: supportCheck?.errorMessage || defaultMessage,
+            },
+        ],
+        isError: true,
+        shouldSkipFormatting: true,
+    };
+}

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

@@ -0,0 +1,5 @@
+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 setUpSimulatePercyChangeHandler(rawInput: unknown, config: BrowserStackConfig): Promise<CallToolResult>;