@browserstack/mcp-server 1.2.3 → 1.2.4

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

@@ -0,0 +1,17 @@
+import { AppSDKSupportedTestingFramework } from "./index.js";
+import { SUPPORTED_CONFIGURATIONS } from "./types.js";
+export declare function isBrowserStackAppUrl(appPath: string): boolean;
+export declare function generateBuildName(baseName?: string): string;
+export declare function createError(message: string, context?: Record<string, any>): Error;
+export declare const PLATFORM_UTILS: {
+    isWindows: boolean;
+    isMac: boolean;
+    isAppleSilicon: boolean;
+    getPlatformLabel: () => "Windows" | "macOS";
+};
+export declare function getAppUploadInstruction(appPath: string, username: string, accessKey: string, detectedTestingFramework: AppSDKSupportedTestingFramework): Promise<string>;
+export type SupportedFramework = keyof typeof SUPPORTED_CONFIGURATIONS;
+type SupportedLanguage = keyof (typeof SUPPORTED_CONFIGURATIONS)[SupportedFramework];
+type SupportedTestingFramework = string;
+export declare function validateSupportforAppAutomate(framework: SupportedFramework, language: SupportedLanguage, testingFramework: SupportedTestingFramework): void;
+export {};

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

@@ -0,0 +1,64 @@
+import { uploadApp } from "../native-execution/appautomate.js";
+import { AppSDKSupportedTestingFrameworkEnum, createStep, } from "./index.js";
+import { SUPPORTED_CONFIGURATIONS } from "./types.js";
+export function isBrowserStackAppUrl(appPath) {
+    return appPath.startsWith("bs://");
+}
+export function generateBuildName(baseName = "app-automate") {
+    const timestamp = new Date().toISOString().slice(0, 19).replace(/[:-]/g, "");
+    return `${baseName}-${timestamp}`;
+}
+export function createError(message, context) {
+    const error = new Error(message);
+    if (context) {
+        error.context = context;
+    }
+    return error;
+}
+// Platform utilities for cross-platform support
+export const PLATFORM_UTILS = {
+    isWindows: process.platform === "win32",
+    isMac: process.platform === "darwin",
+    isAppleSilicon: process.platform === "darwin" && process.arch === "arm64",
+    getPlatformLabel: () => {
+        switch (process.platform) {
+            case "win32":
+                return "Windows";
+            case "darwin":
+                return "macOS";
+            default:
+                return "macOS";
+        }
+    },
+};
+export async function getAppUploadInstruction(appPath, username, accessKey, detectedTestingFramework) {
+    if (detectedTestingFramework ===
+        AppSDKSupportedTestingFrameworkEnum.nightwatch ||
+        detectedTestingFramework ===
+            AppSDKSupportedTestingFrameworkEnum.webdriverio ||
+        detectedTestingFramework ===
+            AppSDKSupportedTestingFrameworkEnum.cucumberRuby) {
+        const app_url = await uploadApp(appPath, username, accessKey);
+        if (app_url) {
+            return createStep("Updating app_path with app_url", `Replace the value of app_path in your configuration with: ${app_url}`);
+        }
+    }
+    return "";
+}
+export function validateSupportforAppAutomate(framework, language, testingFramework) {
+    const frameworks = Object.keys(SUPPORTED_CONFIGURATIONS);
+    if (!SUPPORTED_CONFIGURATIONS[framework]) {
+        throw new Error(`Unsupported framework '${framework}'. Supported frameworks: ${frameworks.join(", ")}`);
+    }
+    const languages = Object.keys(SUPPORTED_CONFIGURATIONS[framework]);
+    if (!SUPPORTED_CONFIGURATIONS[framework][language]) {
+        throw new Error(`Unsupported language '${language}' for framework '${framework}'. Supported languages: ${languages.join(", ")}`);
+    }
+    const testingFrameworks = SUPPORTED_CONFIGURATIONS[framework][language];
+    if (testingFrameworks.length === 0) {
+        throw new Error(`No testing frameworks are supported for language '${language}' and framework '${framework}'.`);
+    }
+    if (!testingFrameworks.includes(testingFramework)) {
+        throw new Error(`Unsupported testing framework '${testingFramework}' for language '${language}' and framework '${framework}'. Supported testing frameworks: ${testingFrameworks.join(", ")}`);
+    }
+}

