@browserstack/mcp-server 2.2.4-beta.1 → 2.2.5-beta.1

package/dist/tools/accessibility.d.ts

@@ -1,3 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BrowserStackConfig } from "../lib/types.js";
+/** How often, and for how long, a first read waits on a report that is still processing. */
+export declare const REPORT_STATUS_POLL_MS = 10000;
+export declare const REPORT_STATUS_WAIT_MS: number;
 export default function addAccessibilityTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/accessibility.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { AccessibilityScanner } from "./accessiblity-utils/scanner.js";
-import { AccessibilityReportFetcher } from "./accessiblity-utils/report-fetcher.js";
+import { AccessibilityReportFetcher, } from "./accessiblity-utils/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";
@@ -26,11 +26,15 @@ function createErrorResponse(message) {
         isError: true,
     };
 }
+/**
+ * Each message ends with a newline: clients that join text blocks with no separator
+ * would otherwise run a link at the end of one block into the next block's first word.
+ */
 function createSuccessResponse(messages) {
     return {
         content: messages.map((text) => ({
             type: "text",
-            text,
+            text: `${text}\n`,
         })),
     };
 }
@@ -71,30 +75,170 @@ async function executeAccessibilityRAG(args, server, config) {
         return handleMCPError("accessibilityExpert", server, config, error);
     }
 }
