@browserstack/mcp-server 1.2.15-beta.2 → 1.2.16

package/dist/tools/testmanagement.js

@@ -4,6 +4,7 @@ import { createProjectOrFolder, CreateProjFoldSchema, } from "./testmanagement-u
 import { createTestCase as createTestCaseAPI, sanitizeArgs, CreateTestCaseSchema, } from "./testmanagement-utils/create-testcase.js";
 import { updateTestCase as updateTestCaseAPI, UpdateTestCaseSchema, } from "./testmanagement-utils/update-testcase.js";
 import { listTestCases, ListTestCasesSchema, } from "./testmanagement-utils/list-testcases.js";
+import { listFolders, ListFoldersSchema, } from "./testmanagement-utils/list-folders.js";
 import { CreateTestRunSchema, createTestRun, } from "./testmanagement-utils/create-testrun.js";
 import { ListTestRunsSchema, listTestRuns, } from "./testmanagement-utils/list-testruns.js";
 import { UpdateTestRunSchema, updateTestRun, } from "./testmanagement-utils/update-testrun.js";
@@ -12,6 +13,8 @@ import { UploadFileSchema, uploadFile, } from "./testmanagement-utils/upload-fil
 import { createTestCasesFromFile } from "./testmanagement-utils/testcase-from-file.js";
 import { CreateTestCasesFromFileSchema } from "./testmanagement-utils/TCG-utils/types.js";
 import { createLCASteps, CreateLCAStepsSchema, } from "./testmanagement-utils/create-lca-steps.js";