package/dist/tools/appautomate-utils/{appautomate.d.ts → native-execution/appautomate.d.ts}

@@ -1,4 +1,4 @@
-import { BrowserStackConfig } from "../../lib/types.js";
+import { BrowserStackConfig } from "../../../lib/types.js";
 interface Device {
     device: string;
     display_name: string;

package/dist/tools/appautomate-utils/{appautomate.js → native-execution/appautomate.js}

@@ -1,7 +1,7 @@
 import fs from "fs";
 import FormData from "form-data";
-import { apiClient } from "../../lib/apiClient.js";
-import { customFuzzySearch } from "../../lib/fuzzy.js";
+import { apiClient } from "../../../lib/apiClient.js";
+import { customFuzzySearch } from "../../../lib/fuzzy.js";
 /**
  * Finds devices that exactly match the provided display name.
  * Uses fuzzy search first, and then filters for exact case-insensitive match.

package/dist/tools/appautomate-utils/native-execution/constants.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { AppTestPlatform } from "./types.js";
+export declare const RUN_APP_AUTOMATE_DESCRIPTION = "Execute pre-built native mobile test suites (Espresso for Android, XCUITest for iOS) by direct upload to BrowserStack. ONLY for compiled .apk/.ipa test files. This is NOT for SDK integration or Appium tests. For Appium-based testing with SDK setup, use 'setupBrowserStackAppAutomateTests' instead.";
+export declare const RUN_APP_AUTOMATE_SCHEMA: {
+    appPath: z.ZodString;
+    testSuitePath: z.ZodString;
+    devices: z.ZodArray<z.ZodString, "many">;
+    project: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    detectedAutomationFramework: z.ZodNativeEnum<typeof AppTestPlatform>;
+};

package/dist/tools/appautomate-utils/native-execution/constants.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { AppTestPlatform } from "./types.js";
+export const RUN_APP_AUTOMATE_DESCRIPTION = `Execute pre-built native mobile test suites (Espresso for Android, XCUITest for iOS) by direct upload to BrowserStack. ONLY for compiled .apk/.ipa test files. This is NOT for SDK integration or Appium tests. For Appium-based testing with SDK setup, use 'setupBrowserStackAppAutomateTests' instead.`;
+export const RUN_APP_AUTOMATE_SCHEMA = {
+    appPath: z
+        .string()
+        .describe("Path to your application file:\n" +
+        "If in development IDE directory:\n" +
+        "• For Android: 'gradle assembleDebug'\n" +
+        "• For iOS:\n" +
+        "  xcodebuild clean -scheme YOUR_SCHEME && \\\n" +
+        "  xcodebuild archive -scheme YOUR_SCHEME -configuration Release -archivePath build/app.xcarchive && \\\n" +
+        "  xcodebuild -exportArchive -archivePath build/app.xcarchive -exportPath build/ipa -exportOptionsPlist exportOptions.plist\n\n" +
+        "If in other directory, provide existing app path"),
+    testSuitePath: z
+        .string()
+        .describe("Path to your test suite file:\n" +
+        "If in development IDE directory:\n" +
+        "• For Android: 'gradle assembleAndroidTest'\n" +
+        "• For iOS:\n" +
+        "  xcodebuild test-without-building -scheme YOUR_SCHEME -destination 'generic/platform=iOS' && \\\n" +
+        "  cd ~/Library/Developer/Xcode/DerivedData/*/Build/Products/Debug-iphonesimulator/ && \\\n" +
+        "  zip -r Tests.zip *.xctestrun *-Runner.app\n\n" +
+        "If in other directory, provide existing test file path"),
+    devices: z
+        .array(z.string())
+        .describe("List of devices to run the test on, e.g., ['Samsung Galaxy S20-10.0', 'iPhone 12 Pro-16.0']."),
+    project: z
+        .string()
+        .optional()
+        .default("BStack-AppAutomate-Suite")
+        .describe("Project name for organizing test runs on BrowserStack."),
+    detectedAutomationFramework: z
+        .nativeEnum(AppTestPlatform)
+        .describe("The automation framework used in the project, such as 'espresso' (Android) or 'xcuitest' (iOS)."),
+};

