@browserstack/mcp-server 1.2.24 → 1.2.25-beta.1

package/dist/tools/testmanagement-utils/create-testcase.d.ts

@@ -25,6 +25,7 @@ export interface TestCaseCreateRequest {
     automation_status?: string;
     priority?: string;
     template?: string;
+    template_id?: number;
 }
 export interface TestCaseResponse {
     data: {
@@ -40,6 +41,7 @@ export interface TestCaseResponse {
             }>;
             tags: string[];
             template: string;
+            template_id?: number;
             description: string;
             preconditions: string;
             title: string;
@@ -76,6 +78,7 @@ export declare const CreateTestCaseSchema: z.ZodObject<{
     automation_status: z.ZodOptional<z.ZodString>;
     priority: z.ZodOptional<z.ZodString>;
     template: z.ZodOptional<z.ZodString>;
+    template_id: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare function sanitizeArgs(args: any): any;
 export declare function createTestCase(params: TestCaseCreateRequest, config: BrowserStackConfig): Promise<CallToolResult>;

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

@@ -69,7 +69,11 @@ export const CreateTestCaseSchema = z.object({
     template: z
         .string()
         .optional()
-        .describe("Template internal slug, e.g. 'test_case_steps' or 'test_case_bdd'. Use the slug, not the display name."),
+        .describe("System template slug only: 'test_case_steps' or 'test_case_bdd'. For a custom template, use template_id instead."),
+    template_id: z
+        .number()
+        .optional()
+        .describe("Numeric ID of a custom template (from listTestCaseTemplates); applies that template. Overrides 'template'."),
 });
 export function sanitizeArgs(args) {
     const cleaned = { ...args };
@@ -83,6 +87,8 @@ export function sanitizeArgs(args) {
         delete cleaned.automation_status;
     if (cleaned.template === null)
         delete cleaned.template;
+    if (cleaned.template_id === null)
+        delete cleaned.template_id;
     if (cleaned.issue_tracker) {
         if (cleaned.issue_tracker.name === undefined ||
             cleaned.issue_tracker.host === undefined) {
@@ -107,24 +113,121 @@ async function normalizePriority(projectIdentifier, priority, config) {
         return priority;
     }
 }
+/**
+ * Read a freshly-created test case back to learn which template was actually
+ * applied. The create response does not echo template_id, but the v1 search
+ * endpoint does. Returns undefined on any failure (caller then skips the
+ * verification warning rather than blocking the success path).
+ */
+async function fetchAppliedTemplateId(numericProjectId, identifier, config) {
+    try {
+        const tmBaseUrl = await getTMBaseURL(config);
+        const resp = await apiClient.get({
+            url: `${tmBaseUrl}/api/v1/projects/${encodeURIComponent(numericProjectId)}/test-cases/search?q%5Bquery%5D=${encodeURIComponent(identifier)}`,
+            headers: {
+                "API-TOKEN": getBrowserStackAuth(config),
+                accept: "application/json, text/plain, */*",
+            },
+        });
+        const cases = resp.data?.test_cases ?? [];
+        const match = cases.find((c) => c.identifier === identifier);
+        return match?.template_id;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The v1 create endpoint (used when a template_id is requested) keys
+ * custom_fields by numeric field id with option *ids* — unlike the v2 endpoint,
+ * which keys by field name with option *values*. Translate the MCP's by-name
+ * shape into v1's by-id shape using the project's form fields. Best-effort:
+ * unknown fields/options pass through unchanged.
+ */
+async function toV1CustomFields(customFields, numericProjectId, config) {
+    let defs = [];
+    try {
+        const formFields = await fetchFormFields(numericProjectId, config);
+        defs = Array.isArray(formFields?.custom_fields)
+            ? formFields.custom_fields
+            : [];
+    }
+    catch {
+        return customFields;
+    }
+    const byName = new Map(defs.map((f) => [f.field_name, f]));
+    const out = {};
+    for (const [name, value] of Object.entries(customFields)) {
+        const def = byName.get(name);
+        if (!def) {
+            out[name] = value; // unknown field name — leave as-is
+            continue;
+        }
+        const isOptionField = def.field_type === "field_dropdown" ||
+            def.field_type === "field_multi_dropdown";
+        if (isOptionField) {
+            const optionIdByValue = new Map();
+            for (const o of (def.option_values ?? [])) {
+                optionIdByValue.set(String(o.option_value), o.id);
+            }
+            const toOptionId = (v) => optionIdByValue.get(String(v)) ?? v;
+            out[String(def.id)] = Array.isArray(value)
+                ? value.map(toOptionId)
+                : toOptionId(value);
+        }
+        else {
+            out[String(def.id)] = value;
+        }
+    }
+    return out;
+}
 export async function createTestCase(params, config) {
     const testCaseParams = { ...params };
     if (testCaseParams.priority !== undefined) {
         testCaseParams.priority = await normalizePriority(params.project_identifier, testCaseParams.priority, config);
     }
-    const body = { test_case: testCaseParams };
     const authString = getBrowserStackAuth(config);
     const [username, password] = authString.split(":");
     try {
         const tmBaseUrl = await getTMBaseURL(config);
-        const response = await apiClient.post({
-            url: `${tmBaseUrl}/api/v2/projects/${encodeURIComponent(params.project_identifier)}/folders/${encodeURIComponent(params.folder_id)}/test-cases`,
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: "Basic " + Buffer.from(`${username}:${password}`).toString("base64"),
-            },
-            body,
-        });
+        // The public v2 create endpoint silently drops template_id, so a specific
+        // (custom) template cannot be applied through it. The v1 create endpoint
+        // DOES honour template_id — but it needs the numeric project id, the folder
+        // in the body, API-TOKEN auth, and custom_fields keyed by id. Use v1 only
+        // when a template_id is requested; otherwise keep the proven v2 path so
+        // existing behaviour (incl. custom_fields by name) is unchanged.
+        let request;
+        if (testCaseParams.template_id !== undefined) {
+            const numericProjectId = await projectIdentifierToId(params.project_identifier, config);
+            const v1TestCase = { ...testCaseParams };
+            delete v1TestCase.project_identifier;
+            delete v1TestCase.folder_id;
+            delete v1TestCase.custom_fields;
+            v1TestCase.test_case_folder_id = Number(params.folder_id);
+            if (testCaseParams.custom_fields) {
+                v1TestCase.custom_fields = await toV1CustomFields(testCaseParams.custom_fields, numericProjectId, config);
+            }
+            request = {
+                url: `${tmBaseUrl}/api/v1/projects/${encodeURIComponent(numericProjectId)}/test-cases`,
+                headers: {
+                    "Content-Type": "application/json",
+                    "API-TOKEN": authString,
+                },
+                body: { folder_id: Number(params.folder_id), test_case: v1TestCase },
+            };
+        }
+        else {
+            request = {
+                url: `${tmBaseUrl}/api/v2/projects/${encodeURIComponent(params.project_identifier)}/folders/${encodeURIComponent(params.folder_id)}/test-cases`,
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: "Basic " +
+                        Buffer.from(`${username}:${password}`).toString("base64"),
+                },
+                body: { test_case: testCaseParams },
+            };
+        }
+        const response = await apiClient.post(request);
         const { data } = response.data;
         if (!data.success) {
             return {
@@ -140,15 +243,33 @@ export async function createTestCase(params, config) {
         const tc = data.test_case;
         const projectId = await projectIdentifierToId(params.project_identifier, config);
         const content = [];
+        // A specific custom template is selected by numeric template_id. The create
+        // response does not echo template_id, so read the case back to learn which
+        // template was actually applied and warn on mismatch — the public create
+        // endpoint may silently ignore the requested template.
+        if (params.template_id !== undefined) {
+            const appliedId = tc.template_id !== undefined
+                ? Number(tc.template_id)
+                : await fetchAppliedTemplateId(projectId, tc.identifier, config);
+            if (appliedId !== undefined && appliedId !== Number(params.template_id)) {
+                content.push({
+                    type: "text",
+                    text: `Warning: requested template_id ${params.template_id} was not applied — the test case uses template_id ${appliedId}. Confirm the id via listTestCaseTemplates and that the template is linked to this project.`,
+                });
+            }
+        }
         // The TM API silently ignores an unrecognized template slug and falls back
         // to the default. Surface that instead of letting it pass as success.
-        if (params.template &&
+        // Note: the `template` slug only ever selects a SYSTEM template; a custom
+        // template must be selected with template_id.
+        if (params.template_id === undefined &&
+            params.template &&
             tc.template &&
             String(tc.template).toLowerCase() !==
                 String(params.template).toLowerCase()) {
             content.push({
                 type: "text",
-                text: `Warning: requested template "${params.template}" was not applied — the test case was created with "${tc.template}". BrowserStack expects the template's internal slug (e.g. "test_case_steps", "test_case_bdd") and silently uses the default for unrecognized values.`,
+                text: `Warning: requested template "${params.template}" was not applied — the test case was created with "${tc.template}". The 'template' field accepts only the system slugs "test_case_steps" or "test_case_bdd"; for a custom template pass template_id (see listTestCaseTemplates).`,
             });
         }
         content.push({

package/dist/tools/testmanagement-utils/list-templates.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { BrowserStackConfig } from "../../lib/types.js";
+/**
+ * Schema for listing test-case templates in BrowserStack Test Management.
+ */
+export declare const ListTemplatesSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ListTemplatesArgs = z.infer<typeof ListTemplatesSchema>;
+/**
+ * Lists test-case templates (group-wide) so callers can resolve a template
+ * name to the numeric template_id.
+ *
+ * Custom templates share a step_type (test_case_steps | test_case_bdd) with the
+ * system templates, so the slug cannot identify them — only the id can. The
+ * list is account-wide; a template must also be linked to the target project to
+ * be usable there.
+ */
+export declare function listTemplates(args: ListTemplatesArgs, config: BrowserStackConfig): Promise<CallToolResult>;

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

@@ -0,0 +1,78 @@
+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 test-case templates in BrowserStack Test Management.
+ */
+export const ListTemplatesSchema = z.object({
+    name: z
+        .string()
+        .optional()
+        .describe("Case-insensitive substring filter on template name."),
+});
+/**
+ * Lists test-case templates (group-wide) so callers can resolve a template
+ * name to the numeric template_id.
+ *
+ * Custom templates share a step_type (test_case_steps | test_case_bdd) with the
+ * system templates, so the slug cannot identify them — only the id can. The
+ * list is account-wide; a template must also be linked to the target project to
+ * be usable there.
+ */
+export async function listTemplates(args, config) {
+    try {
+        const tmBaseUrl = await getTMBaseURL(config);
+        // Verified working with API-TOKEN auth (same surface as form-fields-v2).
+        const resp = await apiClient.get({
+            url: `${tmBaseUrl}/api/v1/admin-v2/settings/templates?entity_type=TestCase&paginated=false`,
+            headers: {
+                "API-TOKEN": getBrowserStackAuth(config),
+                accept: "application/json, text/plain, */*",
+            },
+        });
+        let templates = resp.data?.templates ?? [];
+        if (args.name) {
+            const needle = args.name.toLowerCase();
+            templates = templates.filter((t) => (t.name ?? "").toLowerCase().includes(needle));
+        }
+        if (templates.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: args.name
+                            ? `No templates matching "${args.name}".`
+                            : "No templates found.",
+                    },
+                ],
+            };
+        }
+        const summary = templates
+            .map((t) => `• [template_id=${t.id}] ${t.name} — step_type=${t.step_type}${t.is_system ? " (system)" : ""}${t.is_default ? " (default)" : ""}${t.enabled === false ? " (disabled)" : ""}`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${templates.length} template(s):\n\n${summary}`,
+                },
+                {
+                    type: "text",
+                    text: JSON.stringify(templates.map((t) => ({
+                        template_id: t.id,
+                        name: t.name,
+                        step_type: t.step_type,
+                        is_system: t.is_system,
+                        is_default: t.is_default,
+                        enabled: t.enabled,
+                    })), null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return formatAxiosError(err, "Failed to list templates");
+    }
+}

package/dist/tools/testmanagement.d.ts

@@ -6,6 +6,7 @@ import { TestCaseCreateRequest } from "./testmanagement-utils/create-testcase.js
 import { TestCaseUpdateRequest } from "./testmanagement-utils/update-testcase.js";
 import { ListTestCasesSchema } from "./testmanagement-utils/list-testcases.js";
 import { ListFoldersSchema } from "./testmanagement-utils/list-folders.js";
+import { ListTemplatesSchema } from "./testmanagement-utils/list-templates.js";
 import { CreateTestRunSchema } from "./testmanagement-utils/create-testrun.js";
 import { ListTestRunsSchema } from "./testmanagement-utils/list-testruns.js";
 import { UpdateTestRunSchema } from "./testmanagement-utils/update-testrun.js";
@@ -38,6 +39,10 @@ export declare function listTestCasesTool(args: z.infer<typeof ListTestCasesSche
  * Lists folders in a project (or sub-folders under a parent folder).
  */
 export declare function listFoldersTool(args: z.infer<typeof ListFoldersSchema>, config: BrowserStackConfig, server: McpServer): Promise<CallToolResult>;
+/**
+ * Lists test-case templates so callers can resolve a name to a template_id.
+ */
+export declare function listTemplatesTool(args: z.infer<typeof ListTemplatesSchema>, config: BrowserStackConfig, server: McpServer): Promise<CallToolResult>;
 /**
  * Creates a test run in BrowserStack Test Management.
  */

package/dist/tools/testmanagement.js

@@ -5,6 +5,7 @@ import { createTestCase as createTestCaseAPI, sanitizeArgs, CreateTestCaseSchema
 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 { listTemplates, ListTemplatesSchema, } from "./testmanagement-utils/list-templates.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";
@@ -128,6 +129,27 @@ export async function listFoldersTool(args, config, server) {
         };
     }
 }
+/**
+ * Lists test-case templates so callers can resolve a name to a template_id.
+ */
+export async function listTemplatesTool(args, config, server) {
+    try {
+        trackMCP("listTestCaseTemplates", server.server.getClientVersion(), undefined, config);
+        return await listTemplates(args, config);
+    }
+    catch (err) {
+        trackMCP("listTestCaseTemplates", server.server.getClientVersion(), err, config);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to list templates: ${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.
  */
@@ -375,6 +397,7 @@ export default function addTestManagementTools(server, config) {
     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.listTestCaseTemplates = server.tool("listTestCaseTemplates", "List test-case templates with their numeric template_id. Use the id with createTestCase to apply a custom template (the 'template' slug only selects system templates).", ListTemplatesSchema.shape, (args) => listTemplatesTool(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));

package/package.json

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