@browserstack/mcp-server 1.5.1-beta.2 → 2.0.0-beta.1

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

@@ -0,0 +1,341 @@
+/**
+ * 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. */
+/**
+ * The constraints a parameter may declare beyond its type.
+ *
+ * ALL OPTIONAL, and absent means unchecked. The released artifact carries none of these
+ * yet — tm's spec holds 59 `format`, 50 `default`, 23 `minimum`, 12 `maximum`, 10
+ * `minItems`, 7 `maxItems`, 4 `minLength`, 3 `pattern` and 2 `maxLength` that the export
+ * currently drops — so this ships inert and starts working the moment the export carries
+ * them. An older index must keep binding exactly as it does today.
+ */
+export interface WireConstraints {
+    /** Numbers. `multipleOf` is checked on the coerced number, not the raw string. */
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    /** Strings. `pattern` is an unanchored regex, compiled with `u` for `\p{…}` classes. */
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    /** Arrays. */
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    /**
+     * The value the product uses when the field is omitted.
+     *
+     * PUBLISHED, NOT INJECTED. Telling a caller the default is what stops the redundant send;
+     * filling it in here would put a value on the wire that the caller never chose, and pin
+     * a server-side default that is free to change. Omission and "explicitly the default" are
+     * different requests, and only the product knows whether that difference matters.
+     */
+    default?: unknown;
+}
+/** One field inside an array item or a nested object — same constraints, one level down. */
+export interface WireField extends WireConstraints {
+    name: string;
+    type: string;
+    required?: true;
+    values?: unknown[];
+}
+export interface WireParam extends WireConstraints {
+    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?: WireField[];
+    /**
+     * 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[];
+    /**
+     * Withheld from this surface entirely.
+     *
+     * A DISABLED CAPABILITY DOES NOT EXIST for searchCapability, describeCapability,
+     * describeEntity or listProducts — it is filtered out when the registry loads, so no
+     * reader downstream has to remember to check. `invokeCapability` is the one exception:
+     * an exact-name or exact-endpoint invoke answers `capability_disabled` rather than
+     * `unknown_capability`, so a caller that already held the handle learns the absence is
+     * deliberate instead of hunting for a synonym.
+     *
+     * NO REASON IS CARRIED. It was a `boolean | string` union whose string half was the
+     * explanation, and it paid for itself nowhere: one consumer, on a path the flag itself
+     * makes rare, at 1216 bytes of duplicated prose in an artifact that ships to public npm.
+     * Why a capability is withheld is documentation — it belongs in the notes beside the
+     * decision, not in four copies inside the index.
+     *
+     * FAILS CLOSED. Any truthy value disables, not just `=== true`. A flag whose only job is
+     * suppression must not be ignored for arriving in an unexpected shape.
+     */
+    disabled?: boolean;
+    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;
+    /**
+     * One line saying what this entity IS. Rides on `listProducts`, next to the aliases.
+     *
+     * Aliases route; they do not define. `version -> history, revision, version-history`
+     * tells a caller which words land here and nothing about whether that is the versioning
+     * of a test case or of a project. Without this line the only way to find out is
+     * `describeEntity`, once per entity — 19 calls at ~1.4KB for tm, against ~1.6KB to
+     * answer it for all of them at once.
+     *
+     * Capped at 140 characters by the build, and dropped rather than truncated when longer.
+     * Often absent: a product that has not authored these emits none (loadtesting has 0 of
+     * 9 today), and absence means "unwritten", never an error.
+     */
+    description?: 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;
+     * "oauth2" exchanges the caller's credentials for a JWT and sends `Authorization: Bearer`.
+     *
+     * Each value fixes BOTH where the value comes from and how it is presented. Only `apiKey`
+     * carries `in`/`name`, because it is the only one with no convention for where it goes —
+     * RFC 6750 settles that for a bearer token, which is why OpenAPI's own `oauth2` scheme has
+     * no location fields either. `in`, `name` and `template` are REFUSED on `oauth2` rather
+     * than ignored, so an author who writes one gets an error instead of a silent 401.
+     */
+    type: "apiKey" | "http" | "oauth2";
+    /** 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;
+    /** apiKey/http only. Defaults to `{username}:{access_key}`. */
+    template?: string;
+    /**
+     * oauth2 only: override the endpoint the JWT is minted at.
+     *
+     * Optional, and most products want the default. Bounded by an allowlist in `oauth.ts` —
+     * this field decides where the caller's credentials are POSTed, and an index is a data
+     * file that ships to public npm.
+     */
+    token_url?: string;
+    /**
+     * oauth2 only: override the scope set. Order is not significant; it is sorted and deduped
+     * before it reaches the grant or the token cache.
+     *
+     * There is deliberately no `flow` beside this. The server implements one grant, so a field
+     * with one legal value could distinguish nothing — and an unvalidated one would read as
+     * though it selected behaviour while selecting nothing.
+     */
+    scopes?: string[];
+}
+export interface ProductIndex {
+    summary: string;
+    /**
+     * Words that route to this product but are not the name of anything in it.
+     *
+     * The entity names and their aliases are what a product CONTAINS; this is what its users
+     * CALL it when they ask for something. `flaky` is the clearest case: both indexes talk
+     * about flakiness and neither models it as an entity, so the word was invisible to
+     * routing and a question about it read as naming no product at all. The other half is
+     * the reverse — `workspace`, `team`, `setting` and `suite` belong to both products and
+     * happen to be modelled by one, which let an incidental word settle a question it had no
+     * business settling. Listing a word here is a claim about vocabulary only; it never adds
+     * a capability and never widens a search.
+     */
+    routing_terms?: 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/testmanagement.js

@@ -19,7 +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";
+import { NEEDS_PROJECT_ID, NEEDS_TEST_PLAN_ID, PLAN_WRITES_VIA_CAPABILITIES, 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.
@@ -536,7 +536,7 @@ export default function addTestManagementTools(server, config) {
     }, (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, {
+        PLAN_WRITES_VIA_CAPABILITIES, ListTestPlansSchema.shape, {
         title: "List Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
@@ -546,7 +546,7 @@ export default function addTestManagementTools(server, config) {
     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, {
+        PLAN_WRITES_VIA_CAPABILITIES, GetTestPlanSchema.shape, {
         title: "Get Test Plan",
         readOnlyHint: true,
         openWorldHint: false,
@@ -556,7 +556,7 @@ export default function addTestManagementTools(server, config) {
     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, {
+        PLAN_WRITES_VIA_CAPABILITIES, ListSubTestPlansSchema.shape, {
         title: "List Sub Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
@@ -566,7 +566,7 @@ export default function addTestManagementTools(server, config) {
     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, {
+        PLAN_WRITES_VIA_CAPABILITIES, GetSubTestPlanSchema.shape, {
         title: "Get Sub Test Plan",
         readOnlyHint: true,
         openWorldHint: false,

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

@@ -8,7 +8,10 @@
  * 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.
+ * predictable than anything that has to reason its way there. When no tool here can, point
+ * at the CAPABILITY FUNCTIONS: they reach the product's own API surface, so they answer the
+ * id question directly. Name them as a group, never individually — which function to call
+ * is their own business, and a name written here goes stale the moment one is renamed.
  *
  * 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
@@ -35,21 +38,21 @@ 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.
+ * `getTestPlan`, `listSubTestPlans`, `getSubTestPlan` and nothing else. The capability functions can do them
+ * (Test Management's own API covers creating, updating, cloning and deleting a plan, and
+ * linking or unlinking its runs), 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.
+ * inviting the model to route plan work elsewhere 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.
+ * Caveat worth knowing: a capability write is pinned to human approval, so this path only
+ * completes on a client that can show a prompt. On one that cannot, the intended write is
+ * refused rather than performed.
  */
-export declare const PLAN_WRITES_VIA_AGENT: string;
+export declare const PLAN_WRITES_VIA_CAPABILITIES: string;
 /** A build id comes from either build-lookup tool. */
 export declare const NEEDS_BUILD_ID: string;
 /**

package/dist/tools/tool-handoff.js

@@ -8,7 +8,10 @@
  * 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.
+ * predictable than anything that has to reason its way there. When no tool here can, point
+ * at the CAPABILITY FUNCTIONS: they reach the product's own API surface, so they answer the
+ * id question directly. Name them as a group, never individually — which function to call
+ * is their own business, and a name written here goes stale the moment one is renamed.
  *
  * 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
@@ -21,8 +24,8 @@
  */
 /** 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.";
+    "have one, use the capability functions to list the Test Management projects, then " +
+    "retry this tool with the identifier they return.";
 /** 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.`;
@@ -34,30 +37,30 @@ export function needsIdFrom(idLabel, sourceTool) {
  * "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.';
+    "needs that project's identifier (PR-*); no tool here lists projects, so use the " +
+    "capability functions to look it up.";
 /** 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.
+ * `getTestPlan`, `listSubTestPlans`, `getSubTestPlan` and nothing else. The capability functions can do them
+ * (Test Management's own API covers creating, updating, cloning and deleting a plan, and
+ * linking or unlinking its runs), 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.
+ * inviting the model to route plan work elsewhere 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.
+ * Caveat worth knowing: a capability write is pinned to human approval, so this path only
+ * completes on a client that can show a prompt. On one that cannot, the intended write is
+ * refused rather than performed.
  */
-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.";
+export const PLAN_WRITES_VIA_CAPABILITIES = " Creating a test plan or sub-plan, and linking or unlinking test runs on one, are not " +
+    "available as tools here: use the capability functions, which reach Test Management's " +
+    "own API for these operations. They ask 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");
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.5.1-beta.2",
+  "version": "2.0.0-beta.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",
@@ -15,13 +15,20 @@
     "dev": "tsx watch --clear-screen=false src/index.ts",
     "test": "vitest run",
     "lint": "eslint . --ext .ts",
-    "format": "prettier --write \"src/**/*.ts\""
+    "format": "prettier --write \"src/**/*.ts\"",
+    "check:contract": "python3 scripts/check-contract.py capability/tm.capability-index.json --baseline scripts/contract-baseline/tm.json --quiet",
+    "eval:index": "tsx scripts/eval-index.mts",
+    "seed:live": "tsx scripts/seed-live.mts",
+    "seed:live:tra": "tsx scripts/seed-live-tra.mts",
+    "plan:tests": "tsx scripts/plan-capability-tests.mts",
+    "replay:live": "tsx scripts/replay-live.mts"
   },
   "bin": {
     "browserstack-mcp-server": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "capability"
   ],
   "keywords": [
     "mcp",