package/dist/tools/appautomate-utils/native-execution/types.d.ts

@@ -0,0 +1,19 @@
+export declare enum AppTestPlatform {
+    ESPRESSO = "espresso",
+    XCUITEST = "xcuitest"
+}
+export interface Device {
+    device: string;
+    display_name: string;
+    os_version: string;
+    real_mobile: boolean;
+}
+export interface PlatformDevices {
+    os: string;
+    os_display_name: string;
+    devices: Device[];
+}
+export declare enum Platform {
+    ANDROID = "android",
+    IOS = "ios"
+}

package/dist/tools/appautomate-utils/{types.js → native-execution/types.js}

@@ -1,6 +1,10 @@
 export var AppTestPlatform;
 (function (AppTestPlatform) {
     AppTestPlatform["ESPRESSO"] = "espresso";
-    AppTestPlatform["APPIUM"] = "appium";
     AppTestPlatform["XCUITEST"] = "xcuitest";
 })(AppTestPlatform || (AppTestPlatform = {}));
+export var Platform;
+(function (Platform) {
+    Platform["ANDROID"] = "android";
+    Platform["IOS"] = "ios";
+})(Platform || (Platform = {}));

package/dist/tools/appautomate.js

@@ -4,14 +4,13 @@ import { getBrowserStackAuth } from "../lib/get-auth.js";
 import { trackMCP } from "../lib/instrumentation.js";
 import { maybeCompressBase64 } from "../lib/utils.js";
 import { remote } from "webdriverio";
-import { AppTestPlatform } from "./appautomate-utils/types.js";
+import { AppTestPlatform } from "./appautomate-utils/native-execution/types.js";
+import { setupAppAutomateHandler } from "./appautomate-utils/appium-sdk/handler.js";
+import { SETUP_APP_AUTOMATE_DESCRIPTION, SETUP_APP_AUTOMATE_SCHEMA, } from "./appautomate-utils/appium-sdk/constants.js";
+import { Platform, } from "./appautomate-utils/native-execution/types.js";
 import { getDevicesAndBrowsers, BrowserStackProducts, } from "../lib/device-cache.js";
-import { findMatchingDevice, getDeviceVersions, resolveVersion, validateArgs, uploadApp, uploadEspressoApp, uploadEspressoTestSuite, triggerEspressoBuild, uploadXcuiApp, uploadXcuiTestSuite, triggerXcuiBuild, } from "./appautomate-utils/appautomate.js";
-var Platform;
-(function (Platform) {
-    Platform["ANDROID"] = "android";
-    Platform["IOS"] = "ios";
-})(Platform || (Platform = {}));
+import { findMatchingDevice, getDeviceVersions, resolveVersion, validateArgs, uploadApp, uploadEspressoApp, uploadEspressoTestSuite, triggerEspressoBuild, uploadXcuiApp, uploadXcuiTestSuite, triggerXcuiBuild, } from "./appautomate-utils/native-execution/appautomate.js";
+import { RUN_APP_AUTOMATE_DESCRIPTION, RUN_APP_AUTOMATE_SCHEMA, } from "./appautomate-utils/native-execution/constants.js";
 /**
  * Launches an app on a selected BrowserStack device and takes a screenshot.
  */
@@ -214,39 +213,7 @@ export default function addAppAutomationTools(server, config) {
             };
         }
     });
