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

package/dist/tools/accessibility.js

@@ -1,11 +1,11 @@
 import { z } from "zod";
-import { AccessibilityScanner } from "./accessiblity-utils/scanner.js";
-import { AccessibilityReportFetcher, } from "./accessiblity-utils/report-fetcher.js";
+import { AccessibilityScanner, } from "./accessiblity-utils/scanner.js";
+import { AccessibilityReportFetcher, EXPORT_WAIT_MS, ExportPendingError, } from "./accessiblity-utils/report-fetcher.js";
+import { compareAppIssues, } from "./accessiblity-utils/app-report-fetcher.js";
 import { AccessibilityAuthConfig, safeAuthConfigData, } from "./accessiblity-utils/auth-config.js";
 import { trackMCP } from "../lib/instrumentation.js";
-import { parseAccessibilityReportFromCSV } from "./accessiblity-utils/report-parser.js";
+import { compareIssues, loadMainIssues, parseAccessibilityReportFromCSV, } from "./accessiblity-utils/report-parser.js";
 import { wrapUntrusted } from "../lib/untrusted-content.js";
-import { queryAccessibilityRAG } from "./accessiblity-utils/accessibility-rag.js";
 import { getBrowserStackAuth } from "../lib/get-auth.js";
 import { elicitCredentialsIfSupported } from "../lib/elicit-credentials.js";
 import logger from "../logger.js";
@@ -66,25 +66,17 @@ async function initializeReportFetcher(config) {
     reportFetcher.setAuth(auth);
     return reportFetcher;
 }
