@browserstack/mcp-server 1.4.0-beta.3 → 1.5.0-beta.10

package/dist/tools/capability-registry/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * The shape of the index artifact, which is the contract with the export pipeline.
+ *
+ * The artifact is generated by the capability-registry build and transformed into its
+ * released envelope by the export pipeline's merge step. It contains ONLY data that has
+ * already passed that side's outbound boundary. Nothing here is parsed from an OpenAPI spec
+ * at runtime: if this half parsed specs it would become the boundary, and every gate (route
+ * lint, vocabulary rule, intent lint, discovery denylist) would have to be reimplemented and
+ * re-tested here. Reading a pre-projected index means the internal data is not in the
+ * package at all.
+ *
+ * ONE FILE PER PRODUCT. The released artifact is `capability/<product>.capability-index.json`,
+ * with the
+ * product object at the top level under its own name. The plural `products` wrapper belonged
+ * to the pre-release shape and implied multi-product files that never existed.
+ */
+/**
+ * The envelope's format marker, for FUTURE shape changes.
+ *
+ * BOTH the released and the pre-release shapes claim 1, so this number cannot distinguish
+ * them — `readIndexFile` shape-detects on the `products` wrapper instead. The check is still
+ * worth keeping: it is what refuses a shape the generator has announced but this build does
+ * not read.
+ */
+export declare const SUPPORTED_SCHEMA_VERSION = 1;
+/** Envelope keys, i.e. everything at the top level that is NOT the product object. */
+export declare const ENVELOPE_KEYS: readonly ["schema_version", "version", "build_id", "harness_commit", "products"];
+export type Mode = "read" | "write" | "destructive";
+/** One parameter, under the name the OpenAPI spec itself gives it. */
+export interface WireParam {
+    name: string;
+    type: string;
+    required?: true;
+    values?: unknown[];
+    example?: unknown;
+    description?: string;
+    /** Field names/types one level inside an array item or nested object. */
+    fields?: {
+        name: string;
+        type: string;
+        required?: true;
+    }[];
+    /**
+     * Where a body field sits in the JSON, when that differs from its name. Published
+     * because the nesting is not guessable and getting it wrong fails silently — tm's folder
+     * create really wants `{folder: {name}}` while the spec's flat `{name}` is what a reader
+     * would assume.
+     */
+    json_path?: string;
+}
+/**
+ * A reference into a product-level lookup table.
+ *
+ * Named components are stored ONCE, already dereferenced and allOf-flattened at build time,
+ * so resolution is a single dict lookup rather than a recursive $ref walk at runtime.
+ */
+export interface ComponentRef {
+    $response?: string;
+    $schema?: string;
+}
+/** A JSON Schema fragment, or a reference to a named one. */
+export type SchemaNode = ComponentRef & Record<string, unknown>;
+/** One declared response, or a reference to a named one. */
+export interface ResponseDoc extends ComponentRef {
+    description?: string;
+    schema?: SchemaNode;
+}
+/** A capability, keyed by the endpoint it exposes. There is deliberately no name. */
+export interface Capability {
+    /**
+     * The caller-facing handle — the snake-cased `operationId`, unique within its product.
+     *
+     * This is what `invokeCapability` takes, and what `entities[*].capabilities[]` lists. It
+     * is stable where a route is not: `/edit` becoming `/edit-v2` must not break a caller
+     * holding a handle.
+     *
+     * OPTIONAL because not every product publishes it yet — loadtesting's index carries none.
+     * For those, the endpoint remains the handle, so nothing may assume this is present.
+     */
+    name?: string;
+    method: string;
+    path: string;
+    mode: Mode;
+    entity: string;
+    path_params?: WireParam[];
+    query?: WireParam[];
+    body?: WireParam[];
+    intent?: string;
+    /**
+     * How to call the endpoint correctly.
+     *
+     * ABSENT from the released artifact — the export dropped it, and the shape-change note
+     * does not say whether that was intended. Kept optional and still scored by search so the
+     * server works either way; nothing may depend on it being present.
+     */
+    guidance?: string[];
+    /** Allowlisted row fields. Absent when `shape` is "discovered". */
+    returns?: string[];
+    /** "discovered" when the product declares no response schema for this operation. */
+    shape?: "discovered";
+    requires?: string[];
+    paginated?: boolean;
+    /** The largest page the operation declares. */
+    max_page_size?: number;
+    /**
+     * Declared responses by status code, values possibly `{$response: "Name"}` references.
+     *
+     * ADDITIVE and not yet emitted: no capability in the current export carries it. Absence
+     * means "no response schema available", never an error. Resolve with `resolveComponent`.
+     */
+    responses?: Record<string, ResponseDoc>;
+}
+export interface EntityDoc {
+    title?: string;
+    aliases?: string[];
+    id_convention?: string;
+    parents?: string[];
+    relations?: {
+        entity?: string;
+        via?: string;
+    }[];
+    /**
+     * What a caller gets wrong about this ENTITY, as opposed to one operation.
+     *
+     * The entity-wide half of guidance: "a run's `id` is the display string, take `uuid`"
+     * holds for every capability returning a run, so it is stated once here rather than
+     * copied onto each capability's `guidance` — which would repeat across ~20 records and,
+     * since guidance is a search haystack, dilute ranking with boilerplate.
+     *
+     * Filtered at build time and often absent: of tm's 155 authored facts, 73 are publishable
+     * as written and the rest name routes, HTTP verbs or wire-shaped parameters. Absent means
+     * "none passed", never an error.
+     */
+    key_facts?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Paging controls, keyed "METHOD /path".
+ *
+ * NOT USED BY THIS SERVER: it performs one request and returns the response, so paging
+ * belongs to the caller and the page parameters are published with the endpoint's other
+ * query parameters. The field is still emitted by the build, so it stays described here
+ * rather than silently ignored — a consumer that DOES page can use it.
+ */
+export interface PagingRule {
+    page?: string;
+    size?: string;
+    /** The largest page the operation declares. Absent when the spec states no maximum. */
+    max?: number;
+}
+/**
+ * How a product wants the caller's credentials presented.
+ *
+ * The OpenAPI `securityScheme` vocabulary, verbatim — `type` / `in` / `name` / `scheme` —
+ * because the spec already describes this and inventing a parallel taxonomy would mean
+ * translating between two of them forever. ONE scheme per product, not OpenAPI's list of
+ * alternatives: this server holds a username and an access key and nothing else, so
+ * "the first alternative we can satisfy" only ever had one answer.
+ *
+ * `template` is what makes it a contract rather than a guess — a product taking
+ * `{username}_{access_key}` is expressible instead of being a special case in the server.
+ * It names placeholders, never values: the credential itself stays in config, and the
+ * harness's `{ env: … }` value sources must NOT cross the boundary into the artifact.
+ */
+export interface AuthScheme {
+    /** "apiKey" puts the rendered template in a header; "http" with scheme "basic" encodes it. */
+    type: "apiKey" | "http";
+    /** apiKey only. Header is the sole supported location — see `egress.authHeaders`. */
+    in?: "header" | "cookie" | "query";
+    /** apiKey only: the header name, e.g. "Api-Token". */
+    name?: string;
+    /** http only. */
+    scheme?: string;
+    /** Defaults to `{username}:{access_key}`. */
+    template?: string;
+}
+export interface ProductIndex {
+    summary: string;
+    /**
+     * How to authenticate to this product. Absent means the historical default: the caller's
+     * credentials as `Api-Token: {username}:{access_key}`, which is what every shipped index
+     * relies on today.
+     */
+    auth?: AuthScheme;
+    /**
+     * The single host this product is served from, when it has one.
+     *
+     * A default, not the last word: config overrides it, and for a region-sharded product
+     * (one declaring `base_urls`) account discovery outranks it and this is the fallback.
+     */
+    base_url?: string;
+    /**
+     * Candidate regional hosts, in probe order, for a product whose host depends on the
+     * ACCOUNT rather than the deployment.
+     *
+     * Declaring these makes the product region-sharded: the server asks each in turn with the
+     * caller's credentials and keeps the one that answers. A single fixed `base_url` cannot
+     * express this — it would send every account outside the default region to the wrong host,
+     * a failure invisible to anyone testing from inside that region.
+     */
+    base_urls?: string[];
+    /**
+     * The endpoint to probe the candidates with. Derived from the capabilities when absent
+     * (see `discovery.probePath`); declare it when the derived choice would be wrong.
+     */
+    probe_path?: string;
+    capabilities: Capability[];
+    entities: Record<string, EntityDoc>;
+    paging?: Record<string, PagingRule>;
+    /** Named responses, referenced as `{$response: "Name"}`. Additive; not yet emitted. */
+    responses?: Record<string, ResponseDoc>;
+    /** Named schemas, referenced as `{$schema: "Name"}`. Additive; not yet emitted. */
+    schemas?: Record<string, SchemaNode>;
+}
+/** Where one product's data came from. Logging and cache-busting only. */
+export interface Provenance {
+    /** `<commit>_<UTC timestamp>` in the released shape. */
+    build_id: string;
+    /** Dotted content-generation counter, e.g. "1.2". Absent in the pre-release shape. */
+    version?: string;
+}
+/**
+ * The merged, in-memory model: every loaded file's product under its own name.
+ *
+ * This is the server's own structure, not the file format — one file carries one product,
+ * and the registry holds all of them so a caller can search across products.
+ */
+export interface RegistryIndex {
+    schema_version: number;
+    build_id: string;
+    products: Record<string, ProductIndex>;
+}

package/dist/tools/capability-registry/types.js

@@ -0,0 +1,33 @@
+/**
+ * The shape of the index artifact, which is the contract with the export pipeline.
+ *
+ * The artifact is generated by the capability-registry build and transformed into its
+ * released envelope by the export pipeline's merge step. It contains ONLY data that has
+ * already passed that side's outbound boundary. Nothing here is parsed from an OpenAPI spec
+ * at runtime: if this half parsed specs it would become the boundary, and every gate (route
+ * lint, vocabulary rule, intent lint, discovery denylist) would have to be reimplemented and
+ * re-tested here. Reading a pre-projected index means the internal data is not in the
+ * package at all.
+ *
+ * ONE FILE PER PRODUCT. The released artifact is `capability/<product>.capability-index.json`,
+ * with the
+ * product object at the top level under its own name. The plural `products` wrapper belonged
+ * to the pre-release shape and implied multi-product files that never existed.
+ */
+/**
+ * The envelope's format marker, for FUTURE shape changes.
+ *
+ * BOTH the released and the pre-release shapes claim 1, so this number cannot distinguish
+ * them — `readIndexFile` shape-detects on the `products` wrapper instead. The check is still
+ * worth keeping: it is what refuses a shape the generator has announced but this build does
+ * not read.
+ */
+export const SUPPORTED_SCHEMA_VERSION = 1;
+/** Envelope keys, i.e. everything at the top level that is NOT the product object. */
+export const ENVELOPE_KEYS = [
+    "schema_version",
+    "version",
+    "build_id",
+    "harness_commit",
+    "products",
+];

package/dist/tools/get-failure-logs.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { trackMCP } from "../lib/instrumentation.js";
-import { NEEDS_SESSION_ID } from "./tool-handoff.js";
 import { retrieveNetworkFailures, retrieveSessionFailures, retrieveConsoleFailures, } from "./failurelogs-utils/automate.js";
 import { retrieveDeviceLogs, retrieveAppiumLogs, retrieveCrashLogs, } from "./failurelogs-utils/app-automate.js";
 import { AppAutomateLogType, AutomateLogType, SessionType, } from "../lib/constants.js";
@@ -99,8 +98,7 @@ export async function getFailureLogs(args, config) {
 // Register tool with the MCP server
 export default function registerGetFailureLogs(server, config) {
     const tools = {};
-    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch various types of logs from a BrowserStack session. Supports both automate and app-automate sessions." +
-        NEEDS_SESSION_ID, {
+    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch various types of logs from a BrowserStack session. Supports both automate and app-automate sessions.", {
         sessionType: z
             .enum([SessionType.Automate, SessionType.AppAutomate])
             .describe("Type of BrowserStack session. Must be explicitly provided by the user."),

package/dist/tools/rca-agent.js

@@ -7,7 +7,6 @@ import { getRCAData } from "./rca-agent-utils/rca-data.js";
 import { formatRCAData } from "./rca-agent-utils/format-rca.js";
 import { handleMCPError } from "../lib/utils.js";
 import { trackMCP } from "../index.js";
-import { NEEDS_BUILD_ID, NEEDS_TEST_IDS } from "./tool-handoff.js";
 import { FETCH_RCA_PARAMS, GET_BUILD_ID_PARAMS, LIST_TEST_IDS_PARAMS, } from "./rca-agent-utils/constants.js";
 // Tool function to fetch build ID
 export async function getBuildIdTool(args, config) {
@@ -131,8 +130,7 @@ export async function listTestIdsTool(args, config) {
 }
 export default function addRCATools(server, config) {
     const tools = {};
-    tools.fetchRCA = server.tool("fetchRCA", "Fetch AI Root Cause Analysis for the current user's failed BrowserStack Automate/App-Automate tests. Suggests fixes only; never auto-apply, require explicit user approval." +
-        NEEDS_TEST_IDS, FETCH_RCA_PARAMS, {
+    tools.fetchRCA = server.tool("fetchRCA", "Fetch AI Root Cause Analysis for the current user's failed BrowserStack Automate/App-Automate tests. Suggests fixes only; never auto-apply, require explicit user approval.", FETCH_RCA_PARAMS, {
         title: "Fetch Root Cause Analysis",
         readOnlyHint: true,
         openWorldHint: false,
@@ -177,8 +175,7 @@ export default function addRCATools(server, config) {
             return handleMCPError("listBuildId", server, config, error);
         }
     });
-    tools.listTestIds = server.tool("listTestIds", "List all tests of a BrowserStack build (each with its status); optional status filter." +
-        NEEDS_BUILD_ID, LIST_TEST_IDS_PARAMS, {
+    tools.listTestIds = server.tool("listTestIds", "List all tests of a BrowserStack build (each with its status); optional status filter.", LIST_TEST_IDS_PARAMS, {
         title: "List Test IDs",
         readOnlyHint: true,
         openWorldHint: false,

package/dist/tools/selfheal.js

@@ -3,7 +3,6 @@ import { getSelfHealSelectors, fetchSelfHealingReportByBuild, } from "./selfheal
 import { fetchTestCodeForSessions, formatTestCodeAsContext, describeTestCodeFetchIssues, } from "./selfheal-utils/fetch-test-code.js";
 import logger from "../logger.js";
 import { trackMCP } from "../lib/instrumentation.js";
-import { NEEDS_SESSION_ID } from "./tool-handoff.js";
 // Local helper: returns the server-configured BrowserStack credentials, or
 // null when either is missing. Lives here because the self-heal tools need
 // to degrade gracefully — `getBrowserStackAuth` throws, which is wrong for
@@ -431,8 +430,7 @@ export default function addSelfHealTools(server, config) {
         "the run. Provide exactly one of `sessionId` (single Automate / " +
         "App-Automate session) or `buildUuid` (full self-healing report for a " +
         "build). Pass the returned locator pairs to `prepareSelfHealingPlan` " +
-        "to plan edits." +
-        NEEDS_SESSION_ID, {
+        "to plan edits.", {
         sessionId: z
             .string()
             .describe("Session ID. Mutually exclusive with buildUuid.")
@@ -501,8 +499,7 @@ export default function addSelfHealTools(server, config) {
         "[...]}`, the raw report `{healing_logs: [...]}` (with " +
         "`healed_selectors` aliasing `locators`), and snake_case keys " +
         "(`session_id`, `original_locator`, `healed_locator`, " +
-        "`healing_thought`)." +
-        NEEDS_SESSION_ID, {
+        "`healing_thought`).", {
         sessions: sessionsFieldSchema.describe("Sessions to plan edits for. See tool description for accepted shapes."),
     }, {
         title: "Prepare Self-Healing Plan",

package/dist/tools/testmanagement.js

@@ -19,7 +19,6 @@ 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.
@@ -433,40 +432,35 @@ 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." +
-        PROJECT_ID_ONLY_FOR_FOLDER, CreateProjFoldSchema.shape, {
+    tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management.", 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." +
-        NEEDS_PROJECT_ID, CreateTestCaseSchema.shape, {
+    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", 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." +
-        NEEDS_PROJECT_ID, 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.", 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." +
-        NEEDS_PROJECT_ID, 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.", 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." +
-        NEEDS_PROJECT_ID, 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.", ListFoldersSchema.shape, {
         title: "List Folders",
         readOnlyHint: true,
         openWorldHint: false,
@@ -480,39 +474,35 @@ 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." + NEEDS_PROJECT_ID, CreateTestRunSchema.shape, {
+    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management.", 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.)" +
-        NEEDS_PROJECT_ID, ListTestRunsSchema.shape, {
+    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)", 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." +
-        NEEDS_PROJECT_ID, UpdateTestRunSchema.shape, {
+    tools.updateTestRun = server.tool("updateTestRun", "Update a test run's metadata and/or add test cases to it.", 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." +
-        NEEDS_PROJECT_ID, AddTestResultSchema.shape, {
+    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API.", 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." +
-        NEEDS_PROJECT_ID, 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.", UploadFileSchema.shape, {
         title: "Upload Product Requirement File",
         readOnlyHint: false,
         openWorldHint: false,
@@ -526,47 +516,35 @@ 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." +
-        NEEDS_PROJECT_ID, 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.", 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." +
-        NEEDS_PROJECT_ID +
-        PLAN_WRITES_VIA_AGENT, 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.", 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." +
-        NEEDS_PROJECT_ID +
-        NEEDS_TEST_PLAN_ID +
-        PLAN_WRITES_VIA_AGENT, 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.", 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." +
-        NEEDS_PROJECT_ID +
-        NEEDS_TEST_PLAN_ID +
-        PLAN_WRITES_VIA_AGENT, ListSubTestPlansSchema.shape, {
+    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination.", 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." +
-        NEEDS_PROJECT_ID +
-        NEEDS_TEST_PLAN_ID +
-        PLAN_WRITES_VIA_AGENT, GetSubTestPlanSchema.shape, {
+    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs.", GetSubTestPlanSchema.shape, {
         title: "Get Sub Test Plan",
         readOnlyHint: true,
         openWorldHint: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.4.0-beta.3",
+  "version": "1.5.0-beta.10",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",
@@ -21,7 +21,8 @@
     "browserstack-mcp-server": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "capability"
   ],
   "keywords": [
     "mcp",

package/dist/tools/ask-browserstack/central-oauth.d.ts

@@ -1,120 +0,0 @@
-/**
- * Mint a BrowserStack central-OAuth JWT from the caller's username and access key.
- *
- * This replaces a shared delegation token, and the upgrade is not cosmetic.
- * `validate_delegation_token` refuses any token without `user.user_id`/`user.group_id`, so
- * what we mint here is USER-ATTESTED: Atlas sets `principal_verified=True`, takes the acting
- * user from signed claims rather than from anything we put in the request body, and reuses
- * this same JWT as its `egress_token` — so the product call a human approves runs as that
- * human, not as a shared service account.
- *
- * SECRET HYGIENE IS THE WHOLE POINT OF THIS MODULE, and Atlas's `central_oauth.py` learned
- * it the hard way: "The body can echo the credential back on some errors, so it is NOT
- * logged or raised — only the status." Neither the access key nor the minted token is ever
- * logged, returned, or put in an error message. Only a status code is.
- */
-import { Credentials } from "./egress.js";
-/**
- * BOTH PARTS ARE REQUIRED, AND THERE IS NO FALLBACK TO ANOTHER SCOPE.
- *
- * `oauth_user_profile` stays because it is what makes the pair obtainable through the
- * username+access_key flow at all. `ai_agent_notify` is what Atlas matches on
- * (`delegation.required_scope`, checked as exact membership of the token's `scopes` claim in
- * `web/oauth.py`); both halves move together with Atlas.
- *
- * THIS SCOPE MAY SIMPLY NOT BE ISSUABLE TO US, and the reasons are worth stating rather than
- * discovering. From the merged `browserstack/railsApp#175367` (2026-08-24):
- *
- *   - `ai_agent_notify` is documented there as CLIENT_ID/SECRET auth, and
- *     `USERNAME_ACCESS_KEY_ONLY_SCOPES` remains only `user_management, oauth_user_profile`.
- *     We are on the username+access_key flow, which those restrictions are not written for.
- *   - It is additionally covered by a new
- *     `APP_REGISTERED_SCOPE_REQUIRED = %w[ai_agent ai_agent_notify]` gate, requiring the
- *     calling APPLICATION to be registered for it — though that gate sits in the
- *     `client_id + client_secret` path, not ours.
- *   - railsApp defines it as the PRODUCT -> AGENT direction: "a product reporting progress
- *     back to an AI agent for work the agent dispatched." We use it in the opposite
- *     direction, as an agent -> Atlas inbound credential.
- *   - `central_ai_s2s`, which this replaces, was deliberately EXCLUDED from that new gate.
- *
- * So this is strictly more restricted than what it replaces. If the endpoint refuses it, that
- * is a PROVISIONING problem — the scope is not available to this credential type or this
- * application — and it is reported as one, naming the scope. It is never retried with a
- * different scope: a silent downgrade to a different authorization is exactly the kind of
- * thing nobody notices until it matters.
- */
-export declare const CENTRAL_SCOPE = "oauth_user_profile ai_agent_notify";
-/** What we ask for. The endpoint clamps to its own maximum, so the response wins. */
-export declare const REQUESTED_EXPIRES_IN = 3600;
-/**
- * Treat a token as stale this long before it actually expires.
- *
- * NOT the usual small skew. This token is not merely used to open the request — Atlas holds
- * it for the life of the run and re-uses it for product egress, so it has to outlive the
- * whole call, and our own `/agent` budget is already 330s. Handing out a token with 61
- * seconds left would mean a human approves a write and the egress that follows fails on an
- * expired credential, which is the exact mid-flight expiry this cache exists to prevent.
- */
-export declare const REFRESH_SKEW_MS: number;
-/** The token endpoint gets its own, much shorter budget than `/agent`. */
-export declare const TOKEN_TIMEOUT_MS = 15000;
-export interface TokenResponse {
-    status: number;
-    body: unknown;
-    /** Only when there was no response at all to speak for itself. */
-    error?: string;
-}
-export type TokenTransport = (url: string, form: Record<string, string>) => Promise<TokenResponse>;
-/**
- * Was this refusal about the SCOPE or about the CREDENTIAL?
- *
- * The two need completely different fixes — provisioning versus a password — so collapsing
- * them into one message sends someone to the wrong place entirely. Our form has five fields
- * and four of them are constants, so a refusal of the REQUEST (as opposed to the caller) can
- * only really be about the scope.
- *
- * Nothing from the body is ever surfaced; the code is used to classify and then discarded.
- */
-export declare function refusalIsAboutScope(status: number, body: unknown): boolean;
-/**
- * The ways authentication can fail, kept apart because a user cannot act on them otherwise.
- *
- * `scope refused` is a provisioning problem; `rejected` is "your credentials are wrong";
- * `unreachable` is "auth is down". A fourth — Atlas refusing a token we minted successfully —
- * is a server misconfiguration and lives in `relay.ts`, because it is discovered from
- * `/agent`. Four different fixes, so four different sentences.
- */
-export declare const AUTH_SCOPE_REFUSED_DETAIL: (status: number) => string;
-export declare const AUTH_REJECTED_DETAIL: (status: number) => string;
-export declare const AUTH_UNREACHABLE_DETAIL: string;
-/**
- * A 5xx from auth: their service is down, not your password.
- *
- * Split out because routing 5xx to `AUTH_REJECTED_DETAIL` actively misdirects the reader,
- * and did: a preprod outage returned 503 and the tool answered "Your BrowserStack
- * credentials were rejected … Check BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY",
- * sending someone to audit env vars that had worked minutes earlier. The status alone
- * settles it — OAuth2 says a bad client is 401/403 and a bad request is 400, so nothing in
- * the 5xx range is ever a statement about the caller.
- */
-export declare const AUTH_SERVER_ERROR_DETAIL: (status: number) => string;
-export declare const AUTH_UNUSABLE_DETAIL: (status: number) => string;
-/** Drop every cached token. For tests, and for a credential rotation. */
-export declare function resetTokenCache(): void;
-/**
- * The token endpoint, through `apiClient` per rules/security.md — no bare `fetch`.
- *
- * `raise_error: false` keeps the status-first contract this transport has always had: the
- * caller distinguishes a 400 scope refusal from a 401 rejection from an unreachable host,
- * so a thrown AxiosError on any non-2xx would destroy the only signal it reads.
- */
-export declare function fetchTokenTransport(timeoutMs?: number): TokenTransport;
-/** The exact form body of the `client_credentials` grant. */
-export declare function mintForm(credentials: Credentials): Record<string, string>;
-/**
- * Return a valid token, minting one only when the cache has nothing fresh.
- *
- * Minting per tool call would add a round trip to every request and make the token endpoint
- * a hot dependency of the whole surface.
- */
-export declare function mintCentralToken(url: string, credentials: Credentials, transport: TokenTransport, now?: number): Promise<string>;