-    tools.runAppTestsOnBrowserStack = server.tool("runAppTestsOnBrowserStack", "Run AppAutomate tests on BrowserStack by uploading app and test suite. If running from Android Studio or Xcode, the tool will help export app and test files automatically. For other environments, you'll need to provide the paths to your pre-built app and test files.", {
-        appPath: z
-            .string()
-            .describe("Path to your application file:\n" +
-            "If in development IDE directory:\n" +
-            "• For Android: 'gradle assembleDebug'\n" +
-            "• For iOS:\n" +
-            "  xcodebuild clean -scheme YOUR_SCHEME && \\\n" +
-            "  xcodebuild archive -scheme YOUR_SCHEME -configuration Release -archivePath build/app.xcarchive && \\\n" +
-            "  xcodebuild -exportArchive -archivePath build/app.xcarchive -exportPath build/ipa -exportOptionsPlist exportOptions.plist\n\n" +
-            "If in other directory, provide existing app path"),
-        testSuitePath: z
-            .string()
-            .describe("Path to your test suite file:\n" +
-            "If in development IDE directory:\n" +
-            "• For Android: 'gradle assembleAndroidTest'\n" +
-            "• For iOS:\n" +
-            "  xcodebuild test-without-building -scheme YOUR_SCHEME -destination 'generic/platform=iOS' && \\\n" +
-            "  cd ~/Library/Developer/Xcode/DerivedData/*/Build/Products/Debug-iphonesimulator/ && \\\n" +
-            "  zip -r Tests.zip *.xctestrun *-Runner.app\n\n" +
-            "If in other directory, provide existing test file path"),
-        devices: z
-            .array(z.string())
-            .describe("List of devices to run the test on, e.g., ['Samsung Galaxy S20-10.0', 'iPhone 12 Pro-16.0']."),
-        project: z
-            .string()
-            .optional()
-            .default("BStack-AppAutomate-Suite")
-            .describe("Project name for organizing test runs on BrowserStack."),
-        detectedAutomationFramework: z
-            .string()
-            .describe("The automation framework used in the project, such as 'espresso' (Android) or 'xcuitest' (iOS)."),
-    }, async (args) => {
+    tools.runAppTestsOnBrowserStack = server.tool("runAppTestsOnBrowserStack", RUN_APP_AUTOMATE_DESCRIPTION, RUN_APP_AUTOMATE_SCHEMA, async (args) => {
         try {
             trackMCP("runAppTestsOnBrowserStack", server.server.getClientVersion(), undefined, config);
             return await runAppTestsOnBrowserStack(args, config);
@@ -265,5 +232,23 @@ export default function addAppAutomationTools(server, config) {
             };
         }
     });
+    tools.setupBrowserStackAppAutomateTests = server.tool("setupBrowserStackAppAutomateTests", SETUP_APP_AUTOMATE_DESCRIPTION, SETUP_APP_AUTOMATE_SCHEMA, async (args) => {
+        try {
+            return await setupAppAutomateHandler(args, config);
+        }
+        catch (error) {
+            const error_message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to bootstrap project with BrowserStack App Automate SDK. Error: ${error_message}. Please open an issue on GitHub if the problem persists`,
+                        isError: true,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
     return tools;
 }

package/dist/tools/bstack-sdk.d.ts

@@ -1,17 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { SDKSupportedBrowserAutomationFramework, SDKSupportedLanguage, SDKSupportedTestingFramework } from "./sdk-utils/types.js";
 import { BrowserStackConfig } from "../lib/types.js";
-/**
- * BrowserStack SDK hooks into your test framework to seamlessly run tests on BrowserStack.
- * This tool gives instructions to setup a browserstack.yml file in the project root and installs the necessary dependencies.
- */
-export declare function bootstrapProjectWithSDK({ detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, desiredPlatforms, enablePercy, config, }: {
-    detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFramework;
-    detectedTestingFramework: SDKSupportedTestingFramework;
-    detectedLanguage: SDKSupportedLanguage;
-    desiredPlatforms: string[];
-    enablePercy: boolean;
-    config: BrowserStackConfig;
-}): Promise<CallToolResult>;
-export default function addSDKTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;
+export declare function registerRunBrowserStackTestsTool(server: McpServer, config: BrowserStackConfig): Record<string, any>;
+export default registerRunBrowserStackTestsTool;

package/dist/tools/bstack-sdk.js

@@ -1,128 +1,19 @@
-import { z } from "zod";
+import { RunTestsOnBrowserStackParamsShape } from "./sdk-utils/common/schema.js";
+import { runTestsOnBrowserStackHandler } from "./sdk-utils/handler.js";
+import { RUN_ON_BROWSERSTACK_DESCRIPTION } from "./sdk-utils/common/constants.js";
+import { handleMCPError } from "../lib/utils.js";
 import { trackMCP } from "../lib/instrumentation.js";
-import { getSDKPrefixCommand } from "./sdk-utils/commands.js";
-import { SDKSupportedLanguageEnum, SDKSupportedBrowserAutomationFrameworkEnum, SDKSupportedTestingFrameworkEnum, } from "./sdk-utils/types.js";
-import { generateBrowserStackYMLInstructions, getInstructionsForProjectConfiguration, formatInstructionsWithNumbers, } from "./sdk-utils/instructions.js";
-import { formatPercyInstructions, getPercyInstructions, } from "./sdk-utils/percy/instructions.js";
-import { getBrowserStackAuth } from "../lib/get-auth.js";
-/**
- * BrowserStack SDK hooks into your test framework to seamlessly run tests on BrowserStack.
- * This tool gives instructions to setup a browserstack.yml file in the project root and installs the necessary dependencies.
- */
-export async function bootstrapProjectWithSDK({ detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, desiredPlatforms, enablePercy, config, }) {
-    // Get credentials from config
-    const authString = getBrowserStackAuth(config);
-    const [username, accessKey] = authString.split(":");
-    // Handle frameworks with unique setup instructions that don't use browserstack.yml
-    if (detectedBrowserAutomationFramework === "cypress" ||
-        detectedTestingFramework === "webdriverio") {
-        let combinedInstructions = getInstructionsForProjectConfiguration(detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, username, accessKey);
-        if (enablePercy) {
-            const percyInstructions = getPercyInstructions(detectedLanguage, detectedBrowserAutomationFramework, detectedTestingFramework);
-            if (percyInstructions) {
-                combinedInstructions +=
-                    "\n\n" + formatPercyInstructions(percyInstructions);
-            }
-            else {
-                throw new Error(`Percy is currently not supported through MCP for ${detectedLanguage} with ${detectedTestingFramework}. If you want to run the test cases without Percy, disable Percy and run it again.`);
-            }
-        }
-        // Apply consistent formatting for all configurations
-        return formatFinalInstructions(combinedInstructions);
-    }
-    // Handle default flow using browserstack.yml
-    const sdkSetupCommand = getSDKPrefixCommand(detectedLanguage, detectedTestingFramework, username, accessKey);
-    const ymlInstructions = generateBrowserStackYMLInstructions(desiredPlatforms, enablePercy);
-    const instructionsForProjectConfiguration = getInstructionsForProjectConfiguration(detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, username, accessKey);
-    let combinedInstructions = "";
-    // Step 1: Add SDK setup command
-    if (sdkSetupCommand) {
-        combinedInstructions += sdkSetupCommand;
-    }
-    // Step 2: Add browserstack.yml setup
-    if (ymlInstructions) {
-        combinedInstructions += "\n\n---STEP---\n" + ymlInstructions;
-    }
-    // Step 3: Add language/framework-specific setup
-    if (instructionsForProjectConfiguration) {
-        combinedInstructions += "\n\n" + instructionsForProjectConfiguration;
-    }
-    // Step 4: Add Percy setup if applicable
-    if (enablePercy) {
-        const percyInstructions = getPercyInstructions(detectedLanguage, detectedBrowserAutomationFramework, detectedTestingFramework);
-        if (percyInstructions) {
-            combinedInstructions +=
-                "\n\n" + formatPercyInstructions(percyInstructions);
-        }
-        else {
-            throw new Error(`Percy is currently not supported through MCP for ${detectedLanguage} with ${detectedTestingFramework}. If you want to run the test cases without Percy, disable Percy and run it again.`);
-        }
-    }
-    // Apply consistent formatting for all configurations
-    return formatFinalInstructions(combinedInstructions);
-}
-// Helper function to apply consistent formatting to all instruction types
-function formatFinalInstructions(combinedInstructions) {
-    const fullInstructions = `⚠️ IMPORTANT: DO NOT SKIP ANY STEP
-  All the setup steps described in this file MUST be executed regardless of any existing configuration or setup.
-  This ensures proper BrowserStack SDK setup.
-
-  ${formatInstructionsWithNumbers(combinedInstructions)}`;
-    return {
-        content: [
-            {
-                type: "text",
-                text: fullInstructions,
-                isError: false,
-            },
-        ],
-    };
-}
-export default function addSDKTools(server, config) {
+export function registerRunBrowserStackTestsTool(server, config) {
     const tools = {};
-    tools.setupBrowserStackAutomateTests = server.tool("setupBrowserStackAutomateTests", "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use for functional or integration tests on BrowserStack, with optional Percy visual testing for supported frameworks. Example prompts: run this test on browserstack; run this test on browserstack with Percy; set up this project for browserstack with Percy. Integrate BrowserStack SDK into your project", {
-        detectedBrowserAutomationFramework: z
-            .nativeEnum(SDKSupportedBrowserAutomationFrameworkEnum)
-            .describe("The automation framework configured in the project. Example: 'playwright', 'selenium'"),
-        detectedTestingFramework: z
-            .nativeEnum(SDKSupportedTestingFrameworkEnum)
-            .describe("The testing framework used in the project. Be precise with framework selection Example: 'webdriverio', 'jest', 'pytest', 'junit4', 'junit5', 'mocha'"),
-        detectedLanguage: z
-            .nativeEnum(SDKSupportedLanguageEnum)
-            .describe("The programming language used in the project. Example: 'nodejs', 'python', 'java', 'csharp'"),
-        desiredPlatforms: z
-            .array(z.enum(["windows", "macos", "android", "ios"]))
-            .describe("The platforms the user wants to test on. Always ask this to the user, do not try to infer this."),
-        enablePercy: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Set to true if the user wants to enable Percy for visual testing. Defaults to false."),
-    }, async (args) => {
+    tools.setupBrowserStackAutomateTests = server.tool("setupBrowserStackAutomateTests", RUN_ON_BROWSERSTACK_DESCRIPTION, RunTestsOnBrowserStackParamsShape, async (args) => {
         try {
-            trackMCP("runTestsOnBrowserStack", server.server.getClientVersion(), undefined, config);
-            return await bootstrapProjectWithSDK({
-                detectedBrowserAutomationFramework: args.detectedBrowserAutomationFramework,
-                detectedTestingFramework: args.detectedTestingFramework,
-                detectedLanguage: args.detectedLanguage,
-                desiredPlatforms: args.desiredPlatforms,
-                enablePercy: args.enablePercy,
-                config,
-            });
+            trackMCP("runTestsOnBrowserStack", server.server.getClientVersion(), config);
+            return await runTestsOnBrowserStackHandler(args, config);
         }
         catch (error) {
-            trackMCP("runTestsOnBrowserStack", server.server.getClientVersion(), error, config);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Failed to bootstrap project with BrowserStack SDK. Error: ${error}. Please open an issue on GitHub if the problem persists`,
-                        isError: true,
-                    },
-                ],
-                isError: true,
-            };
+            return handleMCPError("runTestsOnBrowserStack", server, config, error);
         }
     });
     return tools;
 }