+import { listTestPlans, ListTestPlansSchema, } from "./testmanagement-utils/list-testplans.js";
+import { getTestPlan, GetTestPlanSchema, } from "./testmanagement-utils/get-testplan.js";
 //TODO: Moving the traceMCP and catch block to the parent(server) function
 /**
  * Wrapper to call createProjectOrFolder util.
@@ -102,6 +105,27 @@ export async function listTestCasesTool(args, config, server) {
         };
     }
 }
+/**
+ * Lists folders in a project (or sub-folders under a parent folder).
+ */
+export async function listFoldersTool(args, config, server) {
+    try {
+        trackMCP("listFolders", server.server.getClientVersion(), undefined, config);
+        return await listFolders(args, config);
+    }
+    catch (err) {
+        trackMCP("listFolders", server.server.getClientVersion(), err, config);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to list folders: ${err instanceof Error ? err.message : "Unknown error"}. Please open an issue on GitHub if the problem persists`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
 /**
  * Creates a test run in BrowserStack Test Management.
  */
@@ -251,6 +275,50 @@ export async function createLCAStepsTool(args, context, config, server) {
         };
     }
 }
+/**
+ * Lists test plans in a project.
+ */
+export async function listTestPlansTool(args, config, server) {
+    try {
+        trackMCP("listTestPlans", server.server.getClientVersion(), undefined, config);
+        return await listTestPlans(args, config);
+    }
+    catch (err) {
+        logger.error("Failed to list test plans: %s", err);
+        trackMCP("listTestPlans", server.server.getClientVersion(), err, config);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to list test plans: ${err instanceof Error ? err.message : "Unknown error"}. Please open an issue on GitHub if the problem persists`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Fetches a test plan by identifier, with its linked runs and a derived status summary.
+ */
+export async function getTestPlanTool(args, config, server) {
+    try {
+        trackMCP("getTestPlan", server.server.getClientVersion(), undefined, config);
+        return await getTestPlan(args, config);
+    }
+    catch (err) {
+        logger.error("Failed to fetch test plan: %s", err);
+        trackMCP("getTestPlan", server.server.getClientVersion(), err, config);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to fetch test plan: ${err instanceof Error ? err.message : "Unknown error"}. Please open an issue on GitHub if the problem persists`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
 /**
  * Registers both project/folder and test-case tools.
  */
@@ -258,8 +326,9 @@ export default function addTestManagementTools(server, config) {
     const tools = {};
     tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management.", CreateProjFoldSchema.shape, (args) => createProjectOrFolderTool(args, config, server));
     tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", CreateTestCaseSchema.shape, (args) => createTestCaseTool(args, config, server));
-    tools.updateTestCase = server.tool("updateTestCase", "Use this tool to update an existing test case in BrowserStack Test Management. Allows editing test case details like name, description, steps, owner, priority, and more.", UpdateTestCaseSchema.shape, (args) => updateTestCaseTool(args, config, server));
-    tools.listTestCases = server.tool("listTestCases", "List test cases in a project with optional filters (status, priority, custom fields, etc.)", ListTestCasesSchema.shape, (args) => listTestCasesTool(args, config, server));
+    tools.updateTestCase = server.tool("updateTestCase", "Update an existing test case in BrowserStack Test Management. Any subset of the following fields may be changed: name, description, preconditions, test_case_steps, owner, priority, case_type, automation_status, status, tags, issues, custom_fields. Only the supplied fields are modified.", UpdateTestCaseSchema.shape, (args) => updateTestCaseTool(args, config, server));
+    tools.listTestCases = server.tool("listTestCases", "List test cases in a project, optionally scoped to a specific folder. Omit folder_id to list all test cases in the project; provide folder_id (discoverable via listFolders) to list only that folder's cases. Supports filters: case_type, priority, pagination.", ListTestCasesSchema.shape, (args) => listTestCasesTool(args, config, server));
+    tools.listFolders = server.tool("listFolders", "List folders in a BrowserStack Test Management project, returning each folder's id and name (plus case counts and sub-folder counts). Pass parent_id to list sub-folders under a specific folder instead of top-level folders.", ListFoldersSchema.shape, (args) => listFoldersTool(args, config, server));
     tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management.", CreateTestRunSchema.shape, (args) => createTestRunTool(args, config, server));
     tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)", ListTestRunsSchema.shape, (args) => listTestRunsTool(args, config, server));
     tools.updateTestRun = server.tool("updateTestRun", "Update a test run in BrowserStack Test Management.", UpdateTestRunSchema.shape, (args) => updateTestRunTool(args, config, server));
@@ -267,5 +336,7 @@ export default function addTestManagementTools(server, config) {
     tools.uploadProductRequirementFile = server.tool("uploadProductRequirementFile", "Upload files (e.g., PDRs, PDFs) to BrowserStack Test Management and retrieve a file mapping ID. This is utilized for generating test cases from files and is part of the Test Case Generator AI Agent in BrowserStack.", UploadFileSchema.shape, (args) => uploadProductRequirementFileTool(args, config, server));
     tools.createTestCasesFromFile = server.tool("createTestCasesFromFile", "Generate test cases from a file in BrowserStack Test Management using the Test Case Generator AI Agent.", CreateTestCasesFromFileSchema.shape, (args, context) => createTestCasesFromFileTool(args, context, config, server));
     tools.createLCASteps = server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case in BrowserStack Test Management using the Low Code Automation Agent.", CreateLCAStepsSchema.shape, (args, context) => createLCAStepsTool(args, context, config, server));
+    tools.listTestPlans = server.tool("listTestPlans", "List test plans in a BrowserStack Test Management project. Returns each plan's identifier (TP-*), name, status, description, dates, and active/closed test-run counts. Supports pagination.", ListTestPlansSchema.shape, (args) => listTestPlansTool(args, config, server));
+    tools.getTestPlan = server.tool("getTestPlan", "Fetch a test plan by identifier (TP-*) from BrowserStack Test Management. Returns plan metadata, the full list of linked test runs, total test-case count across runs, and a status summary — suitable for generating test documentation or QA status reports.", GetTestPlanSchema.shape, (args) => getTestPlanTool(args, config, server));
     return tools;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.2.15-beta.2",
+  "version": "1.2.16",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",
@@ -15,8 +15,7 @@
     "dev": "tsx watch --clear-screen=false src/index.ts",
     "test": "vitest run",
     "lint": "eslint . --ext .ts",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "generate-app-samples": "node scripts/generate-app-samples.mjs"
+    "format": "prettier --write \"src/**/*.ts\""
   },
   "bin": {
     "browserstack-mcp-server": "dist/index.js"

package/dist/lib/percy-api/auth.d.ts

@@ -1,41 +0,0 @@
-/**
- * Percy API authentication module.
- * Resolves Percy tokens via environment variables or BrowserStack credential fallback.
- *
- * SECURITY: Token values are NEVER logged or included in error messages.
- * Masked format (****<last4>) is used when referencing tokens in diagnostics.
- */
-import { BrowserStackConfig } from "../types.js";
-type TokenScope = "project" | "org" | "auto";
-interface ResolveTokenOptions {
-    projectName?: string;
-    scope?: TokenScope;
-}
-/**
- * Masks a token for safe display in error messages.
- * Shows only the last 4 characters.
- */
-export declare function maskToken(token: string): string;
-/**
- * Resolves a Percy token using the following priority:
- *
- * 1. `process.env.PERCY_TOKEN` (for project or auto scope)
- * 2. `process.env.PERCY_ORG_TOKEN` (for org scope)
- * 3. Fallback: fetch via BrowserStack API using `fetchPercyToken()`
- * 4. If nothing works, throws an enriched error with guidance
- */
-export declare function resolvePercyToken(config: BrowserStackConfig, options?: ResolveTokenOptions): Promise<string>;
-/**
- * Returns headers for Percy API requests.
- * Includes Authorization, Content-Type, and User-Agent.
- */
-export declare function getPercyHeaders(config: BrowserStackConfig, options?: {
-    scope?: TokenScope;
-    projectName?: string;
-}): Promise<Record<string, string>>;
-/**
- * Returns the Percy API base URL.
- * Defaults to `https://percy.io/api/v1`, overridable via `PERCY_API_URL` env var.
- */
-export declare function getPercyApiBaseUrl(): string;
-export {};

package/dist/lib/percy-api/auth.js

@@ -1,96 +0,0 @@
-/**
- * Percy API authentication module.
- * Resolves Percy tokens via environment variables or BrowserStack credential fallback.
- *
- * SECURITY: Token values are NEVER logged or included in error messages.
- * Masked format (****<last4>) is used when referencing tokens in diagnostics.
- */
-import { fetchPercyToken } from "../../tools/sdk-utils/percy-web/fetchPercyToken.js";
-/**
- * Masks a token for safe display in error messages.
- * Shows only the last 4 characters.
- */
-export function maskToken(token) {
-    if (token.length <= 4) {
-        return "****";
-    }
-    return `****${token.slice(-4)}`;
-}
-/**
- * Resolves a Percy token using the following priority:
- *
- * 1. `process.env.PERCY_TOKEN` (for project or auto scope)
- * 2. `process.env.PERCY_ORG_TOKEN` (for org scope)
- * 3. Fallback: fetch via BrowserStack API using `fetchPercyToken()`
- * 4. If nothing works, throws an enriched error with guidance
- */
-export async function resolvePercyToken(config, options = {}) {
-    const { projectName, scope = "auto" } = options;
-    // For project or auto scope, check PERCY_TOKEN first
-    if (scope === "project" || scope === "auto") {
-        const envToken = process.env.PERCY_TOKEN;
-        if (envToken) {
-            return envToken;
-        }
-    }
-    // For org scope, check PERCY_ORG_TOKEN
-    if (scope === "org") {
-        const orgToken = process.env.PERCY_ORG_TOKEN;
-        if (orgToken) {
-            return orgToken;
-        }
-    }
-    // For auto scope, also check PERCY_ORG_TOKEN as secondary
-    if (scope === "auto") {
-        const orgToken = process.env.PERCY_ORG_TOKEN;
-        if (orgToken) {
-            return orgToken;
-        }
-    }
-    // Fallback: fetch via BrowserStack credentials
-    const username = config["browserstack-username"];
-    const accessKey = config["browserstack-access-key"];
-    if (username && accessKey) {
-        const auth = `${username}:${accessKey}`;
-        const resolvedProjectName = projectName || "default";
-        try {
-            const token = await fetchPercyToken(resolvedProjectName, auth, {});
-            return token;
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to fetch Percy token via BrowserStack API: ${message}. ` +
-                `Set PERCY_TOKEN or PERCY_ORG_TOKEN environment variable as an alternative.`);
-        }
-    }
-    // Nothing worked — provide actionable guidance
-    if (scope === "project") {
-        throw new Error("Percy project token not available. Set PERCY_TOKEN environment variable, " +
-            "or provide BrowserStack credentials to fetch a token automatically.");
-    }
-    if (scope === "org") {
-        throw new Error("Percy org token not available. Set PERCY_ORG_TOKEN environment variable.");
-    }
-    throw new Error("Percy token not available. Set PERCY_TOKEN (project) or PERCY_ORG_TOKEN (org) " +
-        "environment variable, or provide BrowserStack credentials (browserstack-username " +
-        "and browserstack-access-key) to fetch a token automatically.");
-}
-/**
- * Returns headers for Percy API requests.
- * Includes Authorization, Content-Type, and User-Agent.
- */
-export async function getPercyHeaders(config, options = {}) {
-    const token = await resolvePercyToken(config, options);
-    return {
-        Authorization: `Token token=${token}`,
-        "Content-Type": "application/json",
-        "User-Agent": "browserstack-mcp-server",
-    };
-}
-/**
- * Returns the Percy API base URL.
- * Defaults to `https://percy.io/api/v1`, overridable via `PERCY_API_URL` env var.
- */
-export function getPercyApiBaseUrl() {
-    return process.env.PERCY_API_URL || "https://percy.io/api/v1";
-}

package/dist/lib/percy-api/cache.d.ts

@@ -1,28 +0,0 @@
-/**
- * Simple in-memory cache with per-entry TTL.
- *
- * Used to cache Percy API responses and avoid redundant network calls
- * within short time windows (e.g., multiple tools querying the same build).
- */
-export declare class PercyCache {
-    private store;
-    /**
-     * Returns the cached value if it exists and has not expired.
-     * Expired entries are deleted on access.
-     */
-    get<T>(key: string): T | null;
-    /**
-     * Stores a value with an optional TTL (defaults to 30 seconds).
-     */
-    set(key: string, value: unknown, ttlMs?: number): void;
-    /**
-     * Removes all entries from the cache.
-     */
-    clear(): void;
-    /**
-     * Removes a single entry from the cache.
-     */
-    delete(key: string): void;
-}
-/** Singleton cache instance shared across Percy API tools. */
-export declare const percyCache: PercyCache;

package/dist/lib/percy-api/cache.js

@@ -1,48 +0,0 @@
-/**
- * Simple in-memory cache with per-entry TTL.
- *
- * Used to cache Percy API responses and avoid redundant network calls
- * within short time windows (e.g., multiple tools querying the same build).
- */
-const DEFAULT_TTL_MS = 30_000; // 30 seconds
-export class PercyCache {
-    store = new Map();
-    /**
-     * Returns the cached value if it exists and has not expired.
-     * Expired entries are deleted on access.
-     */
-    get(key) {
-        const entry = this.store.get(key);
-        if (!entry) {
-            return null;
-        }
-        if (Date.now() > entry.expiresAt) {
-            this.store.delete(key);
-            return null;
-        }
-        return entry.value;
-    }
-    /**
-     * Stores a value with an optional TTL (defaults to 30 seconds).
-     */
-    set(key, value, ttlMs = DEFAULT_TTL_MS) {
-        this.store.set(key, {
-            value,
-            expiresAt: Date.now() + ttlMs,
-        });
-    }
-    /**
-     * Removes all entries from the cache.
-     */
-    clear() {
-        this.store.clear();
-    }
-    /**
-     * Removes a single entry from the cache.
-     */
-    delete(key) {
-        this.store.delete(key);
-    }
-}
-/** Singleton cache instance shared across Percy API tools. */
-export const percyCache = new PercyCache();

package/dist/lib/percy-api/client.d.ts

@@ -1,69 +0,0 @@
-/**
- * Percy API HTTP client.
- *
- * Uses native `fetch` (consistent with existing Percy tools in this repo).
- * Handles JSON:API deserialization, rate limiting, and error enrichment.
- *
- * SECURITY: Token values are NEVER logged or exposed in error messages.
- */
-import { BrowserStackConfig } from "../types.js";
-type TokenScope = "project" | "org" | "auto";
-interface ClientOptions {
-    scope?: TokenScope;
-    projectName?: string;
-}
-interface JsonApiResource {
-    id: string;
-    type: string;
-    attributes?: Record<string, unknown>;
-    relationships?: Record<string, {
-        data: {
-            id: string;
-            type: string;
-        } | Array<{
-            id: string;
-            type: string;
-        }> | null;
-    }>;
-}
-interface JsonApiEnvelope {
-    data: JsonApiResource | JsonApiResource[] | null;
-    included?: JsonApiResource[];
-    meta?: Record<string, unknown>;
-}
-/**
- * Deserializes a JSON:API envelope into plain objects.
- *
- * - `data: null` → returns `null`
- * - `data: []` → returns `[]`
- * - `data: { ... }` → returns a single deserialized object
- * - `data: [{ ... }, ...]` → returns an array of deserialized objects
- */
-export declare function deserialize(envelope: JsonApiEnvelope): {
-    data: Record<string, unknown> | Record<string, unknown>[] | null;
-    meta?: Record<string, unknown>;
-};
-export declare class PercyClient {
-    private config;
-    private options;
-    constructor(config: BrowserStackConfig, options?: ClientOptions);
-    /**
-     * GET request with optional query params and JSON:API `include`.
-     */
-    get<T = Record<string, unknown>>(path: string, params?: Record<string, string>, includes?: string[]): Promise<T>;
-    /**
-     * POST request with an optional JSON body.
-     */
-    post<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
-    /**
-     * PATCH request with an optional JSON body.
-     */
-    patch<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
-    /**
-     * DELETE request.
-     */
-    del(path: string): Promise<void>;
-    private buildUrl;
-    private request;
-}
-export {};