@browserstack/mcp-server 1.5.0-beta.8 → 1.5.0

package/dist/tools/testmanagement.js

@@ -19,6 +19,7 @@ import { getTestPlan, GetTestPlanSchema, } from "./testmanagement-utils/get-test
 import { listSubTestPlans, ListSubTestPlansSchema, } from "./testmanagement-utils/list-sub-testplans.js";
 import { getSubTestPlan, GetSubTestPlanSchema, } from "./testmanagement-utils/get-sub-testplan.js";
 import { elicitCredentialsIfSupported } from "../lib/elicit-credentials.js";
+import { NEEDS_PROJECT_ID, NEEDS_TEST_PLAN_ID, PLAN_WRITES_VIA_AGENT, PROJECT_ID_ONLY_FOR_FOLDER, } from "./tool-handoff.js";
 //TODO: Moving the traceMCP and catch block to the parent(server) function
 /**
  * Wrapper to call createProjectOrFolder util.
@@ -263,11 +264,11 @@ export async function uploadProductRequirementFileTool(args, config, server) {
  */
 export async function createTestCasesFromFileTool(args, context, config, server) {
     try {
-        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), undefined);
+        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), undefined, config);
         return await createTestCasesFromFile(args, context, config);
     }
     catch (err) {
-        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), err);
+        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), err, config);
         return {
             content: [
                 {
@@ -432,35 +433,40 @@ export async function getSubTestPlanTool(args, config, server) {
  */
 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, {
+    tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management." +
+        PROJECT_ID_ONLY_FOR_FOLDER, CreateProjFoldSchema.shape, {
         title: "Create Project or Folder",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createProjectOrFolderTool(args, config, server));
-    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", CreateTestCaseSchema.shape, {
+    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management." +
+        NEEDS_PROJECT_ID, CreateTestCaseSchema.shape, {
         title: "Create Test Case",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createTestCaseTool(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, {
+    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." +
+        NEEDS_PROJECT_ID, UpdateTestCaseSchema.shape, {
         title: "Update Test Case",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: true,
         idempotentHint: true,
     }, (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, {
+    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." +
+        NEEDS_PROJECT_ID, ListTestCasesSchema.shape, {
         title: "List Test Cases",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (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, {
+    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." +
+        NEEDS_PROJECT_ID, ListFoldersSchema.shape, {
         title: "List Folders",
         readOnlyHint: true,
         openWorldHint: false,
@@ -474,35 +480,39 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTemplatesTool(args, config, server));
-    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management.", CreateTestRunSchema.shape, {
+    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management." + NEEDS_PROJECT_ID, CreateTestRunSchema.shape, {
         title: "Create Test Run",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (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, {
+    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)" +
+        NEEDS_PROJECT_ID, ListTestRunsSchema.shape, {
         title: "List Test Runs",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestRunsTool(args, config, server));
-    tools.updateTestRun = server.tool("updateTestRun", "Update a test run's metadata and/or add test cases to it.", UpdateTestRunSchema.shape, {
+    tools.updateTestRun = server.tool("updateTestRun", "Update a test run's metadata and/or add test cases to it." +
+        NEEDS_PROJECT_ID, UpdateTestRunSchema.shape, {
         title: "Update Test Run",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: true,
         idempotentHint: true,
     }, (args) => updateTestRunTool(args, config, server));
-    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API.", AddTestResultSchema.shape, {
+    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API." +
+        NEEDS_PROJECT_ID, AddTestResultSchema.shape, {
         title: "Add Test Result",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => addTestResultTool(args, config, server));
-    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, {
+    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." +
+        NEEDS_PROJECT_ID, UploadFileSchema.shape, {
         title: "Upload Product Requirement File",
         readOnlyHint: false,
         openWorldHint: false,
@@ -516,35 +526,47 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: false,
     }, (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, {
+    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." +
+        NEEDS_PROJECT_ID, CreateLCAStepsSchema.shape, {
         title: "Create LCA Steps",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (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, {
+    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." +
+        NEEDS_PROJECT_ID +
+        PLAN_WRITES_VIA_AGENT, ListTestPlansSchema.shape, {
         title: "List Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (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, {
+    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." +
+        NEEDS_PROJECT_ID +
+        NEEDS_TEST_PLAN_ID +
+        PLAN_WRITES_VIA_AGENT, GetTestPlanSchema.shape, {
         title: "Get Test Plan",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (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, {
+    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination." +
+        NEEDS_PROJECT_ID +
+        NEEDS_TEST_PLAN_ID +
+        PLAN_WRITES_VIA_AGENT, ListSubTestPlansSchema.shape, {
         title: "List Sub Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (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, {
+    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs." +
+        NEEDS_PROJECT_ID +
+        NEEDS_TEST_PLAN_ID +
+        PLAN_WRITES_VIA_AGENT, GetSubTestPlanSchema.shape, {
         title: "Get Sub Test Plan",
         readOnlyHint: true,
         openWorldHint: false,

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

@@ -0,0 +1,66 @@
+/**
+ * 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

@@ -0,0 +1,78 @@
+/**
+ * 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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.5.0-beta.8",
+  "version": "1.5.0",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",
@@ -21,8 +21,7 @@
     "browserstack-mcp-server": "dist/index.js"
   },
   "files": [
-    "dist",
-    "capability"
+    "dist"
   ],
   "keywords": [
     "mcp",
@@ -31,7 +30,7 @@
     "automation"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20.9.0"
   },
   "author": "",
   "license": "ISC",
@@ -45,7 +44,7 @@
     "form-data": "^4.0.5",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "sharp": "^0.34.5",
+    "sharp": "^0.35.4",
     "uuid": "^13.0.0",
     "webdriverio": "^9.27.0",
     "zod": "^4.3.6"