@browserstack/mcp-server 2.2.5-beta.3 → 2.2.6-beta.1

package/dist/tools/appautomate.js

@@ -96,26 +96,8 @@ 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");
@@ -123,13 +105,8 @@ 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, 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}`)
-        : [];
+    // Validate devices against real BrowserStack device data
+    await validateAppAutomateDevices(args.devices);
     switch (args.detectedAutomationFramework) {
         case AppTestPlatform.ESPRESSO: {
             try {
@@ -151,12 +128,17 @@ async function runAppTestsOnBrowserStack(args, config) {
                     test_suite_url = await uploadEspressoTestSuite(args.testSuitePath, config);
                     logger.info(`Test suite uploaded. URL: ${test_suite_url}`);
                 }
-                const build_id = await triggerEspressoBuild(app_url, test_suite_url, deviceStrings, args.project, config, { accessibility });
+                // 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);
                 return {
                     content: [
                         {
                             type: "text",
-                            text: runStartedMessage("Espresso", build_id, accessibility),
+                            text: `✅ Espresso run started successfully!\n\n🔧 Build ID: ${build_id}\n🔗 View your build: https://app-automate.browserstack.com/builds/${build_id}`,
                         },
                     ],
                 };
@@ -186,12 +168,17 @@ async function runAppTestsOnBrowserStack(args, config) {
                     test_suite_url = await uploadXcuiTestSuite(args.testSuitePath, config);
                     logger.info(`Test suite uploaded. URL: ${test_suite_url}`);
                 }
-                const build_id = await triggerXcuiBuild(app_url, test_suite_url, deviceStrings, args.project, config, { accessibility });
+                // 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);
                 return {
                     content: [
                         {
                             type: "text",
-                            text: runStartedMessage("XCUITest", build_id, accessibility),
+                            text: `✅ XCUITest run started successfully!\n\n🔧 Build ID: ${build_id}\n🔗 View your build: https://app-automate.browserstack.com/builds/${build_id}`,
                         },
                     ],
                 };

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";
-            in_progress: "in_progress";
             new_run: "new_run";
+            in_progress: "in_progress";
             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";
-            in_progress: "in_progress";
             new_run: "new_run";
+            in_progress: "in_progress";
             under_review: "under_review";
             rejected: "rejected";
             closed: "closed";

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

@@ -62,9 +62,8 @@ export declare const NEEDS_BUILD_ID: string;
  */
 export declare const NEEDS_SESSION_ID: string;
 /**
- * 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.
+ * 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.
  */
 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,9 +71,8 @@ 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; 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.
+ * 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.
  */
 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-beta.3",
+  "version": "2.2.6-beta.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",

package/dist/lib/accessibility-routing.d.ts

@@ -1,5 +0,0 @@
-/**
- * Which product checks what for accessibility, said once to every client, since the tools
- * alone do not tell an agent that a web page and a mobile app are scanned differently.
- */
-export declare const ACCESSIBILITY_ROUTING_INSTRUCTION = "Accessibility checks: a web page or site \u2192 startAccessibilityScan (Website Scanner); a multi-step web flow \u2192 Automate tests with `accessibility: true` in browserstack.yml (setupBrowserStackAutomateTests); a mobile app \u2192 its tests on App Automate with accessibility on (setupBrowserStackAppAutomateTests, or runAppTestsOnBrowserStack for Espresso/XCUITest). Then read the issues with fetchAccessibilityIssues.";

package/dist/lib/accessibility-routing.js

@@ -1,5 +0,0 @@
-/**
- * Which product checks what for accessibility, said once to every client, since the tools
- * alone do not tell an agent that a web page and a mobile app are scanned differently.
- */
-export const ACCESSIBILITY_ROUTING_INSTRUCTION = "Accessibility checks: a web page or site → startAccessibilityScan (Website Scanner); a multi-step web flow → Automate tests with `accessibility: true` in browserstack.yml (setupBrowserStackAutomateTests); a mobile app → its tests on App Automate with accessibility on (setupBrowserStackAppAutomateTests, or runAppTestsOnBrowserStack for Espresso/XCUITest). Then read the issues with fetchAccessibilityIssues.";

package/dist/tools/accessiblity-utils/app-report-fetcher.d.ts

