@browserstack/mcp-server 1.2.17 → 1.2.18-beta.1

package/dist/tools/testmanagement-utils/get-sub-testplan.js

@@ -0,0 +1,149 @@
+import { apiClient } from "../../lib/apiClient.js";
+import { z } from "zod";
+import { formatAxiosError } from "../../lib/error.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { getTMBaseURL } from "../../lib/tm-base-url.js";
+/**
+ * Schema for fetching a single sub-test-plan by identifier under a parent test
+ * plan, including its linked test runs.
+ */
+export const GetSubTestPlanSchema = z.object({
+    project_identifier: z.string().describe("Project identifier (PR-*)."),
+    parent_test_plan_identifier: z
+        .string()
+        .describe("Parent test plan identifier (TP-*)."),
+    sub_test_plan_identifier: z
+        .string()
+        .describe("Sub-test-plan identifier (STP-*)."),
+});
+// Validates host parity with the TM base URL to prevent SSRF if `links.test_runs`
+// ever resolves to an absolute URL pointing elsewhere.
+//
+// The constructed fallback uses the flat shape `/test-plans/{STP}/test-runs`
+// (not nested under the parent) because that is the form the v2 API itself
+// returns in `sub_test_plan.links.test_runs`. The parent identifier deliberately
+// does NOT appear in this URL.
+function resolveEnrichmentUrl(linksTestRuns, tmBaseUrl, projectId, subPlanId) {
+    if (typeof linksTestRuns === "string" && linksTestRuns.length > 0) {
+        if (linksTestRuns.startsWith("/")) {
+            // Relative path — safe to join under tmBaseUrl.
+            return `${tmBaseUrl}${linksTestRuns}`;
+        }
+        if (linksTestRuns.startsWith("http://") ||
+            linksTestRuns.startsWith("https://")) {
+            try {
+                const linkUrl = new URL(linksTestRuns);
+                const baseUrl = new URL(tmBaseUrl);
+                if (linkUrl.host === baseUrl.host) {
+                    return linksTestRuns;
+                }
+            }
+            catch {
+                // Fall through to constructed fallback.
+            }
+        }
+    }
+    return `${tmBaseUrl}/api/v2/projects/${projectId}/test-plans/${subPlanId}/test-runs`;
+}
+/**
+ * Fetches a sub-test-plan by identifier and best-effort-enriches it with its
+ * linked test runs. The enrichment call is fail-soft: any failure (thrown
+ * AxiosError or non-success response) is swallowed into an empty runs list
+ * without flipping `isError` on the primary response.
+ */
+export async function getSubTestPlan(args, config) {
+    try {
+        const tmBaseUrl = await getTMBaseURL(config);
+        const projectId = encodeURIComponent(args.project_identifier);
+        const parentPlanId = encodeURIComponent(args.parent_test_plan_identifier);
+        const subPlanId = encodeURIComponent(args.sub_test_plan_identifier);
+        const authString = getBrowserStackAuth(config);
+        const [username, password] = authString.split(":");
+        const authHeader = "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+        const planResp = await apiClient.get({
+            url: `${tmBaseUrl}/api/v2/projects/${projectId}/test-plans/${parentPlanId}/sub-test-plans/${subPlanId}`,
+            headers: { Authorization: authHeader },
+        });
+        if (!planResp.data?.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to fetch sub-test-plan: ${JSON.stringify(planResp.data)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const plan = planResp.data.sub_test_plan;
+        const enrichmentUrl = resolveEnrichmentUrl(plan.links?.test_runs, tmBaseUrl, projectId, subPlanId);
+        let runs = [];
+        try {
+            const runsResp = await apiClient.get({
+                url: enrichmentUrl,
+                headers: { Authorization: authHeader },
+            });
+            if (runsResp.data?.success) {
+                runs = runsResp.data.test_runs ?? [];
+            }
+        }
+        catch {
+            // Enrichment is best-effort — leave runs empty.
+        }
+        const statusSummary = {};
+        let totalCases = 0;
+        for (const run of runs) {
+            statusSummary[run.run_state] = (statusSummary[run.run_state] ?? 0) + 1;
+            totalCases += run.test_cases_count ?? 0;
+        }
+        const tagsLine = Array.isArray(plan.tags) && plan.tags.length > 0
+            ? `Tags: ${plan.tags.join(", ")}`
+            : null;
+        const issuesLine = Array.isArray(plan.issues) && plan.issues.length > 0
+            ? `Issues: ${plan.issues.join(", ")}`
+            : null;
+        const header = [
+            `Sub-Test-Plan ${plan.identifier}: ${plan.name}`,
+            `Parent plan: ${plan.parent_plan_id}`,
+            `Status: ${plan.active_state}`,
+            plan.description ? `Description: ${plan.description}` : null,
+            tagsLine,
+            issuesLine,
+            plan.start_date || plan.end_date
+                ? `Dates: ${plan.start_date ?? "—"} → ${plan.end_date ?? "—"}`
+                : null,
+            `Linked runs: ${runs.length} (plan counts — active ${plan.test_runs_count?.active ?? 0} / closed ${plan.test_runs_count?.closed ?? 0})`,
+            `Total test cases across runs: ${totalCases}`,
+            Object.keys(statusSummary).length > 0
+                ? `Run-state breakdown: ${Object.entries(statusSummary)
+                    .map(([s, n]) => `${s}=${n}`)
+                    .join(", ")}`
+                : null,
+        ]
+            .filter(Boolean)
+            .join("\n");
+        const runsBlock = runs.length
+            ? "\n\nLinked test runs:\n" +
+                runs
+                    .map((r) => `• ${r.identifier}: ${r.name} [${r.run_state}] — ${r.test_cases_count} case(s)${r.assignee ? ` (assignee: ${r.assignee})` : ""}`)
+                    .join("\n")
+            : "\n\nNo test runs linked to this sub-plan.";
+        return {
+            content: [
+                { type: "text", text: header + runsBlock },
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        sub_test_plan: plan,
+                        linked_test_runs: runs,
+                        status_summary: statusSummary,
+                        total_test_cases: totalCases,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return formatAxiosError(err, "Failed to fetch sub-test-plan");
+    }
+}

package/dist/tools/testmanagement-utils/list-sub-testplans.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { BrowserStackConfig } from "../../lib/types.js";
+/**
+ * Schema for listing sub-test-plans under a parent test plan in a BrowserStack
+ * Test Management project.
+ */
+export declare const ListSubTestPlansSchema: z.ZodObject<{
+    project_identifier: z.ZodString;
+    parent_test_plan_identifier: z.ZodString;
+    p: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ListSubTestPlansArgs = z.infer<typeof ListSubTestPlansSchema>;
+/**
+ * Lists sub-test-plans under a parent test plan in BrowserStack Test Management.
+ */
+export declare function listSubTestPlans(args: ListSubTestPlansArgs, config: BrowserStackConfig): Promise<CallToolResult>;

package/dist/tools/testmanagement-utils/list-sub-testplans.js

@@ -0,0 +1,83 @@
+import { apiClient } from "../../lib/apiClient.js";
+import { z } from "zod";
+import { formatAxiosError } from "../../lib/error.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { getTMBaseURL } from "../../lib/tm-base-url.js";
+/**
+ * Schema for listing sub-test-plans under a parent test plan in a BrowserStack
+ * Test Management project.
+ */
+export const ListSubTestPlansSchema = z.object({
+    project_identifier: z.string().describe("Project identifier (PR-*)."),
+    parent_test_plan_identifier: z
+        .string()
+        .describe("Parent test plan identifier (TP-*)."),
+    p: z.number().optional().describe("Page number."),
+});
+/**
+ * Lists sub-test-plans under a parent test plan in BrowserStack Test Management.
+ */
+export async function listSubTestPlans(args, config) {
+    try {
+        const params = new URLSearchParams();
+        if (args.p !== undefined)
+            params.append("p", args.p.toString());
+        const tmBaseUrl = await getTMBaseURL(config);
+        const projectId = encodeURIComponent(args.project_identifier);
+        const parentPlanId = encodeURIComponent(args.parent_test_plan_identifier);
+        const url = `${tmBaseUrl}/api/v2/projects/${projectId}/test-plans/${parentPlanId}/sub-test-plans?${params.toString()}`;
+        const authString = getBrowserStackAuth(config);
+        const [username, password] = authString.split(":");
+        const resp = await apiClient.get({
+            url,
+            headers: {
+                Authorization: "Basic " + Buffer.from(`${username}:${password}`).toString("base64"),
+            },
+        });
+        const data = resp.data;
+        if (!data.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to list sub-test-plans: ${JSON.stringify(data)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const plans = data.sub_test_plans ?? [];
+        const info = data.info ?? {};
+        const count = info.count ?? plans.length;
+        if (plans.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No sub-test-plans found under ${args.parent_test_plan_identifier} in project ${args.project_identifier}.`,
+                    },
+                ],
+            };
+        }
+        const summary = plans
+            .map((p) => {
+            const tagsSegment = Array.isArray(p.tags) && p.tags.length > 0
+                ? ` — tags: [${p.tags.join(", ")}]`
+                : "";
+            return `• ${p.identifier}: ${p.name} [${p.active_state}] — ${p.test_runs_count?.active ?? 0} active / ${p.test_runs_count?.closed ?? 0} closed run(s)${tagsSegment}`;
+        })
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${count} sub-test-plan(s) under ${args.parent_test_plan_identifier} in project ${args.project_identifier}:\n\n${summary}`,
+                },
+                { type: "text", text: JSON.stringify(plans, null, 2) },
+            ],
+        };
+    }
+    catch (err) {
+        return formatAxiosError(err, "Failed to list sub-test-plans");
+    }
+}

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

@@ -1,7 +1,7 @@
 import { apiClient } from "../../lib/apiClient.js";
 import { z } from "zod";
 import { formatAxiosError } from "../../lib/error.js";
-import { fetchFormFields, projectIdentifierToId } from "./TCG-utils/api.js";
+import { fetchFormFields, normalizeDefaultFieldValue, projectIdentifierToId, } from "./TCG-utils/api.js";
 import { getTMBaseURL } from "../../lib/tm-base-url.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import logger from "../../logger.js";
@@ -62,26 +62,6 @@ export const UpdateTestCaseSchema = z.object({
         .optional()
         .describe("Map of custom field name/id to value. Valid field names and value types are per-project; discover them via the project's form fields."),
 });
-/**
- * Build a normalizer for a default field's accepted value.
- * The TM PATCH endpoint accepts different casings for different default
- * fields (Title-Case display name for priority/case_type, snake_case
- * internal_name for automation_status). We accept either from the caller
- * and emit the form the API actually wants.
- *
- * Returns undefined when no matching option is found — callers should
- * pass the raw value through so the backend can surface its own error.
- */
-function normalizeDefaultFieldValue(fieldValues, input, emit) {
-    const normalized = input.toLowerCase().trim();
-    const match = fieldValues.find((v) => (v.internal_name ?? "").toLowerCase() === normalized ||
-        (v.name ?? "").toLowerCase() === normalized);
-    if (!match)
-        return undefined;
-    if (emit === "name")
-        return match.name;
-    return match.internal_name ?? match.name;
-}
 /**
  * Normalise default-field inputs (priority/case_type/automation_status) to
  * what the TM PATCH endpoint accepts. Fetches the project's form-fields

package/dist/tools/testmanagement.d.ts

@@ -15,6 +15,8 @@ import { CreateTestCasesFromFileSchema } from "./testmanagement-utils/TCG-utils/
 import { CreateLCAStepsSchema } from "./testmanagement-utils/create-lca-steps.js";
 import { ListTestPlansSchema } from "./testmanagement-utils/list-testplans.js";
 import { GetTestPlanSchema } from "./testmanagement-utils/get-testplan.js";
+import { ListSubTestPlansSchema } from "./testmanagement-utils/list-sub-testplans.js";
+import { GetSubTestPlanSchema } from "./testmanagement-utils/get-sub-testplan.js";
 import { BrowserStackConfig } from "../lib/types.js";
 /**
  * Wrapper to call createProjectOrFolder util.
@@ -74,6 +76,14 @@ export declare function listTestPlansTool(args: z.infer<typeof ListTestPlansSche
  * Fetches a test plan by identifier, with its linked runs and a derived status summary.
  */
 export declare function getTestPlanTool(args: z.infer<typeof GetTestPlanSchema>, config: BrowserStackConfig, server: McpServer): Promise<CallToolResult>;
+/**
+ * Lists sub-test-plans under a parent test plan.
+ */
+export declare function listSubTestPlansTool(args: z.infer<typeof ListSubTestPlansSchema>, config: BrowserStackConfig, server: McpServer): Promise<CallToolResult>;
+/**
+ * Fetches a sub-test-plan by identifier, with its linked runs and a derived status summary.
+ */
+export declare function getSubTestPlanTool(args: z.infer<typeof GetSubTestPlanSchema>, config: BrowserStackConfig, server: McpServer): Promise<CallToolResult>;
 /**
  * Registers both project/folder and test-case tools.
  */

package/dist/tools/testmanagement.js

@@ -15,6 +15,8 @@ import { CreateTestCasesFromFileSchema } from "./testmanagement-utils/TCG-utils/
 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";
+import { listSubTestPlans, ListSubTestPlansSchema, } from "./testmanagement-utils/list-sub-testplans.js";
+import { getSubTestPlan, GetSubTestPlanSchema, } from "./testmanagement-utils/get-sub-testplan.js";
 //TODO: Moving the traceMCP and catch block to the parent(server) function
 /**
  * Wrapper to call createProjectOrFolder util.
@@ -319,6 +321,50 @@ export async function getTestPlanTool(args, config, server) {
         };
     }
 }
+/**
+ * Lists sub-test-plans under a parent test plan.
+ */
+export async function listSubTestPlansTool(args, config, server) {
+    try {
+        trackMCP("listSubTestPlans", server.server.getClientVersion(), undefined, config);
+        return await listSubTestPlans(args, config);
+    }
+    catch (err) {
+        logger.error("Failed to list sub-test-plans: %s", err);
+        trackMCP("listSubTestPlans", server.server.getClientVersion(), err, config);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to list sub-test-plans: ${err instanceof Error ? err.message : "Unknown error"}. Please open an issue on GitHub if the problem persists`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Fetches a sub-test-plan by identifier, with its linked runs and a derived status summary.
+ */
+export async function getSubTestPlanTool(args, config, server) {
+    try {
+        trackMCP("getSubTestPlan", server.server.getClientVersion(), undefined, config);
+        return await getSubTestPlan(args, config);
+    }
+    catch (err) {
+        logger.error("Failed to fetch sub-test-plan: %s", err);
+        trackMCP("getSubTestPlan", server.server.getClientVersion(), err, config);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to fetch sub-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.
  */
@@ -338,5 +384,7 @@ export default function addTestManagementTools(server, config) {
     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));
+    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination.", ListSubTestPlansSchema.shape, (args) => listSubTestPlansTool(args, config, server));
+    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs.", GetSubTestPlanSchema.shape, (args) => getSubTestPlanTool(args, config, server));
     return tools;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.2.17",
+  "version": "1.2.18-beta.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",