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

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("Run App Accessibility (WCAG) checks on the screens the tests touch; Android 11+ or iOS 14+."),
 };

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/failurelogs-utils/app-automate.js

@@ -4,7 +4,7 @@ import { apiClient } from "../../lib/apiClient.js";
 import { wrapUntrusted } from "../../lib/untrusted-content.js";
 // DEVICE LOGS
 export async function retrieveDeviceLogs(sessionId, buildId, config) {
-    const url = `https://api.browserstack.com/app-automate/builds/${buildId}/sessions/${sessionId}/deviceLogs`;
+    const url = `https://api.browserstack.com/app-automate/builds/${buildId}/sessions/${sessionId}/devicelogs`;
     const authString = getBrowserStackAuth(config);
     const auth = Buffer.from(authString).toString("base64");
     const response = await apiClient.get({

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,11 +62,12 @@ 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: string;
+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. */
-export declare const NEEDS_A11Y_CONFIG_ID: string;
+export declare const NEEDS_A11Y_CONFIG_ID = " Requires the id returned by createAccessibilityAuthConfig; nothing here lists configs.";
 /** Test ids come from listTestIds, which itself needs a build id. */
 export declare const NEEDS_TEST_IDS: string;

package/dist/tools/tool-handoff.js

@@ -71,17 +71,12 @@ 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 = " Requires a completed source: a Website Scanner run's ids, returned by " +
-    "startAccessibilityScan; an Automated Tests build's id, the thBuildId in its accessibility " +
-    "report link; a Workflow Analyzer report's numeric id; or a Website Scanner or Automated " +
-    "Tests report's dashboard link, passed as reportUrl. No tool here lists past scans, builds " +
-    "or reports, so if you have none of these, ask the user for the report link, or start a " +
-    "new scan, rather than guessing.";
+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. */
-export const NEEDS_A11Y_CONFIG_ID = " Requires the numeric id returned by createAccessibilityAuthConfig. No tool here lists " +
-    "existing configurations, so if you do not have the id, create one rather than guessing.";
+export const NEEDS_A11Y_CONFIG_ID = " Requires the id returned by createAccessibilityAuthConfig; nothing here lists configs.";
 /** Test ids come from listTestIds, which itself needs a build id. */
 export const NEEDS_TEST_IDS = needsIdFrom("test ids", "listTestIds");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "2.2.5-beta.2",
+  "version": "2.2.5-beta.3",
   "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,
-            },
-        ],
-    };
-}