@browserstack/mcp-server 2.2.5 → 2.2.6-beta.2

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

@@ -38,6 +38,11 @@ export declare function uploadEspressoApp(appPath: string, config: BrowserStackC
 export declare function uploadEspressoTestSuite(testSuitePath: string, config: BrowserStackConfig): Promise<string>;
 export declare function uploadXcuiApp(appPath: string, config: BrowserStackConfig): Promise<string>;
 export declare function uploadXcuiTestSuite(testSuitePath: string, config: BrowserStackConfig): Promise<string>;
-export declare function triggerEspressoBuild(app_url: string, test_suite_url: string, devices: string[], project: string, config: BrowserStackConfig): Promise<string>;
-export declare function triggerXcuiBuild(app_url: string, test_suite_url: string, devices: string[], project: string, config: BrowserStackConfig): Promise<string>;
+/** What a native build run can be asked for beyond app, suite, devices and project. */
+export interface NativeBuildOptions {
+    /** Run App Accessibility checks during the tests (the build API's `accessibility` flag). */
+    accessibility?: boolean;
+}
+export declare function triggerEspressoBuild(app_url: string, test_suite_url: string, devices: string[], project: string, config: BrowserStackConfig, options?: NativeBuildOptions): Promise<string>;
+export declare function triggerXcuiBuild(app_url: string, test_suite_url: string, devices: string[], project: string, config: BrowserStackConfig, options?: NativeBuildOptions): Promise<string>;
 export {};

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

@@ -138,8 +138,17 @@ export async function uploadXcuiApp(appPath, config) {
 export async function uploadXcuiTestSuite(testSuitePath, config) {
     return uploadFileToBrowserStack(testSuitePath, "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/test-suite", "test_suite_url", config, { allowedExtensions: [".zip"] });
 }
+function buildRequestBody(app_url, test_suite_url, devices, project, options) {
+    return {
+        app: app_url,
+        testSuite: test_suite_url,
+        devices,
+        project,
+        ...(options.accessibility ? { accessibility: true } : {}),
+    };
+}
 // Triggers an Espresso test run on BrowserStack and returns the build_id
-export async function triggerEspressoBuild(app_url, test_suite_url, devices, project, config) {
+export async function triggerEspressoBuild(app_url, test_suite_url, devices, project, config, options = {}) {
     const authHeader = "Basic " + Buffer.from(getBrowserStackAuth(config)).toString("base64");
     const response = await apiClient.post({
         url: "https://api-cloud.browserstack.com/app-automate/espresso/v2/build",
@@ -148,10 +157,9 @@ export async function triggerEspressoBuild(app_url, test_suite_url, devices, pro
             "Content-Type": "application/json",
         },
         body: {
-            app: app_url,
-            testSuite: test_suite_url,
-            devices,
-            project,
+            ...buildRequestBody(app_url, test_suite_url, devices, project, options),
+            // An Espresso build's App Accessibility report is generated through Test Observability.
+            ...(options.accessibility ? { testObservability: true } : {}),
         },
     });
     if (response.data.build_id) {
@@ -160,7 +168,7 @@ export async function triggerEspressoBuild(app_url, test_suite_url, devices, pro
     throw new Error(`Failed to trigger Espresso build: ${JSON.stringify(response.data)}`);
 }
 // Triggers an XCUITest run on BrowserStack and returns the build_id
-export async function triggerXcuiBuild(app_url, test_suite_url, devices, project, config) {
+export async function triggerXcuiBuild(app_url, test_suite_url, devices, project, config, options = {}) {
     const auth = {
         username: config["browserstack-username"],
         password: config["browserstack-access-key"],
@@ -172,12 +180,7 @@ export async function triggerXcuiBuild(app_url, test_suite_url, devices, project
                 Buffer.from(`${auth.username}:${auth.password}`).toString("base64"),
             "Content-Type": "application/json",
         },
-        body: {
-            app: app_url,
-            testSuite: test_suite_url,
-            devices,
-            project,
-        },
+        body: buildRequestBody(app_url, test_suite_url, devices, project, options),
     });
     if (response.data.build_id) {
         return response.data.build_id;

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

@@ -1,6 +1,6 @@
 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_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. Set accessibility: true to also run App Accessibility (WCAG) checks during the tests; the issues are then read with fetchAccessibilityIssues.";
 export declare const MobileDeviceSchema: z.ZodObject<{
     platform: z.ZodEnum<{
         android: "android";
@@ -22,4 +22,5 @@ export declare const RUN_APP_AUTOMATE_SCHEMA: {
     }, z.core.$strip>>>;
     project: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     detectedAutomationFramework: z.ZodEnum<typeof AppTestPlatform>;
+    accessibility: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 };

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

@@ -1,6 +1,6 @@
 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_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. Set accessibility: true to also run App Accessibility (WCAG) checks during the tests; the issues are then read with fetchAccessibilityIssues.`;
 export const MobileDeviceSchema = z.object({
     platform: z
         .enum(["android", "ios"])
@@ -46,4 +46,9 @@ export const RUN_APP_AUTOMATE_SCHEMA = {
     detectedAutomationFramework: z
         .nativeEnum(AppTestPlatform)
         .describe("The automation framework used in the project, such as 'espresso' (Android) or 'xcuitest' (iOS)."),
+    accessibility: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("App Accessibility checks on screens the tests touch (Android 11+, iOS 14+); suite must be built with BrowserStack's SDK."),
 };

package/dist/tools/appautomate.js

@@ -96,8 +96,26 @@ async function takeAppScreenshot(args) {
         }
     }
 }
+/**
+ * What a native suite needs for App Accessibility to scan it. The build request's flag
+ * turns the checks on, but only a suite built with BrowserStack's instrumentation records
+ * scans; without it the run finishes with none, and nothing says why.
+ */
+const NATIVE_ACCESSIBILITY_SETUP = {
+    Espresso: "The test suite must be built with BrowserStack's Gradle plugin and SDK, or the run records no scans: classpath 'com.browserstack:gradle-tool:latest.release' in the root build.gradle, id 'com.browserstack.gradle-tool' in the app's plugins, and androidTestImplementation 'com.browserstack:browserstack-java-sdk:latest.release' (1.31.0 or newer). The app also needs internet permission.",
+    XCUITest: "The UI test target must embed and initialize the BrowserStack Swift SDK (BrowserstackSwiftSDK.xcframework, or the Swift package), or the run records no scans: set NSPrincipalClass to BrowserstackSwiftSDK.BrowserstackSwiftSDK in the test target's Info.plist, or call BrowserstackSwiftSDK.init() in the test class's init(). Swift 5.4+ and iOS 14+.",
+};
+/** The run's build and, with accessibility on, where its issues are read once it finishes. */
+function runStartedMessage(framework, buildId, accessibility) {
+    const link = `https://app-automate.browserstack.com/builds/${buildId}`;
+    const a11y = accessibility
+        ? `\n\n♿ App Accessibility checks are on. ${NATIVE_ACCESSIBILITY_SETUP[framework] ?? ""}\nWhen the build finishes (typically 10–20 minutes), read the issues with fetchAccessibilityIssues, reportUrl: ${link} — it maps the build to its accessibility report and waits while the report is still processing.`
+        : "";
+    return `✅ ${framework} run started successfully!\n\n🔧 Build ID: ${buildId}\n🔗 View your build: ${link}${a11y}`;
+}
 //Runs AppAutomate tests on BrowserStack by uploading app and test suite, then triggering a test run.
 async function runAppTestsOnBrowserStack(args, config) {
+    const accessibility = args.accessibility === true;
     // Validate that either paths or URLs are provided for both app and test suite
     if (!args.browserstackAppUrl && !args.appPath) {
         throw new Error("appPath is required when browserstackAppUrl is not provided");
@@ -105,8 +123,13 @@ async function runAppTestsOnBrowserStack(args, config) {
     if (!args.browserstackTestSuiteUrl && !args.testSuitePath) {
         throw new Error("testSuitePath is required when browserstackTestSuiteUrl is not provided");
     }
-    // Validate devices against real BrowserStack device data
-    await validateAppAutomateDevices(args.devices);
+    // Validate devices against real BrowserStack device data, and ask for them as App Automate
+    // lists them: a version given as "14" is "14.0" there, and a run asking for "-14" waits for
+    // a device that never matches.
+    const validated = await validateAppAutomateDevices(args.devices);
+    const deviceStrings = args.devices.length > 0
+        ? validated.map((device) => `${device.deviceName}-${device.osVersion}`)
+        : [];
     switch (args.detectedAutomationFramework) {
         case AppTestPlatform.ESPRESSO: {
             try {
@@ -128,17 +151,12 @@ async function runAppTestsOnBrowserStack(args, config) {
                     test_suite_url = await uploadEspressoTestSuite(args.testSuitePath, config);
                     logger.info(`Test suite uploaded. URL: ${test_suite_url}`);
                 }
-                // Convert array format to string format for Espresso
-                const deviceStrings = args.devices.map((device) => {
-                    const [, deviceName, osVersion] = device;
-                    return `${deviceName}-${osVersion}`;
-                });
-                const build_id = await triggerEspressoBuild(app_url, test_suite_url, deviceStrings, args.project, config);
+                const build_id = await triggerEspressoBuild(app_url, test_suite_url, deviceStrings, args.project, config, { accessibility });
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `✅ Espresso run started successfully!\n\n🔧 Build ID: ${build_id}\n🔗 View your build: https://app-automate.browserstack.com/builds/${build_id}`,
+                            text: runStartedMessage("Espresso", build_id, accessibility),
                         },
                     ],
                 };
@@ -168,17 +186,12 @@ async function runAppTestsOnBrowserStack(args, config) {
                     test_suite_url = await uploadXcuiTestSuite(args.testSuitePath, config);
                     logger.info(`Test suite uploaded. URL: ${test_suite_url}`);
                 }
-                // Convert array format to string format for XCUITest
-                const deviceStrings = args.devices.map((device) => {
-                    const [, deviceName, osVersion] = device;
-                    return `${deviceName}-${osVersion}`;
-                });
-                const build_id = await triggerXcuiBuild(app_url, test_suite_url, deviceStrings, args.project, config);
+                const build_id = await triggerXcuiBuild(app_url, test_suite_url, deviceStrings, args.project, config, { accessibility });
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `✅ XCUITest run started successfully!\n\n🔧 Build ID: ${build_id}\n🔗 View your build: https://app-automate.browserstack.com/builds/${build_id}`,
+                            text: runStartedMessage("XCUITest", build_id, accessibility),
                         },
                     ],
                 };

package/dist/tools/testmanagement-utils/create-testrun.d.ts

@@ -11,8 +11,8 @@ export declare const CreateTestRunSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         run_state: z.ZodOptional<z.ZodEnum<{
             done: "done";
-            new_run: "new_run";
             in_progress: "in_progress";
+            new_run: "new_run";
             under_review: "under_review";
             rejected: "rejected";
             closed: "closed";

package/dist/tools/testmanagement-utils/update-testrun.d.ts

@@ -11,8 +11,8 @@ export declare const UpdateTestRunSchema: z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
         run_state: z.ZodOptional<z.ZodEnum<{
             done: "done";
-            new_run: "new_run";
             in_progress: "in_progress";
+            new_run: "new_run";
             under_review: "under_review";
             rejected: "rejected";
             closed: "closed";

package/dist/tools/tool-handoff.d.ts

@@ -62,8 +62,9 @@ export declare const NEEDS_BUILD_ID: string;
  */
 export declare const NEEDS_SESSION_ID: string;
 /**
- * A scan run's ids come from startAccessibilityScan. Nothing here lists builds or reports,
- * but the tool takes a report's dashboard link and looks the ids up itself.
+ * A scan run's ids come from startAccessibilityScan; a build's id is printed by the SDK at
+ * the end of its run. Nothing here lists builds or reports, but the tool takes a report's
+ * dashboard link, or an Automate link, and looks the ids up itself.
  */
 export declare const NEEDS_A11Y_SCAN_ID = " Ids: startAccessibilityScan or a dashboard link; nothing here lists reports.";
 /** Auth-config ids are not listable by any tool here. */

package/dist/tools/tool-handoff.js

@@ -71,8 +71,9 @@ export const NEEDS_BUILD_ID = needsIdFrom("a BrowserStack build id", "getBuildId
 export const NEEDS_SESSION_ID = " Requires a session id. listSessions lists them for a build; if you do not have the " +
     "build either, getBuildId or listBuildId resolves one from a project and build name.";
 /**
- * A scan run's ids come from startAccessibilityScan. Nothing here lists builds or reports,
- * but the tool takes a report's dashboard link and looks the ids up itself.
+ * A scan run's ids come from startAccessibilityScan; a build's id is printed by the SDK at
+ * the end of its run. Nothing here lists builds or reports, but the tool takes a report's
+ * dashboard link, or an Automate link, and looks the ids up itself.
  */
 export const NEEDS_A11Y_SCAN_ID = " Ids: startAccessibilityScan or a dashboard link; nothing here lists reports.";
 /** Auth-config ids are not listable by any tool here. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "2.2.5",
+  "version": "2.2.6-beta.2",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",

package/dist/tools/accessiblity-utils/accessibility-rag.d.ts

@@ -1,12 +0,0 @@
-export interface RAGChunk {
-    url: string;
-    content: string;
-}
-import { BrowserStackConfig } from "../../lib/types.js";
-export interface AccessibilityRAGResponse {
-    content: Array<{
-        type: "text";
-        text: string;
-    }>;
-}
-export declare function queryAccessibilityRAG(userQuery: string, config: BrowserStackConfig): Promise<any>;

package/dist/tools/accessiblity-utils/accessibility-rag.js

@@ -1,59 +0,0 @@
-import { apiClient } from "../../lib/apiClient.js";
-import { wrapUntrusted } from "../../lib/untrusted-content.js";
-import { getBrowserStackAuth } from "../../lib/get-auth.js";
-export async function queryAccessibilityRAG(userQuery, config) {
-    const url = "https://accessibility.browserstack.com/api/tcg-proxy/search";
-    const authString = getBrowserStackAuth(config);
-    const auth = Buffer.from(authString).toString("base64");
-    const response = await apiClient.post({
-        url,
-        headers: {
-            "Content-Type": "application/json",
-            Authorization: `Basic ${auth}`,
-        },
-        body: {
-            query: userQuery,
-        },
-        raise_error: false,
-    });
-    if (!response.ok) {
-        const errorText = typeof response.data === "string"
-            ? response.data
-            : JSON.stringify(response.data);
-        throw new Error(`RAG endpoint error: ${response.status} ${errorText}`);
-    }
-    const responseData = response.data;
-    if (!responseData.success) {
-        throw new Error("Something went wrong: " + responseData.message);
-    }
-    // Parse the stringified JSON data
-    let parsedData;
-    try {
-        parsedData = JSON.parse(responseData.data);
-    }
-    catch (err) {
-        throw new Error("Failed to parse RAG response data as JSON: " +
-            (err instanceof Error ? err.message : String(err)));
-    }
-    if (!parsedData ||
-        !parsedData.data ||
-        !Array.isArray(parsedData.data.chunks)) {
-        throw new Error("RAG response data is missing expected 'data.chunks' array");
-    }
-    const chunks = parsedData.data.chunks;
-    // Format the response properly
-    const instruction = "IMPORTANT: Use ONLY the data provided below to answer the user's accessibility question. Do not use any external knowledge. When answering, you MUST include the relevant BrowserStack documentation links provided in the sources for personalization and further reference.\n\n";
-    const formattedChunks = chunks
-        .map((chunk, index) => `${index + 1}: Source: ${chunk.url}\n\n${chunk.content}`)
-        .join("\n\n---\n\n");
-    const formattedResponse = instruction +
-        wrapUntrusted("BrowserStack accessibility documentation", formattedChunks);
-    return {
-        content: [
-            {
-                type: "text",
-                text: formattedResponse,
-            },
-        ],
-    };
-}