@browserstack/mcp-server 1.0.10 → 1.0.12

package/dist/tools/live-utils/version-resolver.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVersion = resolveVersion;
+/**
+ * If req === "latest" or "oldest", returns max/min numeric (or lex)
+ * Else if exact match, returns that
+ * Else picks the numerically closest (or first)
+ */
+function resolveVersion(requested, available) {
+    // strip duplicates & sort
+    const uniq = Array.from(new Set(available));
+    // pick min/max
+    if (requested === "latest" || requested === "oldest") {
+        // try numeric
+        const nums = uniq
+            .map((v) => ({ v, n: parseFloat(v) }))
+            .filter((x) => !isNaN(x.n))
+            .sort((a, b) => a.n - b.n);
+        if (nums.length) {
+            return requested === "latest" ? nums[nums.length - 1].v : nums[0].v;
+        }
+        // fallback lex
+        const lex = uniq.slice().sort();
+        return requested === "latest" ? lex[lex.length - 1] : lex[0];
+    }
+    // exact?
+    if (uniq.includes(requested)) {
+        return requested;
+    }
+    // try closest numeric
+    const reqNum = parseFloat(requested);
+    const nums = uniq
+        .map((v) => ({ v, n: parseFloat(v) }))
+        .filter((x) => !isNaN(x.n));
+    if (!isNaN(reqNum) && nums.length) {
+        let best = nums[0], bestDiff = Math.abs(nums[0].n - reqNum);
+        for (const x of nums) {
+            const d = Math.abs(x.n - reqNum);
+            if (d < bestDiff) {
+                best = x;
+                bestDiff = d;
+            }
+        }
+        return best.v;
+    }
+    // final fallback
+    return uniq[0];
+}

package/dist/tools/live.js

@@ -3,90 +3,99 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startBrowserLiveSession = startBrowserLiveSession;
 exports.default = addBrowserLiveTools;
 const zod_1 = require("zod");
-const start_session_1 = require("./live-utils/start-session");
 const logger_1 = __importDefault(require("../logger"));
-const local_1 = require("../lib/local");
+const start_session_1 = require("./live-utils/start-session");
+const types_1 = require("./live-utils/types");
+const instrumentation_1 = require("../lib/instrumentation");
+// Define the schema shape
+const LiveArgsShape = {
+    platformType: zod_1.z
+        .nativeEnum(types_1.PlatformType)
+        .describe("Must be 'desktop' or 'mobile'"),
+    desiredURL: zod_1.z.string().url().describe("The URL to test"),
+    desiredOS: zod_1.z
+        .enum(["Windows", "OS X", "android", "ios", "winphone"])
+        .describe("Desktop OS ('Windows' or 'OS X') or mobile OS ('android','ios','winphone')"),
+    desiredOSVersion: zod_1.z
+        .string()
+        .describe("The OS version must be specified as a version number (e.g., '10', '14.0') or as a keyword such as 'latest' or 'oldest'. Normalize variations like 'newest' or 'most recent' to 'latest', and terms like 'earliest' or 'first' to 'oldest'. For macOS, version names (e.g., 'Sequoia') must be used instead of numeric versions."),
+    desiredBrowser: zod_1.z
+        .enum(["chrome", "firefox", "safari", "edge", "ie"])
+        .describe("Browser for desktop (Chrome, IE, Firefox, Safari, Edge)"),
+    desiredBrowserVersion: zod_1.z
+        .string()
+        .optional()
+        .describe("Browser version for desktop (e.g. '133.2', 'latest'). If the user says 'latest', 'newest', or similar, normalize it to 'latest'. Likewise, convert terms like 'earliest' or 'oldest' to 'oldest'."),
+    desiredDevice: zod_1.z.string().optional().describe("Device name for mobile"),
+};
+const LiveArgsSchema = zod_1.z.object(LiveArgsShape);
 /**
- * Launches a Browser Live Session on BrowserStack.
+ * Launches a desktop browser session
  */
