@browserstack/mcp-server 1.5.0-beta.21 → 1.5.0-beta.22

package/dist/tools/automate-utils/list-session-ids.js

@@ -1,87 +0,0 @@
-import { SessionType } from "../../lib/constants.js";
-import { getBrowserStackAuth } from "../../lib/get-auth.js";
-import { apiClient } from "../../lib/apiClient.js";
-export const DEFAULT_SESSION_LIST_LIMIT = 10;
-/** The REST session list returned 404: no Automate/App Automate build has this hashed id. */
-export class UnknownBuildError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "UnknownBuildError";
-    }
-}
-export function sessionsListUrl(sessionType, buildId) {
-    const encodedBuildId = encodeURIComponent(buildId);
-    switch (sessionType) {
-        case SessionType.Automate:
-            return `https://api.browserstack.com/automate/builds/${encodedBuildId}/sessions.json`;
-        case SessionType.AppAutomate:
-            return `https://api-cloud.browserstack.com/app-automate/builds/${encodedBuildId}/sessions.json`;
-        default: {
-            const _exhaustive = sessionType;
-            throw new Error(`Unsupported session type: ${_exhaustive}`);
-        }
-    }
-}
-export function mapSessionRecords(payload, statusFilter) {
-    const items = Array.isArray(payload) ? payload : [];
-    const normalizedFilter = statusFilter?.trim().toLowerCase();
-    const records = [];
-    for (const item of items) {
-        const session = item?.automation_session;
-        if (!session) {
-            continue;
-        }
-        const sessionId = session.hashed_id?.trim();
-        if (!sessionId) {
-            continue;
-        }
-        if (normalizedFilter &&
-            (session.status ?? "").toLowerCase() !== normalizedFilter) {
-            continue;
-        }
-        records.push({
-            sessionId,
-            name: session.name,
-            status: session.status,
-            os: session.os,
-            osVersion: session.os_version,
-            browser: session.browser,
-            device: session.device,
-            browserUrl: session.browser_url,
-            videoUrl: session.video_url,
-        });
-    }
-    return records;
-}
-export async function listSessionIds(args, config) {
-    const buildId = args.buildId.trim();
-    if (!buildId) {
-        throw new Error("Hashed Automate/App Automate build ID is required");
-    }
-    const authString = getBrowserStackAuth(config);
-    const auth = Buffer.from(authString).toString("base64");
-    const limit = args.limit ?? DEFAULT_SESSION_LIST_LIMIT;
-    const params = { limit };
-    if (args.offset !== undefined) {
-        params.offset = args.offset;
-    }
-    const response = await apiClient.get({
-        url: sessionsListUrl(args.sessionType, buildId),
-        headers: {
-            "Content-Type": "application/json",
-            Authorization: `Basic ${auth}`,
-        },
-        params,
-        raise_error: false,
-    });
-    if (!response.ok) {
-        if (response.status === 404) {
-            throw new UnknownBuildError(`No ${args.sessionType} build found for id "${buildId}". ` +
-                "Pass the Automate/App Automate dashboard hashed build id or the " +
-                "observability build id from getBuildId / listBuildId, and check that " +
-                "sessionType matches the product the build ran on.");
-        }
-        throw new Error(`Failed to list sessions: ${response.status} ${response.statusText}`);
-    }
-    return mapSessionRecords(response.data, args.status);
-}

package/dist/tools/automate-utils/resolve-hashed-build-id.d.ts