+export default registerRunBrowserStackTestsTool;

package/dist/tools/build-insights.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { BrowserStackConfig } from "../lib/types.js";
+export declare function fetchBuildInsightsTool(args: {
+    buildId: string;
+}, config: BrowserStackConfig): Promise<CallToolResult>;
+export default function addBuildInsightsTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/build-insights.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import logger from "../logger.js";
+import { fetchFromBrowserStackAPI, handleMCPError } from "../lib/utils.js";
+import { trackMCP } from "../lib/instrumentation.js";
+// Tool function that fetches build insights from two APIs
+export async function fetchBuildInsightsTool(args, config) {
+    try {
+        const buildUrl = `https://api-automation.browserstack.com/ext/v1/builds/${args.buildId}`;
+        const qualityGateUrl = `https://api-automation.browserstack.com/ext/v1/quality-gates/${args.buildId}`;
+        const [buildData, qualityData] = await Promise.all([
+            fetchFromBrowserStackAPI(buildUrl, config),
+            fetchFromBrowserStackAPI(qualityGateUrl, config),
+        ]);
+        // Select useful fields for users
+        const insights = {
+            name: buildData.name,
+            status: buildData.status,
+            duration: buildData.duration,
+            user: buildData.user,
+            tags: buildData.tags,
+            alerts: buildData.alerts,
+            status_stats: buildData.status_stats,
+            failure_categories: buildData.failure_categories,
+            smart_tags: buildData.smart_tags,
+            unique_errors: buildData.unique_errors?.overview,
+            observability_url: buildData?.observability_url,
+            ci_build_url: buildData.ci_info?.build_url,
+            quality_gate_result: qualityData.quality_gate_result,
+        };
+        const qualityProfiles = qualityData.quality_profiles?.map((profile) => ({
+            name: profile.name,
+            result: profile.result,
+        }));
+        const qualityProfilesText = qualityProfiles && qualityProfiles.length > 0
+            ? `Quality Gate Profiles (respond only if explicitly requested): ${JSON.stringify(qualityProfiles, null, 2)}`
+            : "No Quality Gate Profiles available.";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Build insights:\n" + JSON.stringify(insights, null, 2),
+                },
+                { type: "text", text: qualityProfilesText },
+            ],
+        };
+    }
+    catch (error) {
+        logger.error("Error fetching build insights", error);
+        throw error;
+    }
+}
+// Registers the fetchBuildInsights tool with the MCP server
+export default function addBuildInsightsTools(server, config) {
+    const tools = {};
+    tools.fetchBuildInsights = server.tool("fetchBuildInsights", "Fetches insights about a BrowserStack build by combining build details and quality gate results.", {
+        buildId: z.string().describe("The build UUID of the BrowserStack build"),
+    }, async (args) => {
+        try {
+            trackMCP("fetchBuildInsights", server.server.getClientVersion(), config);
+            return await fetchBuildInsightsTool(args, config);
+        }
+        catch (error) {
+            return handleMCPError("fetchBuildInsights", server, config, error);
+        }
+    });
+    return tools;
+}