-async function startBrowserLiveSession(args) {
-    if (!args.desiredBrowser) {
-        throw new Error("You must provide a desiredBrowser.");
-    }
-    if (!args.desiredURL) {
-        throw new Error("You must provide a desiredURL.");
-    }
-    if (!args.desiredOS) {
-        throw new Error("You must provide a desiredOS.");
-    }
-    if (!args.desiredOSVersion) {
-        throw new Error("You must provide a desiredOSVersion.");
-    }
-    if (!args.desiredBrowserVersion) {
-        throw new Error("You must provide a desiredBrowserVersion.");
-    }
-    // Validate URL format
-    try {
-        new URL(args.desiredURL);
-    }
-    catch (error) {
-        logger_1.default.error("Invalid URL format: %s", error);
-        throw new Error("The provided URL is invalid.");
-    }
-    const isLocal = (0, local_1.isLocalURL)(args.desiredURL);
-    if (isLocal) {
-        await (0, local_1.ensureLocalBinarySetup)();
-    }
-    else {
-        await (0, local_1.killExistingBrowserStackLocalProcesses)();
-    }
-    const launchUrl = await (0, start_session_1.startBrowserSession)({
-        browser: args.desiredBrowser,
+async function launchDesktopSession(args) {
+    if (!args.desiredBrowser)
+        throw new Error("You must provide a desiredBrowser");
+    if (!args.desiredBrowserVersion)
+        throw new Error("You must provide a desiredBrowserVersion");
+    return (0, start_session_1.startBrowserSession)({
+        platformType: types_1.PlatformType.DESKTOP,
+        url: args.desiredURL,
         os: args.desiredOS,
         osVersion: args.desiredOSVersion,
-        url: args.desiredURL,
+        browser: args.desiredBrowser,
         browserVersion: args.desiredBrowserVersion,
-        isLocal,
     });
+}
+/**
+ * Launches a mobile browser session
+ */
+async function launchMobileSession(args) {
+    if (!args.desiredDevice)
+        throw new Error("You must provide a desiredDevice");
+    return (0, start_session_1.startBrowserSession)({
+        platformType: types_1.PlatformType.MOBILE,
+        browser: args.desiredBrowser,
+        url: args.desiredURL,
+        os: args.desiredOS,
+        osVersion: args.desiredOSVersion,
+        device: args.desiredDevice,
+    });
+}
+/**
+ * Handles the core logic for running a browser session
+ */
+async function runBrowserSession(rawArgs) {
+    // Validate and narrow
+    const args = LiveArgsSchema.parse(rawArgs);
+    // Branch desktop vs mobile and delegate
+    const launchUrl = args.platformType === types_1.PlatformType.DESKTOP
+        ? await launchDesktopSession(args)
+        : await launchMobileSession(args);
     return {
         content: [
             {
                 type: "text",
-                text: `Successfully started a browser session. If a browser window did not open automatically, use the following URL to start the session: ${launchUrl}`,
+                text: `✅ Session started. If it didn't open automatically, visit:\n${launchUrl}`,
             },
         ],
     };
 }
 function addBrowserLiveTools(server) {
-    server.tool("runBrowserLiveSession", "Use this tool when user wants to manually check their website on a particular browser and OS combination using BrowserStack's cloud infrastructure. Can be used to debug layout issues, compatibility problems, etc.", {
-        desiredBrowser: zod_1.z
-            .enum(["Chrome", "IE", "Firefox", "Safari", "Edge"])
-            .describe("The browser to run the test on. Example: 'Chrome', 'IE', 'Safari', 'Edge'. Always ask the user for the browser they want to use, do not assume it."),
-        desiredOSVersion: zod_1.z
-            .string()
-            .describe("The OS version to run the browser on. Example: '10' for Windows, '12' for macOS, '14' for iOS"),
-        desiredOS: zod_1.z
-            .enum(["Windows", "OS X"])
-            .describe("The operating system to run the browser on. Example: 'Windows', 'OS X'"),
-        desiredURL: zod_1.z
-            .string()
-            .describe("The URL of the website to test. This can be a local URL (e.g., http://localhost:3000) or a public URL. Always ask the user for the URL, do not assume it."),
-        desiredBrowserVersion: zod_1.z
-            .string()
-            .describe("The version of the browser to use. Example: 133.0, 134.0, 87.0"),
-    }, async (args) => {
+    server.tool("runBrowserLiveSession", "Launch a BrowserStack Live session (desktop or mobile).", LiveArgsShape, async (args) => {
         try {
-            return startBrowserLiveSession(args);
+            (0, instrumentation_1.trackMCP)("runBrowserLiveSession", server.server.getClientVersion());
+            return await runBrowserSession(args);
         }
         catch (error) {
+            logger_1.default.error("Live session failed: %s", error);
+            (0, instrumentation_1.trackMCP)("runBrowserLiveSession", server.server.getClientVersion(), error);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Failed to start a browser live session. Error: ${error}. Please open an issue on GitHub if the problem persists`,
+                        text: `Failed to start a browser live session. Error: ${error}`,
                         isError: true,
                     },
                 ],

package/dist/tools/observability.js

@@ -1,9 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFailuresInLastRun = getFailuresInLastRun;
 exports.default = addObservabilityTools;
 const zod_1 = require("zod");
 const api_1 = require("../lib/api");
+const instrumentation_1 = require("../lib/instrumentation");
+const logger_1 = __importDefault(require("../logger"));
 async function getFailuresInLastRun(buildName, projectName) {
     const buildsData = await (0, api_1.getLatestO11YBuildInfo)(buildName, projectName);
     const observabilityUrl = buildsData.observability_url;
@@ -40,9 +45,12 @@ function addObservabilityTools(server) {
             .describe("Name of the project to get failures for. This is the 'projectName' key in the browserstack.yml file. If not sure, ask the user for the project name."),
     }, async (args) => {
         try {
-            return getFailuresInLastRun(args.buildName, args.projectName);
+            (0, instrumentation_1.trackMCP)("getFailuresInLastRun", server.server.getClientVersion());
+            return await getFailuresInLastRun(args.buildName, args.projectName);
         }
         catch (error) {
+            logger_1.default.error("Failed to get failures in the last run: %s", error);
+            (0, instrumentation_1.trackMCP)("getFailuresInLastRun", server.server.getClientVersion(), error);
             return {
                 content: [
                     {

package/dist/tools/testmanagement-utils/create-testrun.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateTestRunSchema = void 0;
+exports.createTestRun = createTestRun;
+const axios_1 = __importDefault(require("axios"));
+const config_1 = __importDefault(require("../../config"));
+const zod_1 = require("zod");
+const error_1 = require("../../lib/error");
+/**
+ * Schema for creating a test run.
+ */
+exports.CreateTestRunSchema = zod_1.z.object({
+    project_identifier: zod_1.z
+        .string()
+        .describe("Identifier of the project in which to create the test run."),
+    test_run: zod_1.z.object({
+        name: zod_1.z.string().describe("Name of the test run"),
+        description: zod_1.z
+            .string()
+            .optional()
+            .describe("Brief information about the test run"),
+        run_state: zod_1.z
+            .enum([
+            "new_run",
+            "in_progress",
+            "under_review",
+            "rejected",
+            "done",
+            "closed",
+        ])
+            .optional()
+            .describe("State of the test run. One of new_run, in_progress, under_review, rejected, done, closed"),
+        issues: zod_1.z.array(zod_1.z.string()).optional().describe("Linked issue IDs"),
+        issue_tracker: zod_1.z
+            .object({ name: zod_1.z.string(), host: zod_1.z.string().url() })
+            .optional()
+            .describe("Issue tracker configuration"),
+        test_cases: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("List of test case IDs"),
+        folder_ids: zod_1.z
+            .array(zod_1.z.number())
+            .optional()
+            .describe("Folder IDs to include"),
+    }),
+});
+/**
+ * Creates a test run via BrowserStack Test Management API.
+ */
+async function createTestRun(rawArgs) {
+    try {
+        const inputArgs = {
+            ...rawArgs,
+            test_run: {
+                ...rawArgs.test_run,
+                include_all: false,
+            },
+        };
+        const args = exports.CreateTestRunSchema.parse(inputArgs);
+        const url = `https://test-management.browserstack.com/api/v2/projects/${encodeURIComponent(args.project_identifier)}/test-runs`;
+        const response = await axios_1.default.post(url, { test_run: args.test_run }, {
+            auth: {
+                username: config_1.default.browserstackUsername,
+                password: config_1.default.browserstackAccessKey,
+            },
+            headers: { "Content-Type": "application/json" },
+        });
+        const data = response.data;
+        if (!data.success) {
+            throw new Error(`API returned unsuccessful response: ${JSON.stringify(data)}`);
+        }
+        // Assume data.test_run contains created run info
+        const created = data.test_run || data;
+        const runId = created.identifier || created.id || created.name;
+        const summary = `Successfully created test run ${runId}`;
+        return {
+            content: [
+                { type: "text", text: summary },
+                { type: "text", text: JSON.stringify(created, null, 2) },
+            ],
+        };
+    }
+    catch (err) {
+        return (0, error_1.formatAxiosError)(err, "Failed to create test run");
+    }
+}

package/dist/tools/testmanagement-utils/list-testcases.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListTestCasesSchema = void 0;
+exports.listTestCases = listTestCases;
+const axios_1 = __importDefault(require("axios"));
+const config_1 = __importDefault(require("../../config"));
+const zod_1 = require("zod");
+const error_1 = require("../../lib/error");
+/**
+ * Schema for listing test cases with optional filters.
+ */
+exports.ListTestCasesSchema = zod_1.z.object({
+    project_identifier: zod_1.z
+        .string()
+        .describe("Identifier of the project to fetch test cases from.  Example: PR-12345"),
+    folder_id: zod_1.z
+        .string()
+        .optional()
+        .describe("If provided, only return cases in this folder."),
+    case_type: zod_1.z
+        .string()
+        .optional()
+        .describe("Comma-separated list of case types (e.g. functional,regression)."),
+    priority: zod_1.z
+        .string()
+        .optional()
+        .describe("Comma-separated list of priorities (e.g. critical,medium,low)."),
+    p: zod_1.z.number().optional().describe("Page number."),
+});
+/**
+ * Calls BrowserStack Test Management to list test cases with filters.
+ */
+async function listTestCases(args) {
+    try {
+        // Build query string
+        const params = new URLSearchParams();
+        if (args.folder_id)
+            params.append("folder_id", args.folder_id);
+        if (args.case_type)
+            params.append("case_type", args.case_type);
+        if (args.priority)
+            params.append("priority", args.priority);
+        if (args.p !== undefined)
+            params.append("p", args.p.toString());
+        const url = `https://test-management.browserstack.com/api/v2/projects/${encodeURIComponent(args.project_identifier)}/test-cases?${params.toString()}`;
+        const resp = await axios_1.default.get(url, {
+            auth: {
+                username: config_1.default.browserstackUsername,
+                password: config_1.default.browserstackAccessKey,
+            },
+        });
+        const resp_data = resp.data;
+        if (!resp_data.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to list test cases: ${JSON.stringify(resp_data)}`,
+                        isError: true,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { test_cases, info } = resp_data;
+        const count = info?.count ?? test_cases.length;
+        // Summary for more focused output
+        const summary = test_cases
+            .map((tc) => `• ${tc.identifier}: ${tc.title} [${tc.case_type} | ${tc.priority}]`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${count} test case(s):\n\n${summary}`,
+                },
+                {
+                    type: "text",
+                    text: JSON.stringify(test_cases, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return (0, error_1.formatAxiosError)(err, "Failed to list test cases");
+    }
+}

package/dist/tools/testmanagement-utils/list-testruns.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListTestRunsSchema = void 0;
+exports.listTestRuns = listTestRuns;
+const axios_1 = __importDefault(require("axios"));
+const config_1 = __importDefault(require("../../config"));
+const zod_1 = require("zod");
+const error_1 = require("../../lib/error");
+/**
+ * Schema for listing test runs with optional filters.
+ */
+exports.ListTestRunsSchema = zod_1.z.object({
+    project_identifier: zod_1.z
+        .string()
+        .describe("Identifier of the project to fetch test runs from (e.g., PR-12345)"),
+    run_state: zod_1.z
+        .string()
+        .optional()
+        .describe("Return all test runs with this state (comma-separated)"),
+});
+/**
+ * Fetches and formats the list of test runs for a project.
+ */
+async function listTestRuns(args) {
+    try {
+        const params = new URLSearchParams();
+        if (args.run_state) {
+            params.set("run_state", args.run_state);
+        }
+        const url = `https://test-management.browserstack.com/api/v2/projects/${encodeURIComponent(args.project_identifier)}/test-runs?` + params.toString();
+        const resp = await axios_1.default.get(url, {
+            auth: {
+                username: config_1.default.browserstackUsername,
+                password: config_1.default.browserstackAccessKey,
+            },
+        });
+        const data = resp.data;
+        if (!data.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to list test runs: ${JSON.stringify(data)}`,
+                        isError: true,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const runs = data.test_runs;
+        const count = runs.length;
+        const summary = runs
+            .map((tr) => `• ${tr.identifier}: ${tr.name} [${tr.run_state}]`)
+            .join("\n");
+        return {
+            content: [
+                { type: "text", text: `Found ${count} test run(s):\n\n${summary}` },
+                { type: "text", text: JSON.stringify(runs, null, 2) },
+            ],
+        };
+    }
+    catch (err) {
+        return (0, error_1.formatAxiosError)(err, "Failed to list test runs");
+    }
+}

package/dist/tools/testmanagement-utils/update-testrun.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateTestRunSchema = void 0;
+exports.updateTestRun = updateTestRun;
+const axios_1 = __importDefault(require("axios"));
+const config_1 = __importDefault(require("../../config"));
+const zod_1 = require("zod");
+const error_1 = require("../../lib/error");
+/**
+ * Schema for updating a test run with partial fields.
+ */
+exports.UpdateTestRunSchema = zod_1.z.object({
+    project_identifier: zod_1.z
+        .string()
+        .describe("Project identifier (e.g., PR-12345)"),
+    test_run_id: zod_1.z.string().describe("Test run identifier (e.g., TR-678)"),
+    test_run: zod_1.z.object({
+        name: zod_1.z.string().optional().describe("New name of the test run"),
+        run_state: zod_1.z
+            .enum([
+            "new_run",
+            "in_progress",
+            "under_review",
+            "rejected",
+            "done",
+            "closed",
+        ])
+            .optional()
+            .describe("Updated state of the test run"),
+    }),
+});
+/**
+ * Partially updates an existing test run.
+ */
+async function updateTestRun(args) {
+    try {
+        const body = { test_run: args.test_run };
+        const url = `https://test-management.browserstack.com/api/v2/projects/${encodeURIComponent(args.project_identifier)}/test-runs/${encodeURIComponent(args.test_run_id)}/update`;
+        const resp = await axios_1.default.patch(url, body, {
+            auth: {
+                username: config_1.default.browserstackUsername,
+                password: config_1.default.browserstackAccessKey,
+            },
+        });
+        const data = resp.data;
+        if (!data.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to update test run: ${JSON.stringify(data)}`,
+                        isError: true,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Successfully updated test run ${args.test_run_id}`,
+                },
+                { type: "text", text: JSON.stringify(data.testrun || data, null, 2) },
+            ],
+        };
+    }
+    catch (err) {
+        return (0, error_1.formatAxiosError)(err, "Failed to update test run");
+    }
+}