@@ -1,30 +0,0 @@
-import { SessionType } from "../../lib/constants.js";
-import { BrowserStackConfig } from "../../lib/types.js";
-export declare function isObservabilityBuildUuid(id: string): boolean;
-export declare function isHashedBuildId(id: string): boolean;
-export declare function sessionDetailsUrl(sessionType: SessionType, sessionId: string): string;
-/**
- * Resolve the hashed build id that a session belongs to via the Automate /
- * App Automate session detail endpoint. Returns undefined when the session
- * cannot be fetched or does not report a build.
- */
-export declare function resolveBuildIdFromSession(sessionId: string, sessionType: SessionType, config: BrowserStackConfig): Promise<string | undefined>;
-/**
- * Find any BrowserStack session id attached to an observability build by
- * walking its test runs. Returns undefined when no test reports a session
- * (e.g. JUnit-uploaded builds that never ran on BrowserStack).
- */
-export declare function findSessionIdForObservabilityBuild(observabilityBuildId: string, config: BrowserStackConfig): Promise<string | undefined>;
-export interface ResolvedHashedBuildId {
-    hashedBuildId: string;
-    sessionId: string;
-    sessionType: SessionType;
-}
-/**
- * Convert an observability build UUID into the Automate / App Automate hashed
- * build id in two deterministic API calls: pick any session of the build from
- * its test runs, then read `build_hashed_id` from that session's details.
- *
- * When `sessionType` is omitted, Automate is tried first, then App Automate.
- */
-export declare function resolveHashedBuildId(observabilityBuildId: string, config: BrowserStackConfig, sessionType?: SessionType): Promise<ResolvedHashedBuildId>;

package/dist/tools/automate-utils/resolve-hashed-build-id.js