package/dist/tools/list-test-files.d.ts

@@ -0,0 +1,2 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function addListTestFiles(args: any): Promise<CallToolResult>;

package/dist/tools/list-test-files.js

@@ -0,0 +1,36 @@
+import { listTestFiles } from "./percy-snapshot-utils/detect-test-files.js";
+import { testFilePathsMap } from "../lib/inmemory-store.js";
+import crypto from "crypto";
+export async function addListTestFiles(args) {
+    const { dirs, language, framework } = args;
+    let testFiles = [];
+    if (!dirs || dirs.length === 0) {
+        throw new Error("No directories provided to add the test files. Please provide test directories to add percy snapshot commands.");
+    }
+    for (const dir of dirs) {
+        const files = await listTestFiles({
+            language,
+            framework,
+            baseDir: dir,
+        });
+        testFiles = testFiles.concat(files);
+    }
+    if (testFiles.length === 0) {
+        throw new Error("No test files found");
+    }
+    // Generate a UUID and store the test files in memory
+    const uuid = crypto.randomUUID();
+    testFilePathsMap.set(uuid, testFiles);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `The Test files are stored in memory with id ${uuid} and the total number of tests files found is ${testFiles.length}. You can use this UUID to retrieve the tests file paths later.`,
+            },
+            {
+                type: "text",
+                text: `You can now use the tool addPercySnapshotCommands to update the test file with Percy commands for visual testing with the UUID ${uuid}`,
+            },
+        ],
+    };
+}