-async function executeFetchAccessibilityIssues(args, server, config) {
+/** 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.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).";
+    }
+    if (args.reportUrl)
+        return { kind: "link", reportUrl: args.reportUrl };
+    if (args.buildId)
+        return { kind: "build", buildId: args.buildId };
+    if (args.workflowReportId) {
+        return { kind: "workflow", reportId: args.workflowReportId };
+    }
+    if (!args.scanId || !args.scanRunId) {
+        return "A Website Scanner run needs both scanId and scanRunId.";
+    }
+    return { kind: "scan", scanId: args.scanId, scanRunId: args.scanRunId };
+}
+/** The arguments that name the same source again, for the next-page hint. */
+function sourceArgs(source) {
+    switch (source.kind) {
+        case "scan":
+            return `scanId: "${source.scanId}", scanRunId: "${source.scanRunId}"`;
+        case "build":
+            return `buildId: "${source.buildId}"`;
+        case "workflow":
+            return `workflowReportId: "${source.reportId}"`;
+    }
+}
+/** What a dashboard link resolved to, in words. */
+function describeSource(source) {
+    switch (source.kind) {
+        case "scan":
+            return `Website Scanner scan ${source.scanId}, run ${source.scanRunId}`;
+        case "build":
+            return `Automated Tests build ${source.buildId}`;
+        case "workflow":
+            return `Workflow Analyzer report ${source.reportId}`;
+    }
+}
+async function executeFetchAccessibilityIssues(args, context, server, config) {
     try {
         trackMCP("fetchAccessibilityIssues", server.server.getClientVersion(), undefined, config);
-        return await fetchAccessibilityIssues(args.scanId, args.scanRunId, config, args.cursor);
+        const source = issueSourceFrom(args);
+        if (typeof source === "string")
+            return createErrorResponse(source);
+        return await fetchAccessibilityIssues(source, config, args.cursor, context);
     }
     catch (error) {
         return handleMCPError("fetchAccessibilityIssues", server, config, error);
     }
 }
-async function fetchAccessibilityIssues(scanId, scanRunId, config, cursor = 0) {
+/**
+ * What the total leaves out, as the dashboard's count does: duplicate occurrences (folded
+ * into their main issue only where one could be matched) and issues hidden in the dashboard.
+ */
+function excludedIssuesNote(duplicates, unlinked, hidden) {
+    const notes = [];
+    if (duplicates) {
+        const folded = duplicates - unlinked;
+        const how = unlinked === 0
+            ? " are folded into their main issue (see duplicate_count) and are not included in the total."
+            : folded > 0
+                ? ` are not included in the total. ${folded} are folded into their main issue (see duplicate_count); ${unlinked} could not be matched to one.`
+                : " are not included in the total.";
+        notes.push(`This report groups repeated occurrences: ${duplicates} duplicate occurrences${how}`);
+    }
+    if (hidden) {
+        notes.push(`${hidden} issues hidden in the dashboard are not included, as the dashboard leaves them out of its count too.`);
+    }
+    return notes;
+}
+/** 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. */
+const PROCESSING_STATUSES = new Set([
+    "queued",
+    "running",
+    "processing",
+    "finalizing",
+]);
+/**
+ * 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
+ * minutes after the tests end), so a first read waits for it, reporting progress, for up to
+ * REPORT_STATUS_WAIT_MS. A later page does not wait again, and a status that cannot be read
+ * is not waited on.
+ */
+async function waitForProcessing(reportFetcher, source, wait, context) {
+    const started = Date.now();
+    const firstStatus = await reportFetcher.reportStatus(source);
+    let status = firstStatus;
+    while (wait &&
+        status &&
+        PROCESSING_STATUSES.has(status) &&
+        Date.now() - started < REPORT_STATUS_WAIT_MS) {
+        const waited = Date.now() - started;
+        if (context) {
+            await notifyScanProgress(context, `The report is still ${status}; waiting for it to complete (${formatDuration(waited)} of up to ${formatDuration(REPORT_STATUS_WAIT_MS)}).`, Math.min(99, Math.round((waited / REPORT_STATUS_WAIT_MS) * 100)));
+        }
+        await new Promise((resolve) => setTimeout(resolve, REPORT_STATUS_POLL_MS));
+        status = await reportFetcher.reportStatus(source);
+    }
+    return { status, firstStatus, waitedMs: Date.now() - started };
+}
+function formatDuration(ms) {
+    const seconds = Math.round(ms / 1000);
+    return seconds < 60
+        ? `${seconds}s`
+        : `${Math.floor(seconds / 60)}m ${String(seconds % 60).padStart(2, "0")}s`;
+}
+/** What the answer says about the report's processing, if anything. */
+function processingNote({ status, firstStatus, waitedMs, }) {
+    if (status && PROCESSING_STATUSES.has(status)) {
+        const meaning = status === "finalizing"
+            ? ", which on an advanced scan means advanced issue processing"
+            : "";
+        return [
+            `⚠️ This report is still processing (status: ${status}${meaning}). The issues below are only those found so far: more will be added and the total will grow. Call fetchAccessibilityIssues again in a few minutes for the complete list.`,
+        ];
+    }
+    if (firstStatus && PROCESSING_STATUSES.has(firstStatus)) {
+        return [
+            `The report was still processing (status: ${firstStatus}); waited ${formatDuration(waitedMs)} for it to complete before reading its issues.`,
+        ];
+    }
+    return [];
+}
+async function fetchAccessibilityIssues(requested, config, cursor = 0, context) {
     const reportFetcher = await initializeReportFetcher(config);
-    const reportLink = await reportFetcher.getReportLink(scanId, scanRunId);
-    const { records, page_length, total_issues, next_page } = await parseAccessibilityReportFromCSV(reportLink, { nextPage: cursor });
+    const source = requested.kind === "link"
+        ? await reportFetcher.sourceFromReportUrl(requested.reportUrl)
+        : requested;
+    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)}.`]
+            : []),
+        ...processingNote(processing),
         `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))}`,
     ];
     if (next_page !== null) {
-        messages.push(`${remainingIssues} more issues available. Use fetchAccessibilityIssues with cursor: ${next_page} to get the next batch.`);
+        messages.push(`${remainingIssues} more issues available. Use fetchAccessibilityIssues with ${sourceArgs(source)} and cursor: ${next_page} to get the next batch.`);
+    }
+    else if (stillProcessing) {
+        messages.push(`All issues found so far retrieved; the report is still processing.`);
     }
     else {
         messages.push(`✅ All issues retrieved.`);
@@ -181,12 +325,13 @@ 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) {
+function createScanSuccessResponse(name, totalIssues, pageLength, records, scanId, scanRunId, reportUrl, cursor, duplicates = []) {
     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}`,
         `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,
         `Scan results: ${wrapUntrusted("accessibility scan results", JSON.stringify(records, null, 2))}`,
     ];
     if (cursor !== null) {
@@ -205,9 +350,13 @@ async function runAccessibilityScan(name, pageURL, context, config, authConfigId
         return createScanFailureResponse(name, status);
     }
     const reportFetcher = await initializeReportFetcher(config);
-    const reportLink = await reportFetcher.getReportLink(scanId, scanRunId);
-    const { records, page_length, total_issues, next_page } = await parseAccessibilityReportFromCSV(reportLink);
-    return createScanSuccessResponse(name, total_issues, page_length, records, scanId, scanRunId, reportLink, next_page);
+    const reportLink = await reportFetcher.getReportLink({
+        kind: "scan",
+        scanId,
+        scanRunId,
+    });
+    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));
 }
 export default function addAccessibilityTools(server, config) {
     const tools = {};
@@ -317,14 +466,28 @@ export default function addAccessibilityTools(server, config) {
     }, async (args) => {
         return await executeGetAuthConfig(args, server, config);
     });
-    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch accessibility issues from a completed scan with pagination support. Use cursor parameter to get subsequent pages of results." +
+    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch accessibility issues with pagination support, from exactly one source: a completed Website Scanner run (scanId with scanRunId), an Automated Tests build from a BrowserStack SDK test run (buildId), a Workflow Analyzer report (workflowReportId), or a Website Scanner or Automated Tests report's dashboard link (reportUrl). Also returns a link to download the full report as a CSV. Use cursor parameter to get subsequent pages of results." +
         NEEDS_A11Y_SCAN_ID, {
         scanId: z
             .string()
-            .describe("The scan ID from a completed accessibility scan"),
+            .optional()
+            .describe("Website Scanner: the scan ID from a completed accessibility scan"),
         scanRunId: z
             .string()
-            .describe("The scan run ID from a completed accessibility scan"),
+            .optional()
+            .describe("Website Scanner: the scan run ID from a completed accessibility scan"),
+        buildId: z
+            .string()
+            .optional()
+            .describe("Automated Tests: the Accessibility build id, shown as thBuildId in the build's accessibility report link (40 lowercase letters and digits). Not the Automate build id or the build name."),
+        workflowReportId: z
+            .string()
+            .optional()
+            .describe("Workflow Analyzer: the report's numeric id, e.g. 123456"),
+        reportUrl: z
+            .string()
+            .optional()
+            .describe("A report's Accessibility dashboard link, as the user pasted it: a Website Scanner or Automated Tests report link carrying thBuildId. A Website Scanner link resolves only to its scan's latest run. Workflow Analyzer links are not supported; use workflowReportId."),
         cursor: z
             .number()
             .optional()
@@ -335,8 +498,8 @@ export default function addAccessibilityTools(server, config) {
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
-    }, async (args) => {
-        return await executeFetchAccessibilityIssues(args, server, config);
+    }, async (args, context) => {
+        return await executeFetchAccessibilityIssues(args, context, server, config);
     });
     return tools;
 }

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

@@ -1,8 +1,47 @@
+/** What to read issues from: a Website Scanner run, an Automated Tests build or a Workflow Analyzer report. */
+export type IssueSource = {
+    kind: "scan";
+    scanId: string;
+    scanRunId: string;
+} | {
+    kind: "build";
+    buildId: string;
+} | {
+    kind: "workflow";
+    reportId: string;
+};
+/**
+ * How far a report link's scan is searched for. The scan list has no name or link filter and
+ * spans the whole organisation, so the walk covers only the newest scans, which is where a
+ * link someone just opened will be. It runs at the list's default page size (~1.2 s a page):
+ * at limit=50 or 100 the cursor skips scans, so a larger page cannot be used to go faster.
+ */
+export declare const MAX_SCAN_LIST_PAGES = 15;
 export declare class AccessibilityReportFetcher {
     private auth;
     setAuth(auth: {
         username: string;
         password: string;
     }): void;
-    getReportLink(scanId: string, scanRunId: string): Promise<string>;
+    private authHeaders;
+    /**
+     * The source a dashboard report link points at. An Automated Tests link carries the build
+     * id itself. A Website Scanner link carries the thBuildId of one run, which only the scan
+     * list can map to ids: each scan there carries its latest run's link. A link to an older
+     * run therefore matches no scan, and is reported as such rather than guessed at.
+     */
+    sourceFromReportUrl(reportUrl: string): Promise<IssueSource>;
+    /** Walk the newest scans for the one whose own link carries this thBuildId. */
+    private findScanRun;
+    getReportLink(source: IssueSource): Promise<string>;
+    /**
+     * Where the report is in its processing, as the report's own status reads it: `completed`,
+     * or `queued` / `running` / `processing` / `finalizing` while issues are still being added.
+     * Undefined when it cannot be read. A build's overview carries no status, so a build's comes
+     * from its project's build list (newest first), found by id.
+     */
+    reportStatus(source: IssueSource): Promise<string | undefined>;
+    private buildStatus;
+    /** The `data` of a successful API response, or undefined. */
+    private getData;
 }

package/dist/tools/accessiblity-utils/report-fetcher.js

@@ -1,37 +1,160 @@
 import { apiClient } from "../../lib/apiClient.js";
+const API_BASE = "https://api-accessibility.browserstack.com/api";
+/**
+ * How far a report link's scan is searched for. The scan list has no name or link filter and
+ * spans the whole organisation, so the walk covers only the newest scans, which is where a
+ * link someone just opened will be. It runs at the list's default page size (~1.2 s a page):
+ * at limit=50 or 100 the cursor skips scans, so a larger page cannot be used to go faster.
+ */
+export const MAX_SCAN_LIST_PAGES = 15;
+/** A build whose status is checked is one just run, so it sits at the top of its project's list. */
+const MAX_BUILD_LIST_PAGES = 3;
+/** The thBuildId a dashboard report link carries, if any. */
+function thBuildIdOf(link) {
+    try {
+        return link ? new URL(link).searchParams.get("thBuildId") : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Each source exports its issues the same way: one call starts a CSV export and returns a
+ * task id, and the same route polled with that task id returns the link. Only the route and
+ * its parameter names differ (the scanner's are snake_case, the other two camelCase).
+ */
+function exportUrls(source) {
+    const q = encodeURIComponent;
+    switch (source.kind) {
+        case "scan": {
+            const route = `${API_BASE}/website-scanner/v1/scans/${q(source.scanId)}/scan_runs/issues`;
+            return {
+                start: `${route}?scan_run_id=${q(source.scanRunId)}`,
+                poll: (taskId) => `${route}?task_id=${q(taskId)}`,
+            };
+        }
+        case "build": {
+            const route = `${API_BASE}/automated-tests/v1/builds/issues`;
+            return {
+                start: `${route}?buildUuid=${q(source.buildId)}`,
+                poll: (taskId) => `${route}?taskId=${q(taskId)}`,
+            };
+        }
+        case "workflow": {
+            const route = `${API_BASE}/workflow-analyzer/v1/reports/issues`;
+            return {
+                start: `${route}?reportId=${q(source.reportId)}`,
+                poll: (taskId) => `${route}?taskId=${q(taskId)}`,
+            };
+        }
+    }
+}
+/** Why an export did not start, in the API's words, and where a build's id comes from when it is not found. */
+function startFailure(source, status, body) {
+    const reason = [body?.error].flat().filter(Boolean).join("; ") ||
+        body?.data?.message ||
+        `HTTP ${status}`;
+    // The API takes only its own build id; the Automate build id is a 404 "Build not found".
+    const hint = status === 404 && source.kind === "build"
+        ? ". Pass the Accessibility build id: the thBuildId in the build's accessibility report link (40 lowercase letters and digits), not the Automate build id or the build name"
+        : "";
+    return `Failed to initiate report: ${reason}${hint}`;
+}
 export class AccessibilityReportFetcher {
     auth;
     setAuth(auth) {
         this.auth = auth;
     }
-    async getReportLink(scanId, scanRunId) {
-        // Initiate CSV link generation
-        const initUrl = `https://api-accessibility.browserstack.com/api/website-scanner/v1/scans/${scanId}/scan_runs/issues?scan_run_id=${scanRunId}`;
-        let basicAuthHeader = undefined;
-        if (this.auth) {
-            const { username, password } = this.auth;
-            basicAuthHeader =
-                "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+    authHeaders() {
+        if (!this.auth)
+            return undefined;
+        const { username, password } = this.auth;
+        return {
+            Authorization: "Basic " + Buffer.from(`${username}:${password}`).toString("base64"),
+        };
+    }
+    /**
+     * The source a dashboard report link points at. An Automated Tests link carries the build
+     * id itself. A Website Scanner link carries the thBuildId of one run, which only the scan
+     * list can map to ids: each scan there carries its latest run's link. A link to an older
+     * run therefore matches no scan, and is reported as such rather than guessed at.
+     */
+    async sourceFromReportUrl(reportUrl) {
+        let url;
+        try {
+            url = new URL(reportUrl);
+        }
+        catch {
+            url = undefined;
+        }
+        const thBuildId = url?.searchParams.get("thBuildId");
+        if (url && thBuildId && url.pathname.includes("/automated-tests/")) {
+            return { kind: "build", buildId: thBuildId };
+        }
+        const scanName = url?.pathname.match(/\/site-scanner\/projects\/([^/]+)\/builds/)?.[1];
+        if (thBuildId && scanName) {
+            return this.findScanRun(thBuildId, decodeURIComponent(scanName));
+        }
+        throw new Error("This link does not name a report the API can look up. Pass an Automated Tests or Website Scanner report link from the Accessibility dashboard (both carry thBuildId), or the ids: scanId with scanRunId, buildId, or workflowReportId");
+    }
+    /** Walk the newest scans for the one whose own link carries this thBuildId. */
+    async findScanRun(thBuildId, scanName) {
+        let nextPage;
+        let sameName;
+        for (let page = 0; page < MAX_SCAN_LIST_PAGES; page++) {
+            const resp = await apiClient.get({
+                url: `${API_BASE}/website-scanner/v1/scans${nextPage ? `?nextPage=${encodeURIComponent(nextPage)}` : ""}`,
+                headers: this.authHeaders(),
+            });
+            const data = resp.data?.data;
+            for (const scan of data?.scans ?? []) {
+                if (thBuildIdOf(scan.scanUrl) === thBuildId) {
+                    return {
+                        kind: "scan",
+                        scanId: String(scan.id),
+                        scanRunId: String(scan.lastScanDetails?.scanRunId),
+                    };
+                }
+                if (sameName === undefined && scan.name === scanName) {
+                    sameName = scan.id;
+                }
+            }
+            if (!data?.pagination?.hasNext || !data.pagination.nextPage) {
+                nextPage = undefined;
+                break;
+            }
+            nextPage = data.pagination.nextPage;
         }
+        if (sameName !== undefined) {
+            throw new Error(`This link is to an earlier run of scan "${scanName}" (scanId ${sameName}). A link resolves only to a scan's latest run; ask the user for that run's scanRunId and pass it with scanId ${sameName}`);
+        }
+        // nextPage is still set only when the walk stopped at the page cap, not at the end.
+        const searched = nextPage
+            ? ` among the most recent scans (${MAX_SCAN_LIST_PAGES} pages)`
+            : "";
+        throw new Error(`No Website Scanner scan${searched} matches this link. Pass scanId and scanRunId instead`);
+    }
+    async getReportLink(source) {
+        const urls = exportUrls(source);
+        // Initiate CSV link generation
         const initResp = await apiClient.get({
-            url: initUrl,
-            headers: basicAuthHeader ? { Authorization: basicAuthHeader } : undefined,
+            url: urls.start,
+            headers: this.authHeaders(),
+            raise_error: false,
         });
         const initData = initResp.data;
-        if (!initData.success) {
-            throw new Error(`Failed to initiate report: ${initData.error || initData.data.message}`);
+        if (!initResp.ok || !initData?.success) {
+            throw new Error(startFailure(source, initResp.status, initData));
         }
         const taskId = initData.data.task_id;
         // Poll for the generated CSV link (task is async, may take a few seconds)
-        const reportUrl = `https://api-accessibility.browserstack.com/api/website-scanner/v1/scans/${scanId}/scan_runs/issues?task_id=${encodeURIComponent(taskId)}`;
+        const reportUrl = urls.poll(taskId);
         const maxAttempts = 3;
         const pollIntervalMs = 2000;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             const reportResp = await apiClient.get({
                 url: reportUrl,
-                headers: basicAuthHeader
-                    ? { Authorization: basicAuthHeader }
-                    : undefined,
+                headers: this.authHeaders(),
             });
             const reportData = reportResp.data;
             if (!reportData.success) {
@@ -45,4 +168,52 @@ export class AccessibilityReportFetcher {
         }
         throw new Error(`Report link was not available after ${maxAttempts} attempts. The CSV generation may still be in progress.`);
     }
+    /**
+     * Where the report is in its processing, as the report's own status reads it: `completed`,
+     * or `queued` / `running` / `processing` / `finalizing` while issues are still being added.
+     * Undefined when it cannot be read. A build's overview carries no status, so a build's comes
+     * from its project's build list (newest first), found by id.
+     */
+    async reportStatus(source) {
+        const q = encodeURIComponent;
+        try {
+            switch (source.kind) {
+                case "scan":
+                    return (await this.getData(`${API_BASE}/website-scanner/v1/scans/${q(source.scanId)}/scan_runs/${q(source.scanRunId)}/status`))?.status;
+                case "workflow":
+                    return (await this.getData(`${API_BASE}/workflow-analyzer/v1/reports/${q(source.reportId)}`))?.summary?.status;
+                case "build":
+                    return await this.buildStatus(source.buildId);
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async buildStatus(buildId) {
+        const q = encodeURIComponent;
+        const project = (await this.getData(`${API_BASE}/automated-tests/v1/builds/${q(buildId)}`))?.projectName;
+        if (!project)
+            return undefined;
+        let nextPage;
+        for (let page = 0; page < MAX_BUILD_LIST_PAGES; page++) {
+            const data = await this.getData(`${API_BASE}/automated-tests/v1/builds?project_name=${q(project)}&limit=100${nextPage ? `&next_page=${q(nextPage)}` : ""}`);
+            const row = data?.builds?.find((build) => build.id === buildId);
+            if (row)
+                return row.status;
+            if (!data?.pagination?.has_next || !data.pagination.next_page)
+                break;
+            nextPage = data.pagination.next_page;
+        }
+        return undefined;
+    }
+    /** The `data` of a successful API response, or undefined. */
+    async getData(url) {
+        const resp = await apiClient.get({
+            url,
+            headers: this.authHeaders(),
+            raise_error: false,
+        });
+        return resp.ok ? resp.data?.data : undefined;
+    }
 }

package/dist/tools/accessiblity-utils/report-parser.d.ts

@@ -5,6 +5,12 @@ type SimplifiedAccessibilityIssue = {
     HTML_snippet: string;
     how_to_fix: string;
     severity: string;
+    /** The page the issue is on; builds and Workflow Analyzer reports span several. */
+    affected_page: string;
+    /** Automated Tests builds only: the test that found the issue. */
+    source_test?: string;
+    /** Grouped reports only: how many duplicate rows point at this issue. */
+    duplicate_count?: number;
 };
 type PaginationOptions = {
     /** How many JSON-chars max per “page” (default 10000) */
@@ -16,8 +22,15 @@ type PaginatedResult = {
     records: SimplifiedAccessibilityIssue[];
     /** Character offset for the next page, or null if done */
     page_length: number;
+    /** Main issues only when the report is grouped, so it matches the run's issue count. */
     total_issues: number;
     next_page: number | null;
+    /** Duplicate rows left out of `records`; null when the report is not grouped. */
+    duplicate_issues: number | null;
+    /** Of those, the ones whose main issue could not be identified (counted only here). */
+    unlinked_duplicates: number;
+    /** Issues hidden in the dashboard and left out; null when the export has no Issue status. */
+    hidden_issues: number | null;
 };
 export declare function parseAccessibilityReportFromCSV(reportLink: string, { maxCharacterLength, nextPage }?: PaginationOptions): Promise<PaginatedResult>;
 export {};

package/dist/tools/accessiblity-utils/report-parser.js

@@ -1,6 +1,19 @@
 import { apiClient } from "../../lib/apiClient.js";
 import { parse } from "csv-parse/sync";
 import logger from "../../logger.js";
+const SOURCE_TEST_COLUMN = "Source test";
+const DUPLICATE_COLUMN = "Duplicate Issue of";
+const ISSUE_LINK_COLUMN = "Issue link";
+const STATUS_COLUMN = "Issue status";
+/** An issue hidden in the dashboard, which leaves it out of its count. */
+function isHidden(row) {
+    return (row[STATUS_COLUMN] ?? "").trim().toLowerCase() === "hidden";
+}
+/** A grouped report marks a main issue `NA`; a duplicate carries its main issue's link. */
+function isMainIssue(row) {
+    const value = (row[DUPLICATE_COLUMN] ?? "").trim();
+    return value === "" || value.toUpperCase() === "NA";
+}
 export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacterLength = 5000, nextPage = 0 } = {}) {
     // 1) Download & parse
     const res = await apiClient.get({ url: reportLink });
@@ -8,9 +21,13 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
         throw new Error(`Failed to download report: ${res.statusText}`);
     const text = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
     let parsed;
+    let columns = [];
     try {
         parsed = parse(text, {
-            columns: true,
+            columns: (header) => {
+                columns = header;
+                return header;
+            },
             skip_empty_lines: true,
             relax_column_count_less: true,
         });
@@ -19,16 +36,63 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
         logger.error(`[AccessibilityReport] CSV parse failed (${text.length} chars): ${err instanceof Error ? err.message : String(err)}`);
         throw err;
     }
-    const all = parsed.map((row) => ({
-        issue_type: row["Issue type"],
-        component: row["Component"],
-        issue_description: row["Issue description"],
-        HTML_snippet: row["HTML snippet"],
-        how_to_fix: row["How to fix this issue"],
-        severity: (row["Severity"] || "unknown").trim(),
-    }));
+    // 2) Leave out hidden issues and fold duplicates into their main issue, as the
+    // dashboard's count does.
+    //
+    // A hidden issue (Issue status "hidden") is left out with every occurrence of it. In a
+    // grouped report, a duplicate's "Duplicate Issue of" is the exact "Issue link" of the
+    // main issue it repeats, so the two are matched verbatim. A value that matches no main
+    // issue, or matches more than one, is not guessed at: it is counted in
+    // `unlinked_duplicates` and the duplicate total, never against a specific issue.
+    const grouped = columns.includes(DUPLICATE_COLUMN);
+    const linkable = grouped && columns.includes(ISSUE_LINK_COLUMN);
+    const hasSourceTest = columns.includes(SOURCE_TEST_COLUMN);
+    const mainRows = grouped ? parsed.filter(isMainIssue) : parsed;
+    const visibleMainRows = mainRows.filter((row) => !isHidden(row));
+    const duplicateRows = grouped
+        ? parsed.filter((row) => !isMainIssue(row))
+        : [];
+    const recordOf = new Map();
+    const all = visibleMainRows.map((row) => {
+        const record = {
+            issue_type: row["Issue type"],
+            component: row["Component"],
+            issue_description: row["Issue description"],
+            HTML_snippet: row["HTML snippet"],
+            how_to_fix: row["How to fix this issue"],
+            severity: (row["Severity"] || "unknown").trim(),
+            affected_page: row["Affected page"],
+            ...(hasSourceTest ? { source_test: row[SOURCE_TEST_COLUMN] } : {}),
+            ...(linkable ? { duplicate_count: 0 } : {}),
+        };
+        recordOf.set(row, record);
+        return record;
+    });
+    // Each main issue's link → its record, "hidden" when it is left out, or null when two
+    // main issues share the link and their duplicates cannot be told apart.
+    const byLink = new Map();
+    if (linkable) {
+        for (const row of mainRows) {
+            const link = (row[ISSUE_LINK_COLUMN] ?? "").trim();
+            if (!link)
+                continue;
+            byLink.set(link, byLink.has(link) ? null : (recordOf.get(row) ?? "hidden"));
+        }
+    }
+    let duplicates = 0;
+    let unlinkedDuplicates = 0;
+    for (const row of duplicateRows) {
+        const main = byLink.get((row[DUPLICATE_COLUMN] ?? "").trim());
+        if (isHidden(row) || main === "hidden")
+            continue;
+        duplicates++;
+        if (main)
+            main.duplicate_count = (main.duplicate_count ?? 0) + 1;
+        else
+            unlinkedDuplicates++;
+    }
     const totalIssues = all.length;
-    // 2) Sort by severity
+    // 3) Sort by severity
     const order = {
         critical: 0,
         serious: 1,
@@ -36,7 +100,7 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
         minor: 3,
     };
     all.sort((a, b) => (order[a.severity] ?? 99) - (order[b.severity] ?? 99));
-    // 3) Walk to the starting offset
+    // 4) Walk to the starting offset
     let charCursor = 0;
     let idx = 0;
     for (; idx < all.length; idx++) {
@@ -45,7 +109,7 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
             break;
         charCursor += len;
     }
-    // 4) Collect up to maxCharacterLength
+    // 5) Collect up to maxCharacterLength
     const page = [];
     for (let i = idx; i < all.length; i++) {
         const recStr = JSON.stringify(all[i]);
@@ -61,5 +125,10 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
         next_page: hasMore ? charCursor : null,
         page_length: pageLength,
         total_issues: totalIssues,
+        duplicate_issues: grouped ? duplicates : null,
+        unlinked_duplicates: unlinkedDuplicates,
+        hidden_issues: columns.includes(STATUS_COLUMN)
+            ? mainRows.length - visibleMainRows.length
+            : null,
     };
 }

package/dist/tools/ask-browserstack/register.js

@@ -406,7 +406,7 @@ export function addAskBrowserStackAITool(server, deps, config) {
     tools.askBrowserStackAI = server.tool("askBrowserStackAI", DESCRIPTION, {
         product: z
             .enum(PRODUCTS)
-            .describe("Which product to work in: tm (Test Management), a11y (Accessibility), " +
+            .describe("Which product to work in: tm (Test Management), " +
             "tra (Test Reporting & Analytics)."),
         // OPTIONAL, because a resume does not carry one. `next_step` tells the model to
         // call again "with exactly these params" — `product`, `run_id`, `perm_id`,

package/dist/tools/ask-browserstack/types.d.ts

@@ -6,7 +6,7 @@
  * different repo, at the same time. A field renamed here to read better is a field the
  * other half will never send. Nothing here changes without changing that document first.
  */
-export declare const PRODUCTS: readonly ["tm", "a11y", "tra"];
+export declare const PRODUCTS: readonly ["tm", "tra"];
 export type Product = (typeof PRODUCTS)[number];
 /** CONTRACT §2 — what Atlas emits on the run's stream when its gate needs a human. */
 export interface PermissionAsk {

package/dist/tools/ask-browserstack/types.js

@@ -6,10 +6,11 @@
  * different repo, at the same time. A field renamed here to read better is a field the
  * other half will never send. Nothing here changes without changing that document first.
  */
-// Dropping a product means this list, the `product` describe text in register.ts, and any
-// handoff in tool-handoff.ts that sends the model here with that product — the two a11y ones
-// do — or those handoffs become instructions to make a call the schema rejects.
-export const PRODUCTS = ["tm", "a11y", "tra"];
+// a11y is deliberately ABSENT while Ask AI is in limited alpha. Atlas itself serves the
+// product; this tool just does not offer it yet. Re-adding it means this list, the `product`
+// describe text in register.ts, and the two a11y handoffs in tool-handoff.ts — which stop
+// pointing here precisely because the call would now be rejected.
+export const PRODUCTS = ["tm", "tra"];
 export const ASK_STATUSES = [
     "ok",
     "blocked",

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

@@ -61,7 +61,10 @@ export declare const NEEDS_BUILD_ID: string;
  * pointing at the agent when a real tool exists is exactly what the header above forbids.
  */
 export declare const NEEDS_SESSION_ID: string;
-/** A completed scan's ids come from startAccessibilityScan, or from the agent. */
+/**
+ * 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: string;
 /** Auth-config ids are not listable by any tool here. */
 export declare const NEEDS_A11Y_CONFIG_ID: string;

package/dist/tools/tool-handoff.js

@@ -70,13 +70,18 @@ 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 completed scan's ids come from startAccessibilityScan, or from the agent. */
-export const NEEDS_A11Y_SCAN_ID = " Requires the ids of a completed scan, which are returned by startAccessibilityScan. " +
-    "No tool here lists past scans; for one run earlier, call askBrowserStackAI with product " +
-    '"a11y" to locate it, or start a new scan rather than guessing.';
+/**
+ * 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 = " 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.";
 /** 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, call askBrowserStackAI with " +
-    'product "a11y" to find it, or create one rather than guessing.';
+    "existing configurations, so if you do not have the id, create one rather than guessing.";
 /** 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.4-beta.1",
+  "version": "2.2.5-beta.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",