@@ -1,124 +0,0 @@
-import { SessionType } from "../../lib/constants.js";
-import { getBrowserStackAuth } from "../../lib/get-auth.js";
-import { apiClient } from "../../lib/apiClient.js";
-import logger from "../../logger.js";
-import { getAutomationBaseUrl } from "../rca-agent-utils/constants.js";
-import { extractTestIds } from "../rca-agent-utils/get-failed-test-id.js";
-// Observability (Test Reporting & Analytics) build ids are usually UUIDs but
-// some are 40-char hex, the same shape as Automate / App Automate "hashed ids".
-// The two are never interchangeable, and the observability build API does not
-// expose the hashed id. The deterministic bridge is any BrowserStack session that belongs to the
-// build: the session detail endpoint reports its parent `build_hashed_id`.
-const OBSERVABILITY_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const HASHED_BUILD_ID_RE = /^[a-f0-9]{40}$/i;
-// Only the first session id is needed; most builds surface one on page one.
-const MAX_TEST_RUN_PAGES = 5;
-export function isObservabilityBuildUuid(id) {
-    return OBSERVABILITY_UUID_RE.test(id.trim());
-}
-export function isHashedBuildId(id) {
-    return HASHED_BUILD_ID_RE.test(id.trim());
-}
-export function sessionDetailsUrl(sessionType, sessionId) {
-    const encoded = encodeURIComponent(sessionId);
-    switch (sessionType) {
-        case SessionType.Automate:
-            return `https://api.browserstack.com/automate/sessions/${encoded}.json`;
-        case SessionType.AppAutomate:
-            return `https://api.browserstack.com/app-automate/sessions/${encoded}.json`;
-        default: {
-            const _exhaustive = sessionType;
-            throw new Error(`Unsupported session type: ${_exhaustive}`);
-        }
-    }
-}
-/**
- * Resolve the hashed build id that a session belongs to via the Automate /
- * App Automate session detail endpoint. Returns undefined when the session
- * cannot be fetched or does not report a build.
- */
-export async function resolveBuildIdFromSession(sessionId, sessionType, config) {
-    const authString = getBrowserStackAuth(config);
-    const auth = Buffer.from(authString).toString("base64");
-    const response = await apiClient.get({
-        url: sessionDetailsUrl(sessionType, sessionId),
-        headers: {
-            "Content-Type": "application/json",
-            Authorization: `Basic ${auth}`,
-        },
-        raise_error: false,
-    });
-    if (!response.ok) {
-        logger.warn(`Could not resolve build id for ${sessionType} session ${sessionId}: ${response.status}`);
-        return undefined;
-    }
-    const session = response.data?.automation_session;
-    const buildId = session?.build_hashed_id;
-    return typeof buildId === "string" && buildId.trim()
-        ? buildId.trim()
-        : undefined;
-}
-/**
- * Find any BrowserStack session id attached to an observability build by
- * walking its test runs. Returns undefined when no test reports a session
- * (e.g. JUnit-uploaded builds that never ran on BrowserStack).
- */
-export async function findSessionIdForObservabilityBuild(observabilityBuildId, config) {
-    const authString = getBrowserStackAuth(config);
-    const auth = Buffer.from(authString).toString("base64");
-    const baseUrl = `${getAutomationBaseUrl()}/ext/v1/builds/${encodeURIComponent(observabilityBuildId)}/testRuns`;
-    let nextPage;
-    for (let page = 0; page < MAX_TEST_RUN_PAGES; page++) {
-        const response = await apiClient.get({
-            url: baseUrl,
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Basic ${auth}`,
-            },
-            ...(nextPage ? { params: { next_page: nextPage } } : {}),
-            raise_error: false,
-        });
-        if (!response.ok) {
-            throw new Error(`Failed to fetch test runs for observability build "${observabilityBuildId}": ` +
-                `${response.status} ${response.statusText}`);
-        }
-        const data = response.data;
-        const withSession = extractTestIds(data?.hierarchy ?? []).find((test) => test.session_id);
-        if (withSession?.session_id) {
-            return withSession.session_id;
-        }
-        if (!data?.pagination?.has_next || !data.pagination.next_page) {
-            return undefined;
-        }
-        nextPage = data.pagination.next_page;
-    }
-    logger.warn(`resolveHashedBuildId: no session id in first ${MAX_TEST_RUN_PAGES} pages of build ${observabilityBuildId}`);
-    return undefined;
-}
-/**
- * Convert an observability build UUID into the Automate / App Automate hashed
- * build id in two deterministic API calls: pick any session of the build from
- * its test runs, then read `build_hashed_id` from that session's details.
- *
- * When `sessionType` is omitted, Automate is tried first, then App Automate.
- */
-export async function resolveHashedBuildId(observabilityBuildId, config, sessionType) {
-    const buildId = observabilityBuildId.trim();
-    const sessionId = await findSessionIdForObservabilityBuild(buildId, config);
-    if (!sessionId) {
-        throw new Error(`No BrowserStack sessions found for observability build "${buildId}". ` +
-            "Only builds that ran on Automate or App Automate have sessions to list; " +
-            "uploaded-report builds (e.g. JUnit) do not.");
-    }
-    const candidates = sessionType
-        ? [sessionType]
-        : [SessionType.Automate, SessionType.AppAutomate];
-    for (const candidate of candidates) {
-        const hashedBuildId = await resolveBuildIdFromSession(sessionId, candidate, config);
-        if (hashedBuildId) {
-            return { hashedBuildId, sessionId, sessionType: candidate };
-        }
-    }
-    throw new Error(`Could not resolve the hashed build id for observability build "${buildId}" ` +
-        `from session "${sessionId}" (tried: ${candidates.join(", ")}).`);
-}

package/dist/tools/failurelogs-utils/resolve-app-build-id.d.ts

@@ -1,2 +0,0 @@
-import { BrowserStackConfig } from "../../lib/types.js";
-export declare function resolveAppAutomateBuildId(sessionId: string, config: BrowserStackConfig): Promise<string | undefined>;

package/dist/tools/failurelogs-utils/resolve-app-build-id.js

@@ -1,5 +0,0 @@
-import { SessionType } from "../../lib/constants.js";
-import { resolveBuildIdFromSession } from "../automate-utils/resolve-hashed-build-id.js";
-export async function resolveAppAutomateBuildId(sessionId, config) {
-    return resolveBuildIdFromSession(sessionId, SessionType.AppAutomate, config);
-}

package/dist/tools/failurelogs-utils/video.d.ts

@@ -1,3 +0,0 @@
-import { BrowserStackConfig } from "../../lib/types.js";
-import { SessionType } from "../../lib/constants.js";
-export declare function retrieveSessionVideo(sessionId: string, sessionType: SessionType, config: BrowserStackConfig): Promise<string>;

package/dist/tools/failurelogs-utils/video.js

@@ -1,25 +0,0 @@
-import { getBrowserStackAuth } from "../../lib/get-auth.js";
-import { apiClient } from "../../lib/apiClient.js";
-import { SessionType } from "../../lib/constants.js";
-import { validateLogResponse } from "./utils.js";
-export async function retrieveSessionVideo(sessionId, sessionType, config) {
-    const product = sessionType === SessionType.AppAutomate ? "app-automate" : "automate";
-    const url = `https://api.browserstack.com/${product}/sessions/${encodeURIComponent(sessionId)}.json`;
-    const authString = getBrowserStackAuth(config);
-    const auth = Buffer.from(authString).toString("base64");
-    const response = await apiClient.get({
-        url,
-        headers: {
-            "Content-Type": "application/json",
-            Authorization: `Basic ${auth}`,
-        },
-        raise_error: false,
-    });
-    const validationError = validateLogResponse(response, "session video");
-    if (validationError)
-        return validationError.message;
-    const videoUrl = response.data?.automation_session?.video_url;
-    return typeof videoUrl === "string" && videoUrl.trim()
-        ? `Session video: ${videoUrl.trim()}`
-        : "No session video available for this session";
-}

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

@@ -1,66 +0,0 @@
-/**
- * Precondition sentences appended to a tool's description.
- *
- * WHY THESE EXIST. Nothing routes an MCP call: the client's model picks a tool from the
- * descriptions alone. A tool that needs an identifier the caller does not have is a dead
- * end — the model either asks the user for something they also do not know, or gives up.
- * These sentences turn that dead end into a HANDOFF by naming, in the description itself,
- * where the missing identifier comes from.
- *
- * Point at a sibling tool whenever one can produce the id — it is faster and more
- * predictable than an agent. Point at `askBrowserStackAI` only when NO tool here can.
- *
- * The one that matters most: 15 of the 17 Test Management tools require a project
- * identifier and NONE of them accepts its absence, yet no tool in this server lists
- * projects. "List my projects" is the first step of nearly every Test Management journey
- * and it was unserved, which is exactly why that request did not reach any tool unless a
- * user named one explicitly.
- *
- * Keep these as shared constants, not per-tool prose: the wording is a routing signal, and
- * twenty hand-written variants drift into twenty different signals.
- */
-/** No tool lists projects, so this genuinely has to go to the agent. */
-export declare const NEEDS_PROJECT_ID: string;
-/** A sibling tool can produce the id — prefer it over the agent. */
-export declare function needsIdFrom(idLabel: string, sourceTool: string): string;
-/**
- * createProjectOrFolder must NOT carry NEEDS_PROJECT_ID: `project_identifier` is optional
- * there, and the create-a-PROJECT half needs no id at all. With the generic constant the
- * tool read "Requires a project identifier ... call askBrowserStackAI", which routed
- * "create me a project" through the agent before letting the tool run.
- */
-export declare const PROJECT_ID_ONLY_FOR_FOLDER: string;
-/** A test plan id (TP-*) comes from listTestPlans. */
-export declare const NEEDS_TEST_PLAN_ID: string;
-/**
- * The ONLY capability handoff here: every other constant points at a tool that produces a
- * missing *id*, but plan WRITES have no tool at all — the surface is `listTestPlans`,
- * `getTestPlan`, `listSubTestPlans`, `getSubTestPlan` and nothing else. Atlas can do them
- * (the tm harness allows POST /api/v1/projects/{id}/test-plans plus /update, /delete,
- * /clone, /test-runs and /test-runs/unlink), so without this line the model reads the four
- * read tools, finds no create, and reports the capability as absent — which is exactly what
- * a QA eval concluded.
- *
- * Deliberately narrow: it names the specific operations that are missing rather than
- * inviting the model to route plan work to the agent generally, because the tool
- * descriptions otherwise say to prefer a specific tool whenever one fits.
- *
- * Caveat worth knowing: askBrowserStackAI pins every write to human approval, so this path
- * only completes on a client that can show a prompt. On one that cannot, the intended write
- * comes back in `needs_approval` instead of happening.
- */
-export declare const PLAN_WRITES_VIA_AGENT: string;
-/** A build id comes from either build-lookup tool. */
-export declare const NEEDS_BUILD_ID: string;
-/**
- * Session ids ARE listable now — PR #395 added `listSessions`, which merged into main while
- * this branch was open. This used to send the model to askBrowserStackAI for want of a tool;
- * 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. */
-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;
-/** Test ids come from listTestIds, which itself needs a build id. */
-export declare const NEEDS_TEST_IDS: string;

package/dist/tools/tool-handoff.js

@@ -1,78 +0,0 @@
-/**
- * Precondition sentences appended to a tool's description.
- *
- * WHY THESE EXIST. Nothing routes an MCP call: the client's model picks a tool from the
- * descriptions alone. A tool that needs an identifier the caller does not have is a dead
- * end — the model either asks the user for something they also do not know, or gives up.
- * These sentences turn that dead end into a HANDOFF by naming, in the description itself,
- * where the missing identifier comes from.
- *
- * Point at a sibling tool whenever one can produce the id — it is faster and more
- * predictable than an agent. Point at `askBrowserStackAI` only when NO tool here can.
- *
- * The one that matters most: 15 of the 17 Test Management tools require a project
- * identifier and NONE of them accepts its absence, yet no tool in this server lists
- * projects. "List my projects" is the first step of nearly every Test Management journey
- * and it was unserved, which is exactly why that request did not reach any tool unless a
- * user named one explicitly.
- *
- * Keep these as shared constants, not per-tool prose: the wording is a routing signal, and
- * twenty hand-written variants drift into twenty different signals.
- */
-/** No tool lists projects, so this genuinely has to go to the agent. */
-export const NEEDS_PROJECT_ID = " Requires a project identifier (PR-*). No tool here lists projects, so if you do not " +
-    'have one, call askBrowserStackAI with product "tm" and ask which projects exist, then ' +
-    "retry this tool with the identifier it returns.";
-/** A sibling tool can produce the id — prefer it over the agent. */
-export function needsIdFrom(idLabel, sourceTool) {
-    return ` Requires ${idLabel}. Call ${sourceTool} first if you do not have it.`;
-}
-/**
- * createProjectOrFolder must NOT carry NEEDS_PROJECT_ID: `project_identifier` is optional
- * there, and the create-a-PROJECT half needs no id at all. With the generic constant the
- * tool read "Requires a project identifier ... call askBrowserStackAI", which routed
- * "create me a project" through the agent before letting the tool run.
- */
-export const PROJECT_ID_ONLY_FOR_FOLDER = " Creating a project needs no identifier. Creating a folder inside an EXISTING project " +
-    "needs that project's identifier (PR-*); no tool here lists projects, so ask " +
-    'askBrowserStackAI with product "tm" for it.';
-/** A test plan id (TP-*) comes from listTestPlans. */
-export const NEEDS_TEST_PLAN_ID = needsIdFrom("a test plan identifier (TP-*)", "listTestPlans");
-/**
- * The ONLY capability handoff here: every other constant points at a tool that produces a
- * missing *id*, but plan WRITES have no tool at all — the surface is `listTestPlans`,
- * `getTestPlan`, `listSubTestPlans`, `getSubTestPlan` and nothing else. Atlas can do them
- * (the tm harness allows POST /api/v1/projects/{id}/test-plans plus /update, /delete,
- * /clone, /test-runs and /test-runs/unlink), so without this line the model reads the four
- * read tools, finds no create, and reports the capability as absent — which is exactly what
- * a QA eval concluded.
- *
- * Deliberately narrow: it names the specific operations that are missing rather than
- * inviting the model to route plan work to the agent generally, because the tool
- * descriptions otherwise say to prefer a specific tool whenever one fits.
- *
- * Caveat worth knowing: askBrowserStackAI pins every write to human approval, so this path
- * only completes on a client that can show a prompt. On one that cannot, the intended write
- * comes back in `needs_approval` instead of happening.
- */
-export const PLAN_WRITES_VIA_AGENT = " Creating a test plan or sub-plan, and linking or unlinking test runs on one, are not " +
-    'available as tools here: call askBrowserStackAI with product "tm" and describe what you ' +
-    "want. It asks you to confirm before changing anything.";
-/** A build id comes from either build-lookup tool. */
-export const NEEDS_BUILD_ID = needsIdFrom("a BrowserStack build id", "getBuildId or listBuildId");
-/**
- * Session ids ARE listable now — PR #395 added `listSessions`, which merged into main while
- * this branch was open. This used to send the model to askBrowserStackAI for want of a tool;
- * pointing at the agent when a real tool exists is exactly what the header above forbids.
- */
-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, so if you do not have the ids, 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, 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");