-async function executeAccessibilityRAG(args, server, config) {
-    try {
-        trackMCP("accessibilityExpert", server.server.getClientVersion(), undefined, config);
-        return await queryAccessibilityRAG(args.query, config);
-    }
-    catch (error) {
-        return handleMCPError("accessibilityExpert", server, config, error);
-    }
-}
 /** The one source the arguments name, or why they do not name exactly one. */
 function issueSourceFrom(args) {
     const named = [
         Boolean(args.scanId || args.scanRunId),
         Boolean(args.buildId),
         Boolean(args.workflowReportId),
+        Boolean(args.appReportId),
         Boolean(args.reportUrl),
     ].filter(Boolean).length;
     if (named !== 1) {
-        return "Pass exactly one source: scanId with scanRunId (a Website Scanner run), buildId (an Automated Tests build), workflowReportId (a Workflow Analyzer report) or reportUrl (a report's dashboard link).";
+        return "Pass exactly one source: scanId with scanRunId (a Website Scanner run), buildId (an Automated Tests or App Accessibility build), workflowReportId (a Workflow Analyzer report), appReportId (an App Accessibility manual report) or reportUrl (a report's dashboard link).";
     }
     if (args.reportUrl)
         return { kind: "link", reportUrl: args.reportUrl };
@@ -93,6 +85,9 @@ function issueSourceFrom(args) {
     if (args.workflowReportId) {
         return { kind: "workflow", reportId: args.workflowReportId };
     }
+    if (args.appReportId) {
+        return { kind: "appReport", reportId: args.appReportId };
+    }
     if (!args.scanId || !args.scanRunId) {
         return "A Website Scanner run needs both scanId and scanRunId.";
     }
@@ -104,9 +99,12 @@ function sourceArgs(source) {
         case "scan":
             return `scanId: "${source.scanId}", scanRunId: "${source.scanRunId}"`;
         case "build":
+        case "appBuild":
             return `buildId: "${source.buildId}"`;
         case "workflow":
             return `workflowReportId: "${source.reportId}"`;
+        case "appReport":
+            return `appReportId: "${source.reportId}"`;
     }
 }
 /** What a dashboard link resolved to, in words. */
@@ -118,6 +116,10 @@ function describeSource(source) {
             return `Automated Tests build ${source.buildId}`;
         case "workflow":
             return `Workflow Analyzer report ${source.reportId}`;
+        case "appBuild":
+            return `App Accessibility build ${source.buildId}`;
+        case "appReport":
+            return `App Accessibility manual report ${source.reportId}`;
     }
 }
 async function executeFetchAccessibilityIssues(args, context, server, config) {
@@ -126,7 +128,11 @@ async function executeFetchAccessibilityIssues(args, context, server, config) {
         const source = issueSourceFrom(args);
         if (typeof source === "string")
             return createErrorResponse(source);
-        return await fetchAccessibilityIssues(source, config, args.cursor, context);
+        return await fetchAccessibilityIssues(source, config, args.cursor, context, {
+            compareWith: args.compareWith,
+            pageUrl: args.pageUrl,
+            exportTaskId: args.exportTaskId,
+        });
     }
     catch (error) {
         return handleMCPError("fetchAccessibilityIssues", server, config, error);
@@ -155,19 +161,21 @@ function excludedIssuesNote(duplicates, unlinked, hidden) {
 /** How often, and for how long, a first read waits on a report that is still processing. */
 export const REPORT_STATUS_POLL_MS = 10_000;
 export const REPORT_STATUS_WAIT_MS = 5 * 60 * 1000;
-/** Statuses during which a report's issues are still being added. */
+/** Statuses during which a report's issues are still being added (`rule_processing`: an app build's). */
 const PROCESSING_STATUSES = new Set([
     "queued",
     "running",
     "processing",
     "finalizing",
+    "rule_processing",
+    "in_progress",
 ]);
 /**
- * Of those, the one worth waiting on: the advanced-issue processing after the run, which
- * ends within minutes. A report whose scan or tests are still running is read as it is,
+ * Of those, the ones worth waiting on: the processing after the run (a web scan's advanced
+ * issues, an app build's rules), which ends within minutes. A report whose scan or tests are still running is read as it is,
  * with a note, since that can last as long as the suite does.
  */
-const WAIT_STATUSES = new Set(["finalizing"]);
+const WAIT_STATUSES = new Set(["finalizing", "rule_processing"]);
 /**
  * Where a report is in its processing before its issues are read. Issues keep being added
  * until it completes; an advanced scan adds its advanced-rule issues while "finalizing", for
@@ -215,46 +223,587 @@ function processingNote({ status, firstStatus, waitedMs, }) {
     }
     return [];
 }
-async function fetchAccessibilityIssues(requested, config, cursor = 0, context) {
+/** Progress while a report's CSV export is generated, so clients see the call is alive. */
+function exportProgress(context) {
+    return async (waitedMs) => {
+        if (!context)
+            return;
+        await notifyScanProgress(context, `Generating the report's CSV export (large reports take longer): ${formatDuration(waitedMs)} so far.`, Math.min(99, Math.round((waitedMs / EXPORT_WAIT_MS) * 100)));
+    };
+}
+/** What to say of an export still being generated: how to continue it, not an error. */
+function exportPendingMessages(source, error, extraArgs) {
+    return [
+        `This report's CSV export is still being generated (waited ${formatDuration(error.waitedMs)}; large reports can take a few minutes). No issues have been read yet.`,
+        `Call fetchAccessibilityIssues again with ${sourceArgs(source)}${extraArgs} and exportTaskId: "${error.taskId}" to continue this export instead of starting a new one.`,
+    ];
+}
+/** The last line: how to get the next page, or that there is none. */
+function closingMessage(next_page, remaining, source, stillProcessing, extraArgs = "") {
+    if (next_page !== null) {
+        return `${remaining} more issues available. Use fetchAccessibilityIssues with ${sourceArgs(source)}${extraArgs} and cursor: ${next_page} to get the next batch.`;
+    }
+    if (stillProcessing) {
+        return `All issues found so far retrieved; the report is still processing.`;
+    }
+    return `✅ All issues retrieved.`;
+}
+/**
+ * An app build's name and dashboard link, as data: the name is the user's own (from their
+ * CI or browserstack.yml), so it is quoted in an untrusted block rather than in our prose.
+ */
+function appBuildDetails(report) {
+    return `Build: ${wrapUntrusted("App Accessibility build", JSON.stringify({
+        name: report.build_name,
+        ...(report.dashboard_link
+            ? { dashboard_link: report.dashboard_link }
+            : {}),
+    }, null, 2))}`;
+}
+/**
+ * Why a native (Espresso, XCUITest) build recorded no scans. The build request's flag only
+ * turns the checks on: the suite itself must carry BrowserStack's instrumentation.
+ */
+const NATIVE_NO_SCAN_CAUSES = {
+    espresso: [
+        "The test suite was not built with BrowserStack's Gradle plugin and SDK: add classpath 'com.browserstack:gradle-tool:latest.release' to the root build.gradle, id 'com.browserstack.gradle-tool' to the app's plugins, and androidTestImplementation 'com.browserstack:browserstack-java-sdk:latest.release' (1.31.0 or newer), then rebuild the test APK.",
+        "Test Observability was off for the build: Espresso's App Accessibility report needs `testObservability: true` in the build request alongside `accessibility: true` (runAppTestsOnBrowserStack sends both).",
+        "The app cannot reach BrowserStack from the device: it needs internet permission, and cleartext traffic allowed (usesCleartextTraffic) if the network calls for it.",
+        "No tests ran: check the build's sessions and test results on App Automate.",
+    ],
+    xcuitest: [
+        "The UI test target does not embed and initialize the BrowserStack Swift SDK: add BrowserstackSwiftSDK.xcframework (or the Swift package) to the test target, and set NSPrincipalClass to BrowserstackSwiftSDK.BrowserstackSwiftSDK in its Info.plist or call BrowserstackSwiftSDK.init() in the test class's init().",
+        "The device runs iOS older than 14, or the suite was built with Swift older than 5.4.",
+        "No tests ran: check the build's sessions and test results on App Automate.",
+    ],
+};
+/** Which native framework ran a build, when its details name one. */
+function nativeFramework(framework) {
+    if (!framework)
+        return undefined;
+    if (/espresso/i.test(framework))
+        return "espresso";
+    if (/xcui|xctest/i.test(framework))
+        return "xcuitest";
+    return undefined;
+}
+/**
+ * Why a finished app build has no scans. Each cause here produced a run that finished
+ * green with nothing scanned and no warning; they are listed most likely first, with what
+ * the build's own details say ahead of the rest. A native build gets the native causes.
+ */
+function noScansNote(report) {
+    const native = nativeFramework(report.framework);
+    if (native) {
+        const causes = [
+            ...(report.fup_capped
+                ? [
+                    "This build hit the fair-usage cap (fup in the build details), which drops tests or scans.",
+                ]
+                : []),
+            ...NATIVE_NO_SCAN_CAUSES[native],
+        ];
+        return [
+            `No accessibility scans were recorded for the ${native === "espresso" ? "Espresso" : "XCUITest"} build below (status: ${report.status}), so there are no issues to list.`,
+            appBuildDetails(report),
+            "The usual causes for a native build, most likely first:",
+            ...causes.map((cause, i) => `${i + 1}. ${cause}`),
+        ];
+    }
+    const causes = [
+        ...(report.fup_capped
+            ? [
+                "This build hit the fair-usage cap (fup in the build details), which drops tests or scans.",
+            ]
+            : []),
+        ...(report.status === "timeout"
+            ? [
+                'The session timed out during initialization (status "timeout"): check the script and the config.',
+            ]
+            : []),
+        "`accessibility: true` is not set in browserstack.yml (or the capabilities); the SDK defaults it to false.",
+        'The platform entry in browserstack.yml does not use `osVersion`, unquoted: with `platformVersion` the SDK selects the device but App Accessibility records no scans, and a quoted "14.0" fails its number check and turns the checks off; neither says so. Write `osVersion: 14.0`.',
+        'The device runs an OS App Accessibility does not support: Android 11 or newer, or iOS 14 or newer, is needed (an older Android reads "update_os_version").',
+        "The driver was created inside the test body: the SDK decides per test, at its start, from the drivers that already exist. Create it in a fixture or setup hook.",
+        "The test only read the screen (find_elements, page_source): scans run on interaction commands such as click/tap, send keys, actions and navigation. Interact with each screen you want scanned.",
+        ...(report.status === "timeout"
+            ? []
+            : [
+                'The session timed out during initialization (status "timeout"): check the script and the config.',
+            ]),
+    ];
+    return [
+        `No accessibility scans were recorded for the App Accessibility build below (status: ${report.status}), so there are no issues to list.`,
+        appBuildDetails(report),
+        "The usual causes, most likely first:",
+        ...causes.map((cause, i) => `${i + 1}. ${cause}`),
+    ];
+}
+const SEVERITY_ORDER = ["critical", "serious", "moderate", "minor"];
+/** How many screens the summary names; the rest are counted. */
+const SUMMARY_SCREENS = 10;
+/** An app report's issues at a glance: by severity, by rule, and by screen. */
+function summaryNote(summary, total) {
+    if (total === 0)
+        return [];
+    const rank = (severity) => {
+        const i = SEVERITY_ORDER.indexOf(severity);
+        return i === -1 ? SEVERITY_ORDER.length : i;
+    };
+    const severities = Object.entries(summary.by_severity)
+        .sort(([a], [b]) => rank(a) - rank(b))
+        .map(([severity, n]) => `${n} ${severity}`)
+        .join(", ");
+    const rules = summary.by_rule
+        .map((r) => `${r.issue_type} ${r.count}`)
+        .join(", ");
+    const shown = summary.by_screen.slice(0, SUMMARY_SCREENS);
+    const more = summary.by_screen.length - shown.length;
+    const screens = `${shown.map((s) => `${s.screen} ${s.count}`).join(", ")}${more > 0 ? `, and ${more} more screens` : ""}`;
+    return [
+        `Summary of the ${total} issues: ${severities}.`,
+        wrapUntrusted("accessibility issue counts", `By rule: ${rules}.\nBy screen: ${screens}.`),
+    ];
+}
+/** How many new and resolved issues a comparison lists per page. */
+const COMPARE_LIST_MAX = 50;
+/** An issue as a comparison lists it: what and where, without the fix text. */
+function compareRow(row) {
+    const { issue_type, rule_id, severity, screen, component, element } = row;
+    return { issue_type, rule_id, severity, screen, component, element };
+}
+/** One page of a comparison's list: the cursor counts the issues already listed. */
+function issueList(label, rows, cursor) {
+    if (cursor > 0 && cursor >= rows.length) {
+        return `${label} (${rows.length}): all listed on earlier pages.`;
+    }
+    const shown = rows.slice(cursor, cursor + COMPARE_LIST_MAX).map(compareRow);
+    const range = rows.length > COMPARE_LIST_MAX
+        ? `, ${cursor + 1} to ${cursor + shown.length}`
+        : "";
+    return `${label} (${rows.length})${range}: ${wrapUntrusted("accessibility scan results", JSON.stringify(shown, null, 2))}`;
+}
+/** The build to compare with, or why there is none. */
+async function baselineAppBuild(reportFetcher, buildId, compareWith) {
+    let baseline;
+    if (compareWith === "previous") {
+        const previous = await reportFetcher.previousAppBuild(buildId);
+        if (!previous) {
+            return "This is its project's first build, so there is nothing earlier to compare it with. Pass an earlier build's id or link as compareWith instead.";
+        }
+        baseline = {
+            buildId: previous.buildId,
+            sameName: previous.same_name,
+            searchedAll: previous.searched_all,
+        };
+    }
+    else {
+        const named = /^https?:\/\//i.test(compareWith)
+            ? await reportFetcher.sourceFromReportUrl(compareWith)
+            : { kind: "build", buildId: compareWith };
+        const source = await reportFetcher.resolveBuild(named);
+        if (source.kind !== "appBuild") {
+            return `compareWith names ${describeSource(source)}, which is not an App Accessibility build. Pass an earlier app build's id or link, or "previous".`;
+        }
+        baseline = { buildId: source.buildId };
+    }
+    if (baseline.buildId === buildId) {
+        return `compareWith names this build itself. Pass an earlier build's id or link, or "previous".`;
+    }
+    return baseline;
+}
+/**
+ * What changed between an earlier app build and this one: issues new in this build,
+ * issues the earlier one had that this one does not, and how many it kept. An issue on a
+ * screen this build did not reach also reads as resolved, so a build that scanned other
+ * screens or ran other tests is called out.
+ */
+async function compareAppBuilds(reportFetcher, source, compareWith, cursor, preface, processing) {
+    const baseline = await baselineAppBuild(reportFetcher, source.buildId, compareWith);
+    if (typeof baseline === "string")
+        return createErrorResponse(baseline);
+    const [named, current] = await Promise.all([
+        reportFetcher.appBuildIssues(baseline.buildId),
+        reportFetcher.appBuildIssues(source.buildId),
+    ]);
+    // A comparison runs from the earlier build to the later; named the other way round, the
+    // new issues would read as resolved and the resolved as new.
+    const reversed = named.created_at !== undefined &&
+        current.created_at !== undefined &&
+        Date.parse(named.created_at) > Date.parse(current.created_at);
+    const [before, after] = reversed ? [current, named] : [named, current];
+    const { added, first_scanned, resolved, unconfirmed, retained } = compareAppIssues(before.issues, after.issues, {
+        sameScreens: before.scan_count === after.scan_count,
+    });
+    const screensOf = (rows) => new Set(rows.map((r) => r.screen)).size;
+    const unreached = screensOf(unconfirmed);
+    const unseen = screensOf(first_scanned);
+    const setApart = [
+        ...(unreached > 0
+            ? [
+                unreached === 1
+                    ? `${unconfirmed.length} more issues of the earlier build are on 1 screen no screen of the later build resembles: the later build did not reach it, or every issue on it was fixed. They are not counted as resolved; scan that screen again to confirm.`
+                    : `${unconfirmed.length} more issues of the earlier build are on ${unreached} screens no screen of the later build resembles: the later build did not reach them, or every issue on them was fixed. They are not counted as resolved; scan those screens again to confirm.`,
+            ]
+            : []),
+        ...(unseen > 0
+            ? [
+                `${first_scanned.length} more issues of the later build are on ${unseen === 1 ? "1 screen" : `${unseen} screens`} no screen of the earlier build resembles: not scanned before, so they are not counted as new.`,
+            ]
+            : []),
+    ];
+    const which = baseline.sameName === undefined
+        ? ""
+        : baseline.sameName
+            ? ", the build before it"
+            : baseline.searchedAll
+                ? ", the build just before it in its project (no earlier build has this build's name)"
+                : ", the build just before it in its project (none of the newest builds before it has this build's name)";
+    const warnings = [];
+    if (before.scan_count !== after.scan_count) {
+        warnings.push(`⚠️ The builds scanned a different number of screens (${after.scan_count} in the later build, ${before.scan_count} in the earlier one): an issue on a screen the later build did not reach reads as resolved without having been fixed. Check the resolved issues' screens before calling them fixed.`);
+    }
+    const notRun = before.tests.filter((t) => !after.tests.includes(t));
+    if (notRun.length > 0) {
+        warnings.push(`⚠️ Some tests had screens scanned in the earlier build but not in the later one; their issues read as resolved without having been checked again. ${wrapUntrusted("test names", JSON.stringify(notRun))}`);
+    }
+    // Build names are the user's own (from their CI or browserstack.yml), so they are data.
+    const builds = wrapUntrusted("App Accessibility builds", JSON.stringify({
+        later: { build_number: after.build_number, name: after.build_name },
+        earlier: { build_number: before.build_number, name: before.build_name },
+    }, null, 2));
+    return createSuccessResponse([
+        ...preface,
+        ...processingNote(processing),
+        ...(reversed
+            ? [
+                "compareWith names a build newer than this one, so the comparison runs from this build (the earlier) to that one (the later).",
+            ]
+            : []),
+        `Compared App Accessibility build #${after.build_number} with build #${before.build_number}${which}: ${added.length} new, ${resolved.length} resolved, ${retained} still open.`,
+        `Builds: ${builds}`,
+        ...setApart,
+        setApart.length > 0
+            ? `Issues are matched one for one by rule and element: its id, or else its class and its text or label; screens, by the elements on them. New, first-scanned and still-open issues add up to the later build's ${after.issues.length}; resolved, not-confirmed and still-open ones to the earlier build's ${before.issues.length}.`
+            : `Issues are matched one for one by rule and element: its id, or else its class and its text or label. New and still-open issues add up to the later build's ${after.issues.length}; resolved and still-open ones to the earlier build's ${before.issues.length}.`,
+        ...warnings,
+        issueList("New issues", added, cursor),
+        issueList("Resolved issues", resolved, cursor),
+        ...(unconfirmed.length > 0
+            ? [issueList("Not confirmed resolved", unconfirmed, cursor)]
+            : []),
+        ...(first_scanned.length > 0
+            ? [
+                issueList("On screens first scanned in the later build", first_scanned, cursor),
+            ]
+            : []),
+        Math.max(added.length, resolved.length, unconfirmed.length, first_scanned.length) >
+            cursor + COMPARE_LIST_MAX
+            ? `More to list: call fetchAccessibilityIssues with buildId: "${source.buildId}", compareWith: "${compareWith}" and cursor: ${cursor + COMPARE_LIST_MAX}.`
+            : `Read the later build's open issues with fetchAccessibilityIssues with buildId: "${after.buildId}".`,
+    ]);
+}
+/** How an app page's issues name what they share, which the page says once. */
+const APP_ISSUES_SHAPE = "Each issue names its rule (rule_id) and screen: the rule's name, description, WCAG criteria and usual fix are under rules, each screen's screenshot under screens, and measured holds what the rule measured on the element.";
+/** An app build's issues come inline from its scanned screens; there is no CSV to link. */
+async function appBuildMessages(reportFetcher, source, cursor, preface, processing, stillProcessing) {
+    const report = await reportFetcher.appBuildReport(source.buildId, cursor);
+    if (report.scan_count === 0 && !stillProcessing) {
+        return [...preface, ...processingNote(processing), ...noScansNote(report)];
+    }
+    const { records, page_length, total_issues, next_page } = report;
+    const screens = `${report.scan_count} screen${report.scan_count === 1 ? "" : "s"} scanned`;
+    return [
+        ...preface,
+        ...processingNote(processing),
+        `Retrieved ${page_length} accessibility issues (Total: ${total_issues}) from the App Accessibility build below (${screens})`,
+        appBuildDetails(report),
+        ...(cursor === 0 ? summaryNote(report.summary, total_issues) : []),
+        ...(report.screens_read !== undefined
+            ? [
+                `Only the first ${report.screens_read} of the build's ${report.scan_count} scanned screens were read; the total counts the issues on those. The dashboard report has them all.`,
+            ]
+            : []),
+        ...excludedIssuesNote(null, 0, report.hidden_issues),
+        APP_ISSUES_SHAPE,
+        `Issues: ${wrapUntrusted("accessibility scan results", JSON.stringify({ issues: records, rules: report.rules, screens: report.screens }, null, 2))}`,
+        closingMessage(next_page, report.remaining, source, stillProcessing),
+    ];
+}
+/**
+ * A manual report's issues come inline from its scanned screens: the dashboard's own, with
+ * its duplicates left out, when its route takes the access key; else every occurrence the
+ * Manual Reports API lists, which does not mark duplicates, so the dashboard's count is
+ * stated next to the total rather than reproduced.
+ */
+async function appReportMessages(reportFetcher, source, cursor, preface, processing, stillProcessing) {
+    const report = await reportFetcher.appReportIssues(source.reportId, cursor);
+    // The report's name is whatever its author typed, so it is quoted as data.
+    const details = `Report: ${wrapUntrusted("App Accessibility manual report", JSON.stringify({ name: report.report_name, dashboard_link: report.dashboard_link }, null, 2))}`;
+    if (report.scan_count === 0 && !stillProcessing) {
+        return [
+            ...preface,
+            ...processingNote(processing),
+            `No screens were scanned in the App Accessibility manual report below (status: ${report.status}), so there are no issues to list.`,
+            details,
+        ];
+    }
+    const { records, page_length, total_issues, next_page } = report;
+    const where = `${report.scan_count} screen${report.scan_count === 1 ? "" : "s"} scanned${report.device ? ` on ${report.device}` : ""}`;
+    const dashboardNote = report.duplicate_occurrences === 0
+        ? []
+        : report.deduplicated
+            ? [
+                `${report.duplicate_occurrences} duplicate occurrences are left out, as the dashboard leaves them out of its count.`,
+            ]
+            : [
+                `The dashboard counts ${report.dashboard_count} issues for this report: ${report.duplicate_occurrences} of the occurrences are duplicates it folds, which the API does not mark.`,
+            ];
+    const counted = report.deduplicated ? "issues" : "issue occurrences";
+    return [
+        ...preface,
+        ...processingNote(processing),
+        `Retrieved ${page_length} accessibility ${counted} (Total: ${total_issues}) from the App Accessibility manual report below (${where})`,
+        details,
+        ...(cursor === 0 ? summaryNote(report.summary, total_issues) : []),
+        ...dashboardNote,
+        ...excludedIssuesNote(null, 0, report.hidden_issues),
+        APP_ISSUES_SHAPE,
+        `Issues: ${wrapUntrusted("accessibility scan results", JSON.stringify({ issues: records, rules: report.rules, screens: report.screens }, null, 2))}`,
+        closingMessage(next_page, report.remaining, source, stillProcessing),
+    ];
+}
+async function fetchAccessibilityIssues(requested, config, cursor = 0, context, { compareWith, pageUrl, exportTaskId, } = {}) {
     const reportFetcher = await initializeReportFetcher(config);
-    const source = requested.kind === "link"
+    const named = requested.kind === "link"
         ? await reportFetcher.sourceFromReportUrl(requested.reportUrl)
         : requested;
+    // A build id names a web build or a mobile app build; the APIs tell which.
+    const source = await reportFetcher.resolveBuild(named);
+    // Website Scanner runs and App Accessibility builds can be compared, each in its own way.
+    if (compareWith !== undefined && source.kind === "scan") {
+        return compareScanRuns(requested.kind === "link" ? requested : source, compareWith, config, context);
+    }
+    if (compareWith !== undefined && source.kind !== "appBuild") {
+        return createErrorResponse(`compareWith compares Website Scanner runs and App Accessibility builds; ${describeSource(source)} is neither.`);
+    }
     const processing = await waitForProcessing(reportFetcher, source, cursor === 0, context);
     const stillProcessing = processing.status !== undefined &&
         PROCESSING_STATUSES.has(processing.status);
-    const reportLink = await reportFetcher.getReportLink(source);
-    const { records, page_length, total_issues, next_page, duplicate_issues, unlinked_duplicates, hidden_issues, } = await parseAccessibilityReportFromCSV(reportLink, { nextPage: cursor });
-    const currentlyShown = cursor === 0
-        ? page_length
-        : Math.floor(cursor / JSON.stringify(records[0] || {}).length) +
-            page_length;
-    const remainingIssues = total_issues - currentlyShown;
-    const messages = [
-        ...(requested.kind === "link"
-            ? [`Resolved the report link to ${describeSource(source)}.`]
-            : []),
+    const preface = requested.kind === "link"
+        ? [`Resolved the report link to ${describeSource(source)}.`]
+        : [];
+    if (source.kind === "appBuild" && compareWith !== undefined) {
+        return compareAppBuilds(reportFetcher, source, compareWith, cursor, preface, processing);
+    }
+    if (source.kind === "appBuild") {
+        return createSuccessResponse(await appBuildMessages(reportFetcher, source, cursor, preface, processing, stillProcessing));
+    }
+    if (source.kind === "appReport") {
+        return createSuccessResponse(await appReportMessages(reportFetcher, source, cursor, preface, processing, stillProcessing));
+    }
+    const pageArg = pageUrl ? `, pageUrl: "${pageUrl}"` : "";
+    let reportLink;
+    try {
+        reportLink = await reportFetcher.getReportLink(source, {
+            exportTaskId,
+            onWait: exportProgress(context),
+        });
+    }
+    catch (error) {
+        if (error instanceof ExportPendingError) {
+            return createSuccessResponse(exportPendingMessages(source, error, pageArg));
+        }
+        throw error;
+    }
+    const { records, page_length, total_issues, next_page, remaining, duplicate_issues, unlinked_duplicates, hidden_issues, page, } = await parseAccessibilityReportFromCSV(reportLink, {
+        nextPage: cursor,
+        pageUrl,
+    });
+    return createSuccessResponse([
+        ...preface,
         ...processingNote(processing),
+        ...(page ? pageNote(page) : []),
         `Retrieved ${page_length} accessibility issues (Total: ${total_issues})`,
         ...excludedIssuesNote(duplicate_issues, unlinked_duplicates, hidden_issues),
         `You can also download the full report (CSV) from the following link, valid for about 12 hours: ${reportLink}`,
         `Issues: ${wrapUntrusted("accessibility scan results", JSON.stringify(records, null, 2))}`,
+        closingMessage(next_page, remaining, source, stillProcessing, pageArg),
+    ]);
+}
+/** What one page of a report holds, in the dashboard's page-view terms. */
+function pageNote(page) {
+    if (page.occurrences === 0) {
+        const similar = page.similar_pages?.length
+            ? ` Pages in this report with a similar address: ${wrapUntrusted("report page addresses", JSON.stringify(page.similar_pages))}`
+            : "";
+        return [`No issue in this report is on ${page.url}.${similar}`];
+    }
+    const severities = Object.entries(page.by_severity)
+        .sort(([, a], [, b]) => b - a)
+        .map(([severity, n]) => `${n} ${severity}`)
+        .join(", ");
+    return [
+        `${page.occurrences} issue occurrences on ${page.url} (${severities}), as the dashboard's page view counts them: ${page.distinct_issues} distinct issues, ${page.first_found_here} of them first found on this page. Each issue below is listed once, with occurrences_on_page; first_found_on names the page an issue was first found on when it is another one.`,
     ];
-    if (next_page !== null) {
-        messages.push(`${remainingIssues} more issues available. Use fetchAccessibilityIssues with ${sourceArgs(source)} and cursor: ${next_page} to get the next batch.`);
+}
+/** At most this many new and resolved issues are listed in a comparison. */
+const COMPARE_LIST_LIMIT = 50;
+/**
+ * A Website Scanner run against an earlier run of the same scan: the run before it
+ * ("previous") or a given scanRunId. Issues are matched by rule, element and page; against
+ * the previous run, the dashboard's own counts (the run's changesSinceLastRun) are given too.
+ */
+async function compareScanRuns(requested, compareWith, config, context) {
+    const reportFetcher = await initializeReportFetcher(config);
+    const source = requested.kind === "link"
+        ? await reportFetcher.sourceFromReportUrl(requested.reportUrl)
+        : requested;
+    if (source.kind !== "scan") {
+        return createErrorResponse('compareWith compares Website Scanner runs: pass the newer run (scanId and scanRunId, or its report link) and compareWith: "previous" or the older run\'s scanRunId.');
     }
-    else if (stillProcessing) {
-        messages.push(`All issues found so far retrieved; the report is still processing.`);
+    const previous = await reportFetcher.previousScanRun(source.scanId, source.scanRunId);
+    const baseRunId = compareWith === "previous" ? previous && String(previous.id) : compareWith;
+    if (!baseRunId) {
+        return createErrorResponse(`Run ${source.scanRunId} is the first run of scan ${source.scanId}; there is no earlier run to compare it with.`);
     }
-    else {
-        messages.push(`✅ All issues retrieved.`);
+    const base = { ...source, scanRunId: baseRunId };
+    const againstPrevious = previous !== undefined && String(previous.id) === baseRunId;
+    let links;
+    try {
+        links = await Promise.all([
+            reportFetcher.getReportLink(source, { onWait: exportProgress(context) }),
+            reportFetcher.getReportLink(base, {}),
+        ]);
     }
-    return createSuccessResponse(messages);
+    catch (error) {
+        if (error instanceof ExportPendingError) {
+            return createSuccessResponse([
+                `The CSV exports of these runs are still being generated (waited ${formatDuration(error.waitedMs)}). Call fetchAccessibilityIssues again with the same arguments in about a minute; the exports continue where they are.`,
+            ]);
+        }
+        throw error;
+    }
+    const [after, before] = await Promise.all(links.map(loadMainIssues));
+    const diff = compareIssues(before, after);
+    const changes = againstPrevious
+        ? await reportFetcher.changesSinceLastRun(source.scanId, source.scanRunId)
+        : undefined;
+    const baseLabel = againstPrevious
+        ? `the run before it, run ${baseRunId}${previous?.scanDate ? ` (${previous.scanDate})` : ""}`
+        : `run ${baseRunId}`;
+    const matched = `${diff.added.length} new, ${diff.resolved.length} resolved, ${diff.retained} still open`;
+    const listed = (issues) => wrapUntrusted("accessibility comparison", JSON.stringify(issues.slice(0, COMPARE_LIST_LIMIT), null, 2)) +
+        (issues.length > COMPARE_LIST_LIMIT
+            ? `\n(${issues.length - COMPARE_LIST_LIMIT} more not listed; see the CSV links.)`
+            : "");
+    return createSuccessResponse([
+        ...(requested.kind === "link"
+            ? [`Resolved the report link to ${describeSource(source)}.`]
+            : []),
+        `Compared Website Scanner scan ${source.scanId}: run ${source.scanRunId} with ${baseLabel}.`,
+        changes
+            ? `The dashboard's comparison: ${changes.newIssues} new, ${changes.resolvedIssues} resolved, ${changes.retainedIssues} still open. Matching the issues by rule, element and page gives ${matched}.`
+            : `Matching the issues by rule, element and page: ${matched}.`,
+        `New issues: ${listed(diff.added)}`,
+        `Resolved issues: ${listed(diff.resolved)}`,
+        `CSV of each run, valid for about 12 hours: newer ${links[0]} , older ${links[1]}`,
+    ]);
+}
+/**
+ * What App Accessibility has on record, newest first, with the ids the issues are read by.
+ * Without a project name, the automated listing shows the projects: a build list needs one.
+ */
+async function listAppAccessibilityReports(args, config) {
+    const reportFetcher = await initializeReportFetcher(config);
+    const limit = args.limit ?? 10;
+    const filtered = (what) => args.name ? ` whose ${what} contains "${args.name}"` : "";
+    if (args.kind === "manual") {
+        const { total, reports } = await reportFetcher.listAppManualReports(args.name, limit);
+        if (reports.length === 0) {
+            return createSuccessResponse([
+                `No App Accessibility manual reports${filtered("name")}. Drop the name filter to list the newest reports.`,
+            ]);
+        }
+        return createSuccessResponse([
+            `${total} App Accessibility manual reports (newest first)${filtered("name")}${total > reports.length ? `, showing ${reports.length}` : ""}:`,
+            wrapUntrusted("app accessibility reports", JSON.stringify(reports, null, 2)),
+            `Read a report's issues with fetchAccessibilityIssues with appReportId: <reportId>; its dashboard_link opens it on the dashboard.`,
+        ]);
+    }
+    if (!args.projectName) {
+        const { total, projects } = await reportFetcher.listAppProjects(limit);
+        return createSuccessResponse([
+            `${total} App Accessibility projects (newest first)${total > projects.length ? `, showing ${projects.length}` : ""}:`,
+            wrapUntrusted("app accessibility projects", JSON.stringify(projects, null, 2)),
+            `A build list needs a project: call listAppAccessibilityReports again with projectName: <name> (exact) to list its builds.`,
+        ]);
+    }
+    const { project, total, builds } = await reportFetcher.listAppBuilds(args.projectName, args.name, limit);
+    if (builds.length === 0) {
+        return createSuccessResponse([
+            `No builds of App Accessibility project "${project.name}"${filtered("name")}${args.name
+                ? ". Drop the name filter to list the project's newest builds"
+                : ": nothing has run with accessibility on in it yet"}.`,
+        ]);
+    }
+    return createSuccessResponse([
+        `${total} builds of App Accessibility project "${project.name}" (newest first)${filtered("name")}${total > builds.length ? `, showing ${builds.length}` : ""}:`,
+        wrapUntrusted("app accessibility builds", JSON.stringify(builds, null, 2)),
+        `Read a build's issues with fetchAccessibilityIssues with buildId: <buildId>; it waits while a build is still processing. report_status "failed" with scan_count 0 means the run recorded no scans.`,
+    ]);
+}
+async function executeListAppAccessibilityReports(args, server, config) {
+    try {
+        trackMCP("listAppAccessibilityReports", server.server.getClientVersion(), undefined, config);
+        return await listAppAccessibilityReports(args, config);
+    }
+    catch (error) {
+        return handleMCPError("listAppAccessibilityReports", server, config, error);
+    }
+}
+/** The WCAG versions and levels Website Scanner checks against, and RGAA 4.1, by name. */
+const WCAG_VERSIONS = {
+    wcag2a: "WCAG 2.0 A",
+    wcag2aa: "WCAG 2.0 AA",
+    wcag2aaa: "WCAG 2.0 AAA",
+    wcag21a: "WCAG 2.1 A",
+    wcag21aa: "WCAG 2.1 AA",
+    wcag21aaa: "WCAG 2.1 AAA",
+    wcag22a: "WCAG 2.2 A",
+    wcag22aa: "WCAG 2.2 AA",
+    wcag22aaa: "WCAG 2.2 AAA",
+    rgaa41: "RGAA 4.1",
+};
+/** What the create-scan API uses for a setting the request leaves out. */
+const SCAN_DEFAULTS = {
+    wcagVersion: "wcag21aa",
+    bestPractices: false,
+    needsReview: true,
+    advancedRules: true,
+};
+/** The settings a scan ran with, each marked when it was the API's default. */
+function scanSettingsNote(settings) {
+    const pick = (key) => settings[key] === undefined
+        ? { value: SCAN_DEFAULTS[key], note: " (default)" }
+        : { value: settings[key], note: "" };
+    const wcag = pick("wcagVersion");
+    const onOff = (key) => {
+        const { value, note } = pick(key);
+        return `${value ? "on" : "off"}${note}`;
+    };
+    const name = WCAG_VERSIONS[wcag.value] ?? wcag.value;
+    return `Scan settings: ${name}${wcag.note}, best practices ${onOff("bestPractices")}, needs review ${onOff("needsReview")}, advanced rules ${onOff("advancedRules")}.`;
 }
 async function executeAccessibilityScan(args, context, server, config) {
     try {
         trackMCP("startAccessibilityScan", server.server.getClientVersion(), undefined, config);
-        return await runAccessibilityScan(args.name, args.pageURL, context, config, args.authConfigId, args.advancedRules);
+        return await runAccessibilityScan(args.name, args.pageURL, context, config, args.authConfigId, {
+            wcagVersion: args.wcagVersion,
+            bestPractices: args.bestPractices,
+            needsReview: args.needsReview,
+            advancedRules: args.advancedRules,
+        });
     }
     catch (error) {
         return handleMCPError("startAccessibilityScan", server, config, error);
@@ -331,10 +880,11 @@ async function executeGetAuthConfig(args, server, config) {
 function createScanFailureResponse(name, status) {
     return createErrorResponse(`❌ Accessibility scan "${name}" failed with status: ${status} , check the BrowserStack dashboard for more details [https://scanner.browserstack.com/site-scanner/scan-details/${name}].`);
 }
-function createScanSuccessResponse(name, totalIssues, pageLength, records, scanId, scanRunId, reportUrl, cursor, duplicates = []) {
+function createScanSuccessResponse(name, totalIssues, pageLength, records, scanId, scanRunId, reportUrl, cursor, duplicates = [], settings = {}) {
     const messages = [
         `Accessibility scan "${name}" completed. check the BrowserStack dashboard for more details [https://scanner.browserstack.com/site-scanner/scan-details/${name}].`,
         `Scan ID: ${scanId} and Scan Run ID: ${scanRunId}`,
+        scanSettingsNote(settings),
         `You can also download the full report from the following link: ${reportUrl}`,
         `We found ${totalIssues} issues. Below are the details of the ${pageLength} most critical issues.`,
         ...duplicates,
@@ -345,9 +895,9 @@ function createScanSuccessResponse(name, totalIssues, pageLength, records, scanI
     }
     return createSuccessResponse(messages);
 }
-async function runAccessibilityScan(name, pageURL, context, config, authConfigId, advancedRules) {
+async function runAccessibilityScan(name, pageURL, context, config, authConfigId, settings = {}) {
     const scanner = await initializeScanner(config);
-    const startResp = await scanner.startScan(name, [pageURL], authConfigId, advancedRules);
+    const startResp = await scanner.startScan(name, [pageURL], authConfigId, settings);
     const scanId = startResp.data.id;
     const scanRunId = startResp.data.scanRunId;
     await notifyScanProgress(context, `Accessibility scan "${name}" started`, 0);
@@ -356,32 +906,33 @@ async function runAccessibilityScan(name, pageURL, context, config, authConfigId
         return createScanFailureResponse(name, status);
     }
     const reportFetcher = await initializeReportFetcher(config);
-    const reportLink = await reportFetcher.getReportLink({
-        kind: "scan",
-        scanId,
-        scanRunId,
-    });
+    let reportLink;
+    try {
+        reportLink = await reportFetcher.getReportLink({ kind: "scan", scanId, scanRunId }, { onWait: exportProgress(context) });
+    }
+    catch (error) {
+        if (error instanceof ExportPendingError) {
+            return createSuccessResponse([
+                `Accessibility scan "${name}" completed. Scan ID: ${scanId} and Scan Run ID: ${scanRunId}`,
+                ...exportPendingMessages({
+                    kind: "scan",
+                    scanId: String(scanId),
+                    scanRunId: String(scanRunId),
+                }, error, ""),
+            ]);
+        }
+        throw error;
+    }
     const { records, page_length, total_issues, next_page, duplicate_issues, unlinked_duplicates, hidden_issues, } = await parseAccessibilityReportFromCSV(reportLink);
-    return createScanSuccessResponse(name, total_issues, page_length, records, scanId, scanRunId, reportLink, next_page, excludedIssuesNote(duplicate_issues, unlinked_duplicates, hidden_issues));
+    return createScanSuccessResponse(name, total_issues, page_length, records, scanId, scanRunId, reportLink, next_page, excludedIssuesNote(duplicate_issues, unlinked_duplicates, hidden_issues), settings);
 }
 export default function addAccessibilityTools(server, config) {
     const tools = {};
-    tools.accessibilityExpert = server.tool("accessibilityExpert", "Answer accessibility, a11y, and WCAG questions using BrowserStack's accessibility knowledge base.", {
-        query: z
-            .string()
-            .describe("Any accessibility, a11y, WCAG, or web accessibility question"),
-    }, {
-        title: "Accessibility Expert",
-        readOnlyHint: true,
-        openWorldHint: false,
-        destructiveHint: false,
-        idempotentHint: true,
-    }, async (args) => {
-        return await executeAccessibilityRAG(args, server, config);
-    });
-    tools.startAccessibilityScan = server.tool("startAccessibilityScan", "Start an accessibility scan via BrowserStack and retrieve a local CSV report path.", {
+    tools.startAccessibilityScan = server.tool("startAccessibilityScan", "Scan a web page URL for accessibility issues and get a CSV report. For a mobile app, run it on App Automate with accessibility on (setupBrowserStackAppAutomateTests), then fetchAccessibilityIssues.", {
         name: z.string().describe("Name of the accessibility scan"),
-        pageURL: z.string().describe("The URL to scan for accessibility issues"),
+        pageURL: z
+            .string()
+            .describe("The web page URL to scan for accessibility issues"),
         authConfigId: z
             .number()
             .optional()
@@ -389,7 +940,19 @@ export default function addAccessibilityTools(server, config) {
         advancedRules: z
             .boolean()
             .optional()
-            .describe("Enable advanced accessibility rules in the scan settings"),
+            .describe("Run the advanced accessibility rules (default true)."),
+        wcagVersion: z
+            .enum(Object.keys(WCAG_VERSIONS))
+            .optional()
+            .describe('WCAG version and level to check against, e.g. "wcag22aa", or "rgaa41" for RGAA 4.1 (default "wcag21aa").'),
+        bestPractices: z
+            .boolean()
+            .optional()
+            .describe("Also report best-practice issues (default false)."),
+        needsReview: z
+            .boolean()
+            .optional()
+            .describe('Also report "needs review" issues to check by hand (default true).'),
     }, {
         title: "Start Accessibility Scan",
         readOnlyHint: false,
@@ -472,7 +1035,7 @@ export default function addAccessibilityTools(server, config) {
     }, async (args) => {
         return await executeGetAuthConfig(args, server, config);
     });
-    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch accessibility issues (paged by cursor) from one source: scanId+scanRunId, buildId, workflowReportId or reportUrl." +
+    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch accessibility issues from one source: scanId+scanRunId, buildId, workflowReportId, appReportId or reportUrl." +
         NEEDS_A11Y_SCAN_ID, {
         scanId: z
             .string()
@@ -486,19 +1049,36 @@ export default function addAccessibilityTools(server, config) {
             .string()
             .regex(/^[a-z0-9]{40}$/, "40 lowercase letters and digits")
             .optional()
-            .describe("Automated Tests: the thBuildId in the build's accessibility report link (not the Automate build id)."),
+            .describe("Automated Tests or App Accessibility build id: the SDK's testhub id, or the thBuildId in a web report link."),
         workflowReportId: z
             .string()
             .optional()
             .describe("Workflow Analyzer: the report's numeric id."),
+        appReportId: z
+            .string()
+            .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, "A manual report id is a UUID")
+            .optional()
+            .describe("Manual App Accessibility report id (a UUID), from listAppAccessibilityReports or its /report/ link."),
         reportUrl: z
             .string()
             .optional()
-            .describe("A Website Scanner or Automated Tests report link from the Accessibility dashboard (carries thBuildId)."),
+            .describe("A web or app report link (dashboard, scanner share link, manual report), or an Automate or App Automate link."),
         cursor: z
             .number()
             .optional()
-            .describe("Character offset for pagination (default: 0)"),
+            .describe("Character offset for pagination (default: 0); with compareWith, how many issues are already listed."),
+        pageUrl: z
+            .string()
+            .optional()
+            .describe("Only the issues on this page URL, counted as the dashboard's page view counts them."),
+        compareWith: z
+            .string()
+            .optional()
+            .describe(`"previous", an older scanRunId (Website Scanner), or an earlier app build's id or link; lists new and resolved issues.`),
+        exportTaskId: z
+            .string()
+            .optional()
+            .describe("Continue a CSV export that an earlier call said is still being generated."),
     }, {
         title: "Fetch Accessibility Issues",
         readOnlyHint: true,
@@ -508,5 +1088,36 @@ export default function addAccessibilityTools(server, config) {
     }, async (args, context) => {
         return await executeFetchAccessibilityIssues(args, context, server, config);
     });
+    tools.listAppAccessibilityReports = server.tool("listAppAccessibilityReports", "List App Accessibility work newest first, with the ids fetchAccessibilityIssues reads: a project's builds (automated; omit projectName to list projects) or manual reports.", {
+        kind: z
+            .enum(["automated", "manual"])
+            .optional()
+            .default("automated")
+            .describe("automated (App Automate builds, default) or manual (Workflow Analyzer reports)."),
+        projectName: z
+            .string()
+            .optional()
+            .describe("Automated only: the exact App Accessibility project name; omit to list the projects."),
+        name: z
+            .string()
+            .optional()
+            .describe("Partial build or report name to filter by."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(30)
+            .optional()
+            .default(10)
+            .describe("Rows to return, newest first (1 to 30, default 10)."),
+    }, {
+        title: "List App Accessibility Reports",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
+        return await executeListAppAccessibilityReports(args, server, config);
+    });
     return tools;
 }