@@ -1,341 +0,0 @@
-/**
- * App Accessibility: the issues of a mobile app build run through App Automate with
- * accessibility on. Unlike the web products there is no CSV export behind an access key,
- * so the issues come inline, one API page per batch of scanned screens.
- */
-export declare const APP_API_BASE = "https://api-app-accessibility.browserstack.com/automate/api/v1";
-export declare const APP_DASHBOARD = "https://app-accessibility.browserstack.com";
-/** Manual (Workflow Analyzer) reports recorded on the dashboard: a separate, older route. */
-export declare const MANUAL_API_BASE = "https://api-app-accessibility.browserstack.com/api/v1";
-export declare const MAX_SNAPSHOT_PAGES = 20;
-/** A dashboard link names a build by number; a build someone just opened is among the newest. */
-export declare const MAX_APP_BUILD_LIST_PAGES = 3;
-export declare const MAX_APP_AUTOMATE_BUILD_PAGES = 3;
-export interface AppBuildMeta {
-    /** The build's number within its project, which the dashboard link uses. */
-    build_id: number;
-    created_at?: string;
-    th_build_id: string;
-    name: string;
-    normalised_name: string;
-    project_name: string;
-    /** running | rule_processing | passed | failed | timeout | update_os_version */
-    status: string;
-    issue_summary?: {
-        total?: number;
-        scan_count?: number;
-    };
-    fup?: {
-        capped?: boolean;
-        tests_partial?: boolean;
-        tests_dropped?: boolean;
-    };
-    /** What ran the tests: an SDK framework (pytest, …) or a native one (Espresso-Junit4, …). */
-    session_data?: {
-        framework?: {
-            name?: string;
-        };
-    };
-}
-interface AppRuleIssue {
-    uid: string;
-    status?: string;
-    duplication_count?: number;
-    issue_class_android?: string;
-    issue_class_ios?: string;
-    issue_id_android?: string;
-    issue_id_ios?: string;
-    how_to_fix_desc?: string;
-    issue_details?: {
-        label?: string;
-        value?: unknown;
-    }[];
-}
-interface AppRule {
-    rule_id: string;
-    label: string;
-    description?: string;
-    severity?: string;
-    guidelines?: {
-        message?: string;
-    }[];
-    rule_issues?: AppRuleIssue[];
-}
-export interface AppSnapshot {
-    meta?: {
-        screenshot_url?: string;
-        testcase_name?: string;
-        /** A manual report's snapshot keeps its rules here. */
-        aggregated_results?: AppRule[];
-    };
-    aggregated_results?: AppRule[];
-}
-export type AppAccessibilityIssue = {
-    issue_type: string;
-    rule_id: string;
-    severity: string;
-    /** Which scanned screen of which test the element was on. */
-    screen: string;
-    /** The element's id when it has one, else its class. */
-    component: string;
-    /** The element's identifying details, as captured on the device. */
-    element: Record<string, unknown>;
-    issue_description: string;
-    how_to_fix: string;
-    /** The WCAG success criteria the rule maps to. */
-    wcag: string;
-    screenshot?: string;
-    /** How many more occurrences of this issue the report folded into it. */
-    duplicate_count?: number;
-};
-/** A report's issues counted by severity, by rule and by screen, largest first. */
-export interface AppIssueSummary {
-    by_severity: Record<string, number>;
-    by_rule: {
-        rule_id: string;
-        issue_type: string;
-        count: number;
-    }[];
-    by_screen: {
-        screen: string;
-        count: number;
-    }[];
-}
-export interface AppBuildReport {
-    records: AppAccessibilityIssue[];
-    page_length: number;
-    total_issues: number;
-    next_page: number | null;
-    /** How many issues the pages after this one hold. */
-    remaining: number;
-    summary: AppIssueSummary;
-    /** Issues hidden in the dashboard, which the API leaves out of the screens. */
-    hidden_issues: number;
-    scan_count: number;
-    status: string;
-    build_name: string;
-    dashboard_link?: string;
-    /** Whether the fair-usage cap dropped tests or scans from this build. */
-    fup_capped: boolean;
-    /** The test framework the build ran under, when the build's details name it. */
-    framework?: string;
-}
-/** A manual (Workflow Analyzer) report's issues, read inline from its scanned screens. */
-export interface AppManualReport {
-    records: AppAccessibilityIssue[];
-    page_length: number;
-    /** Every occurrence the API lists; the dashboard folds duplicates it does not mark. */
-    total_issues: number;
-    next_page: number | null;
-    /** How many issues the pages after this one hold. */
-    remaining: number;
-    summary: AppIssueSummary;
-    dashboard_count: number;
-    duplicate_occurrences: number;
-    hidden_issues: number;
-    scan_count: number;
-    /** complete | in_progress */
-    status: string;
-    report_name: string;
-    device?: string;
-    dashboard_link: string;
-}
-/** Every issue of one app build, with what a comparison needs to know of the build. */
-export interface AppBuildIssues {
-    buildId: string;
-    build_name: string;
-    build_number: number;
-    created_at?: string;
-    status: string;
-    scan_count: number;
-    /** The tests whose screens were scanned, in the order first seen. */
-    tests: string[];
-    issues: AppAccessibilityIssue[];
-}
-/** An earlier build of a project, as the build list names it. */
-export interface AppBuildRef {
-    buildId: string;
-    name?: string;
-    build_number?: number;
-    created_at?: string;
-    /** Whether it has the later build's name; a native run's builds are each named apart. */
-    same_name: boolean;
-    /**
-     * Whether the project's whole build list was read. When it was not, a build of the same
-     * name may still be further back than the newest builds read.
-     */
-    searched_all: boolean;
-}
-export interface AppProjectRow {
-    id: number;
-    name: string;
-    created_at?: string;
-}
-/** A build as the listing tool shows it: what it is, how it went, and how to read it. */
-export interface AppBuildRow {
-    buildId: string;
-    build_number?: number;
-    name: string;
-    status?: string;
-    report_status?: string;
-    created_at?: string;
-    scan_count: number;
-    issues: {
-        total: number;
-        critical: number;
-        serious: number;
-        moderate: number;
-        minor: number;
-    };
-    app?: string;
-    framework?: string;
-    dashboard_link: string;
-}
-export interface AppManualReportRow {
-    reportId: string;
-    name: string;
-    status?: string;
-    created_at?: string;
-    app?: string;
-    scan_count: number;
-    issues: {
-        total: number;
-        critical: number;
-        serious: number;
-        moderate: number;
-        minor: number;
-        duplicates: number;
-        hidden: number;
-    };
-    dashboard_link: string;
-}
-/** One row per element with an issue, most severe first. Screens are numbered in order. */
-export declare function flattenAppSnapshots(details: AppSnapshot[]): AppAccessibilityIssue[];
-/** The issues counted by severity, by rule and by screen, largest first. */
-export declare function summarizeAppIssues(rows: AppAccessibilityIssue[]): AppIssueSummary;
-/**
- * Which issues of two builds are the same issue. Issues that look alike (one rule on
- * elements known by neither id nor label) are paired one for one, those on the same screen
- * and spot first, then on the same screen, then any; what is left over in either build is
- * new or resolved. So new and still open add up to the later build's issues, and resolved
- * and still open to the earlier one's.
- */
-export declare function compareAppIssues(before: AppAccessibilityIssue[], after: AppAccessibilityIssue[]): {
-    added: AppAccessibilityIssue[];
-    resolved: AppAccessibilityIssue[];
-    retained: number;
-};
-/** The id a manual report's dashboard link names (`/report/{uuid}`), if it is one. */
-export declare function manualReportIdFromDashboardLink(url: URL): string | undefined;
-/** A manual report has no status of its own; it is complete once it has ended. */
-export declare function manualReportStatus(detail: {
-    meta_data?: {
-        ended_at?: string | null;
-    };
-}): string;
-export declare class AppAccessibilityApi {
-    private readonly headers;
-    constructor(headers: () => Record<string, string> | undefined);
-    /** The build's details, or undefined when the API does not know the id. */
-    buildMeta(buildId: string): Promise<AppBuildMeta | undefined>;
-    /**
-     * The id of the build an App Accessibility dashboard link points at, if it is one: the
-     * project's newest builds, by number. (The list's name filter would not do: the link
-     * carries TestHub's name for the build, which the filter does not match.)
-     */
-    buildIdFromDashboardLink(url: URL): Promise<string | undefined>;
-    /**
-     * The accessibility build of an App Automate build or session link. An SDK (Appium)
-     * session's test code carries the TestHub build id its results went to, which is the
-     * App Accessibility build when accessibility was on; a build link goes through any one
-     * of its sessions. A native (Espresso, XCUITest) build has no SDK session, and is found
-     * by name instead.
-     */
-    buildIdFromAppAutomateLink(url: URL): Promise<string | undefined>;
-    private buildOfSdkSession;
-    /** The first SDK session of an App Automate build; a native build lists none. */
-    private anySdkSession;
-    /**
-     * A native build's details name its project and when it started; App Accessibility lists
-     * the run under the same project, created as it started, and named as the App Automate
-     * build list names it ("Build #N: app vX"). The start finds it among the project's newest
-     * builds; the name, read from the account's build list, tells runs that started together
-     * apart, and finds a run older than those.
-     */
-    private buildOfNativeBuild;
-    /** A native build's project and start, from whichever framework API knows the build. */
-    private nativeBuild;
-    /** The project's builds created within moments of a run's start, newest first. */
-    private buildsStartedNear;
-    /** The build's name in the account's App Automate build list, walked newest first. */
-    private appAutomateBuildName;
-    /** The App Accessibility project of that exact name, if any. */
-    private projectId;
-    /** The projects whose name contains `name`, as the API searches it. */
-    private projectsNamed;
-    /**
-     * A listing's page. The API answers an empty list with 404 ("No builds found") for
-     * access-key callers, which is not an error here; any other failure is, a 404 from a
-     * wrong route or a missing permission included.
-     */
-    private listing;
-    /** The newest projects, as many as asked for. */
-    listAppProjects(limit: number): Promise<{
-        projects: AppProjectRow[];
-        total: number;
-    }>;
-    /**
-     * A project's newest builds, by exact project name, optionally filtered by build name.
-     * A project name that matches none exactly names the near matches, so the agent can
-     * pick rather than guess.
-     */
-    listAppBuilds(projectName: string, buildName: string | undefined, limit: number): Promise<{
-        project: {
-            id: number;
-            name: string;
-        };
-        total: number;
-        builds: AppBuildRow[];
-    }>;
-    /** The newest manual reports, optionally filtered by name. */
-    listAppManualReports(name: string | undefined, limit: number): Promise<{
-        total: number;
-        reports: AppManualReportRow[];
-    }>;
-    /** A manual report's details, or undefined when the API does not know the id. */
-    manualReport(reportId: string): Promise<any | undefined>;
-    /**
-     * A manual report's issues, every occurrence the API lists, most severe first. The
-     * dashboard's own count comes from the report's summary: it folds duplicates that the
-     * issue rows do not mark, so the two numbers are both given.
-     */
-    appReportIssues(reportId: string, cursor?: number, maxCharacterLength?: number): Promise<AppManualReport>;
-    /**
-     * The id of the project's build that `pick` accepts, newest first, within the first
-     * pages; `buildName` narrows the list to builds named like it, when the name is known
-     * to be the build's own.
-     */
-    private findBuild;
-    /**
-     * The project's builds a page at a time, newest first, within the first pages; `more`
-     * says whether the list goes on past the page.
-     */
-    private projectBuilds;
-    /**
-     * The build before this one in its project: the newest earlier build of the same name,
-     * as an SDK suite keeps its name from run to run, or else the build just before it, as
-     * each native (Espresso, XCUITest) run is named apart. None for a project's first build.
-     */
-    previousBuild(buildId: string): Promise<AppBuildRef | undefined>;
-    /** The build's page on the App Accessibility dashboard, when its project can be found. */
-    private dashboardLink;
-    /** Every scanned screen of the build, and how many issues the dashboard hides. */
-    private snapshots;
-    private requireBuildMeta;
-    /** The build's details and scanned screens; a build with no scans has none to read. */
-    private readBuild;
-    /** Every issue of the build at once, to compare it with another. */
-    buildIssues(buildId: string): Promise<AppBuildIssues>;
-    report(buildId: string, cursor?: number, maxCharacterLength?: number): Promise<AppBuildReport>;
-}
-export {};