package/dist/tools/percy-sdk.d.ts

@@ -0,0 +1,4 @@
+import { BrowserStackConfig } from "../lib/types.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPercyTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;
+export default registerPercyTools;

package/dist/tools/percy-sdk.js

@@ -0,0 +1,71 @@
+import { trackMCP } from "../index.js";
+import { fetchPercyChanges } from "./review-agent.js";
+import { addListTestFiles } from "./list-test-files.js";
+import { runPercyScan } from "./run-percy-scan.js";
+import { SetUpPercyParamsShape } from "./sdk-utils/common/schema.js";
+import { updateTestsWithPercyCommands } from "./add-percy-snapshots.js";
+import { approveOrDeclinePercyBuild } from "./review-agent-utils/percy-approve-reject.js";
+import { setUpPercyHandler } from "./sdk-utils/handler.js";
+import { SETUP_PERCY_DESCRIPTION, LIST_TEST_FILES_DESCRIPTION, PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, } from "./sdk-utils/common/constants.js";
+import { ListTestFilesParamsShape, UpdateTestFileWithInstructionsParams, } from "./percy-snapshot-utils/constants.js";
+import { RunPercyScanParamsShape, FetchPercyChangesParamsShape, ManagePercyBuildApprovalParamsShape, } from "./sdk-utils/common/schema.js";
+import { handleMCPError } from "../lib/utils.js";
+export function registerPercyTools(server, config) {
+    const tools = {};
+    tools.setupPercyVisualTesting = server.tool("setupPercyVisualTesting", SETUP_PERCY_DESCRIPTION, SetUpPercyParamsShape, async (args) => {
+        try {
+            trackMCP("setupPercyVisualTesting", server.server.getClientVersion(), config);
+            return setUpPercyHandler(args, config);
+        }
+        catch (error) {
+            return handleMCPError("setupPercyVisualTesting", server, config, error);
+        }
+    });
+    tools.addPercySnapshotCommands = server.tool("addPercySnapshotCommands", PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, UpdateTestFileWithInstructionsParams, async (args) => {
+        try {
+            trackMCP("addPercySnapshotCommands", server.server.getClientVersion(), config);
+            return await updateTestsWithPercyCommands(args);
+        }
+        catch (error) {
+            return handleMCPError("addPercySnapshotCommands", server, config, error);
+        }
+    });
+    tools.listTestFiles = server.tool("listTestFiles", LIST_TEST_FILES_DESCRIPTION, ListTestFilesParamsShape, async (args) => {
+        try {
+            trackMCP("listTestFiles", server.server.getClientVersion(), config);
+            return addListTestFiles(args);
+        }
+        catch (error) {
+            return handleMCPError("listTestFiles", server, config, error);
+        }
+    });
+    tools.runPercyScan = server.tool("runPercyScan", "Run a Percy visual test scan. Example prompts : Run this Percy build/scan. Never run percy scan/build without this tool", RunPercyScanParamsShape, async (args) => {
+        try {
+            trackMCP("runPercyScan", server.server.getClientVersion(), config);
+            return runPercyScan(args, config);
+        }
+        catch (error) {
+            return handleMCPError("runPercyScan", server, config, error);
+        }
+    });
+    tools.fetchPercyChanges = server.tool("fetchPercyChanges", "Retrieves and summarizes all visual changes detected by Percy AI between the latest and previous builds, helping quickly review what has changed in your project.", FetchPercyChangesParamsShape, async (args) => {
+        try {
+            trackMCP("fetchPercyChanges", server.server.getClientVersion(), config);
+            return await fetchPercyChanges(args, config);
+        }
+        catch (error) {
+            return handleMCPError("fetchPercyChanges", server, config, error);
+        }
+    });
+    tools.managePercyBuildApproval = server.tool("managePercyBuildApproval", "Approve or reject a Percy build", ManagePercyBuildApprovalParamsShape, async (args) => {
+        try {
+            trackMCP("managePercyBuildApproval", server.server.getClientVersion(), config);
+            return await approveOrDeclinePercyBuild(args, config);
+        }
+        catch (error) {
+            return handleMCPError("managePercyBuildApproval", server, config, error);
+        }
+    });
+    return tools;
+}
+export default registerPercyTools;

package/dist/tools/percy-snapshot-utils/constants.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { SDKSupportedLanguage } from "../sdk-utils/common/types.js";
+import { DetectionConfig } from "./types.js";
+export declare const UpdateTestFileWithInstructionsParams: {
+    uuid: z.ZodString;
+    index: z.ZodNumber;
+};
+export declare const ListTestFilesParamsShape: {
+    dirs: z.ZodArray<z.ZodString, "many">;
+    language: z.ZodEnum<[string, ...string[]]>;
+    framework: z.ZodEnum<[string, ...string[]]>;
+};
+export declare const TEST_FILE_DETECTION: Record<SDKSupportedLanguage, DetectionConfig>;
+export declare const EXCLUDED_DIRS: Set<string>;
+export declare const backendIndicators: RegExp[];
+export declare const strongUIIndicators: RegExp[];