BrowserStack MCP server

Instructions

Implementation Reference

• src/tools/bstack-sdk.ts:9-34 (registration)

  Registers the BrowserStack tool 'setupBrowserStackAutomateTests' which internally tracks and calls 'runTestsOnBrowserStackHandler' as the tool logic.

  export function registerRunBrowserStackTestsTool(
    server: McpServer,
    config: BrowserStackConfig,
  ) {
    const tools: Record<string, any> = {};
  
    tools.setupBrowserStackAutomateTests = server.tool(
      "setupBrowserStackAutomateTests",
      RUN_ON_BROWSERSTACK_DESCRIPTION,
      RunTestsOnBrowserStackParamsShape,
      async (args) => {
        try {
          trackMCP(
            "runTestsOnBrowserStack",
            server.server.getClientVersion()!,
            config,
          );
          return await runTestsOnBrowserStackHandler(args, config);
        } catch (error) {
          return handleMCPError("runTestsOnBrowserStack", server, config, error);
        }
      },
    );
  
    return tools;
  }

• src/tools/sdk-utils/handler.ts:31-38 (handler)

  The primary handler function named runTestsOnBrowserStackHandler. It parses the raw input using the schema and delegates to the core BrowserStack SDK implementation.

  export async function runTestsOnBrowserStackHandler(
    rawInput: unknown,
    config: BrowserStackConfig,
  ): Promise<CallToolResult> {
    const input = RunTestsOnBrowserStackSchema.parse(rawInput);
    const result = await runBstackSDKOnly(input, config);
    return await formatToolResult(result);
  }

• src/tools/sdk-utils/bstack/sdkHandler.ts:16-156 (handler)

  Core handler logic (runBstackSDKOnly) that implements the tool by generating step-by-step instructions for BrowserStack SDK setup, device validation, framework-specific configs, and browserstack.yml generation.

  export async function runBstackSDKOnly(
    input: RunTestsOnBrowserStackInput,
    config: BrowserStackConfig,
    isPercyAutomate = false,
  ): Promise<RunTestsInstructionResult> {
    const steps: RunTestsStep[] = [];
    const authString = getBrowserStackAuth(config);
    const [username, accessKey] = authString.split(":");
  
    const tupleTargets: Array<Array<string>> =
      input.devices?.map((device) => {
        const platform = device.platform.toLowerCase();
        if (platform === "windows" || platform === "macos") {
          // Desktop: ["platform", "osVersion", "browser", "browserVersion"]
          return [
            platform,
            device.osVersion || "latest",
            device.browser || "",
            device.browserVersion || "latest",
          ];
        } else {
          // Mobile: ["platform", "deviceName", "osVersion", "browser"]
          return [
            platform,
            device.deviceName || "",
            device.osVersion || "latest",
            device.browser || "",
          ];
        }
      }) || [];
  
    const validatedEnvironments = await validateDevices(
      tupleTargets,
      input.detectedBrowserAutomationFramework,
    );
  
    // Handle frameworks with unique setup instructions that don't use browserstack.yml
    if (
      input.detectedBrowserAutomationFramework === "cypress" ||
      input.detectedTestingFramework === "webdriverio"
    ) {
      const frameworkInstructions = getInstructionsForProjectConfiguration(
        input.detectedBrowserAutomationFramework as SDKSupportedBrowserAutomationFramework,
        input.detectedTestingFramework as SDKSupportedTestingFramework,
        input.detectedLanguage as SDKSupportedLanguage,
        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 as SDKSupportedLanguage,
      input.detectedTestingFramework as SDKSupportedTestingFramework,
      username,
      accessKey,
    );
  
    if (sdkSetupCommand) {
      steps.push({
        type: "instruction",
        title: "Install BrowserStack SDK",
        content: sdkSetupCommand,
      });
    }
  
    const frameworkInstructions = getInstructionsForProjectConfiguration(
      input.detectedBrowserAutomationFramework as SDKSupportedBrowserAutomationFramework,
      input.detectedTestingFramework as SDKSupportedTestingFramework,
      input.detectedLanguage as SDKSupportedLanguage,
      username,
      accessKey,
    );
  
    if (frameworkInstructions) {
      if (frameworkInstructions.setup) {
        steps.push({
          type: "instruction",
          title: "Framework-Specific Setup",
          content: frameworkInstructions.setup,
        });
      }
    }
  
    const ymlInstructions = generateBrowserStackYMLInstructions(
      {
        validatedEnvironments,
        enablePercy: false,
        projectName: input.projectName,
      },
      config,
    );
  
    if (ymlInstructions) {
      steps.push({
        type: "instruction",
        title: "Configure browserstack.yml",
        content: ymlInstructions,
      });
    }
  
    if (frameworkInstructions) {
      if (frameworkInstructions.run && !isPercyAutomate) {
        steps.push({
          type: "instruction",
          title: "Run the tests",
          content: frameworkInstructions.run,
        });
      }
    }
  
    return {
      steps,
      requiresPercy: false,
      missingDependencies: [],
    };
  }

• src/tools/sdk-utils/common/schema.ts:78-105 (schema)

  Zod schema definitions for RunTestsOnBrowserStackParamsShape, RunTestsOnBrowserStackSchema, and related types used for input validation in the tool.

  export const RunTestsOnBrowserStackParamsShape = {
    projectName: z
      .string()
      .describe("A single name for your project to organize all your tests."),
    detectedLanguage: z.nativeEnum(SDKSupportedLanguageEnum),
    detectedBrowserAutomationFramework: z.nativeEnum(
      SDKSupportedBrowserAutomationFrameworkEnum,
    ),
    detectedTestingFramework: z.nativeEnum(SDKSupportedTestingFrameworkEnum),
    devices: z
      .array(DeviceSchema)
      .max(3)
      .default([])
      .describe(
        "Device objects array. Use the object format directly - no transformation needed. Add only when user explicitly requests devices. Examples: [{ platform: 'windows', osVersion: '11', browser: 'chrome', browserVersion: 'latest' }] or [{ platform: 'android', deviceName: 'Samsung Galaxy S24', osVersion: '14', browser: 'chrome' }].",
      ),
  };
  
  export const SetUpPercySchema = z.object(SetUpPercyParamsShape);
  
  export const RunTestsOnBrowserStackSchema = z.object(
    RunTestsOnBrowserStackParamsShape,
  );
  
  export type SetUpPercyInput = z.infer<typeof SetUpPercySchema>;
  export type RunTestsOnBrowserStackInput = z.infer<
    typeof RunTestsOnBrowserStackSchema
  >;