@browserstack/mcp-server 1.4.0-beta.1 → 1.5.0-beta.1

package/dist/index.js

@@ -29,12 +29,9 @@ async function main() {
     await mcpServer.getInstance().connect(transport);
 }
 main().catch(console.error);
-// Ensure logs are flushed before exit. Optional-called because an exit handler must not
-// be the thing that throws: `flush` is absent from every `vi.mock("src/logger")` in the
-// suite, so any test file that loads this module used to fail the run with
-// `default.flush is not a function` depending on how vitest scheduled workers.
+// Ensure logs are flushed before exit
 process.on("exit", () => {
-    logger.flush?.();
+    logger.flush();
 });
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";

package/dist/server-factory.js

@@ -16,7 +16,7 @@ import addAppLiveTools from "./tools/applive.js";
 import addBuildInsightsTools from "./tools/build-insights.js";
 import { setupOnInitialized } from "./oninitialized.js";
 import addRCATools from "./tools/rca-agent.js";
-import addAskBrowserstackAITool from "./tools/ask-browserstack/register.js";
+import addCapabilityRegistryTools from "./tools/capability-registry/register.js";
 /**
  * Wrapper class for BrowserStack MCP Server
  * Stores a map of registered tools by name
@@ -52,10 +52,10 @@ export class BrowserStackMcpServer {
             addSelfHealTools,
             addBuildInsightsTools,
             addRCATools,
-            // Hands a plain-language task to BrowserStack's agent and relays its mid-run
-            // permission asks back to this client, so a write can be confirmed by the human
-            // sitting in front of it rather than refused for want of anyone to ask.
-            addAskBrowserstackAITool,
+            // Driven by a prebuilt index rather than hand-written per endpoint. Registers
+            // nothing (and logs why) when the artifact is absent, so a packaging problem cannot
+            // take the other products' tools down with it.
+            addCapabilityRegistryTools,
         ];
         toolAdders.forEach((adder) => {
             // Each adder now returns a Record<string, Tool>

package/dist/tools/accessibility.js

@@ -8,7 +8,6 @@ import { queryAccessibilityRAG } from "./accessiblity-utils/accessibility-rag.js
 import { getBrowserStackAuth } from "../lib/get-auth.js";
 import { elicitCredentialsIfSupported } from "../lib/elicit-credentials.js";
 import logger from "../logger.js";
-import { NEEDS_A11Y_CONFIG_ID, NEEDS_A11Y_SCAN_ID } from "./tool-handoff.js";
 function setupAuth(config) {
     const authString = getBrowserStackAuth(config);
     const [username, password] = authString.split(":");
@@ -304,8 +303,7 @@ export default function addAccessibilityTools(server, config) {
             return handleMCPError("createAccessibilityAuthConfig", server, config, error);
         }
     });
-    tools.getAccessibilityAuthConfig = server.tool("getAccessibilityAuthConfig", "Retrieve an existing authentication configuration by ID." +
-        NEEDS_A11Y_CONFIG_ID, {
+    tools.getAccessibilityAuthConfig = server.tool("getAccessibilityAuthConfig", "Retrieve an existing authentication configuration by ID.", {
         configId: z.number().describe("ID of the auth configuration to retrieve"),
     }, {
         title: "Get Accessibility Auth Config",
@@ -316,8 +314,7 @@ export default function addAccessibilityTools(server, config) {
     }, async (args) => {
         return await executeGetAuthConfig(args, server, config);
     });
-    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch accessibility issues from a completed scan with pagination support. Use cursor parameter to get subsequent pages of results." +
-        NEEDS_A11Y_SCAN_ID, {
+    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch accessibility issues from a completed scan with pagination support. Use cursor parameter to get subsequent pages of results.", {
         scanId: z
             .string()
             .describe("The scan ID from a completed accessibility scan"),

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

@@ -0,0 +1,29 @@
+/**
+ * Turn grouped caller arguments into a path, a query and a body.
+ *
+ * Arguments arrive GROUPED — {path_params, query, body} — because spec parameter names
+ * collide across locations: four tm operations declare one name in two places (`bulk-move`
+ * has `folder_id` as both a path parameter and a body field). A flat map cannot say which
+ * one is meant, which is exactly why the Python side used to rename body fields `body_*`.
+ * Grouping removes the collision AND the rename, so a caller sends the spec's own names.
+ */
+import { Capability, WireParam } from "./types.js";
+export interface GroupedArguments {
+    path_params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+}
+export interface BoundRequest {
+    path: string;
+    query: Record<string, unknown>;
+    body?: Record<string, unknown>;
+}
+/**
+ * Check one argument against its declared schema, raising a caller-safe error.
+ *
+ * Type checking is also the injection defence for path parameters: most of tm's 278 path
+ * parameters are `type: integer`, so a traversal attempt like `../../admin-v2` fails here
+ * rather than being encoded into a URL.
+ */
+export declare function coerce(value: unknown, param: WireParam): unknown;
+export declare function bind(capability: Capability, args: GroupedArguments): BoundRequest;

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

@@ -0,0 +1,134 @@
+/**
+ * Turn grouped caller arguments into a path, a query and a body.
+ *
+ * Arguments arrive GROUPED — {path_params, query, body} — because spec parameter names
+ * collide across locations: four tm operations declare one name in two places (`bulk-move`
+ * has `folder_id` as both a path parameter and a body field). A flat map cannot say which
+ * one is meant, which is exactly why the Python side used to rename body fields `body_*`.
+ * Grouping removes the collision AND the rename, so a caller sends the spec's own names.
+ */
+import { InvocationError } from "./index-loader.js";
+/**
+ * Check one argument against its declared schema, raising a caller-safe error.
+ *
+ * Type checking is also the injection defence for path parameters: most of tm's 278 path
+ * parameters are `type: integer`, so a traversal attempt like `../../admin-v2` fails here
+ * rather than being encoded into a URL.
+ */
+export function coerce(value, param) {
+    const expected = param.type;
+    if (expected === "object" || expected === "array") {
+        // An opaque body object is passed through as given: the spec does not describe its
+        // fields, so validating or reshaping it would mean inventing a contract.
+        if (expected === "object" &&
+            (typeof value !== "object" || value === null || Array.isArray(value))) {
+            throw new InvocationError(`'${param.name}' must be an object`);
+        }
+        if (expected === "array" && !Array.isArray(value)) {
+            throw new InvocationError(`'${param.name}' must be a list`);
+        }
+        return value;
+    }
+    if (expected === "integer" || expected === "number") {
+        const parsed = Number(String(value).trim());
+        if (!Number.isFinite(parsed)) {
+            throw new InvocationError(`'${param.name}' must be a number`);
+        }
+        return expected === "integer" ? Math.trunc(parsed) : parsed;
+    }
+    if (expected === "boolean") {
+        if (typeof value === "boolean")
+            return value;
+        const text = String(value).trim().toLowerCase();
+        if (["true", "1", "yes"].includes(text))
+            return true;
+        if (["false", "0", "no"].includes(text))
+            return false;
+        throw new InvocationError(`'${param.name}' must be true or false`);
+    }
+    const text = String(value);
+    if (param.values && param.values.length > 0) {
+        const allowed = param.values.map((v) => String(v));
+        if (!allowed.includes(text)) {
+            throw new InvocationError(`'${param.name}' must be one of: ${allowed.join(", ")}`);
+        }
+    }
+    return text;
+}
+/** Place a value at a JSON-pointer-ish path, creating the objects on the way. */
+function place(root, pointer, value) {
+    const segments = pointer.split("/").filter((segment) => segment !== "");
+    let cursor = root;
+    for (const segment of segments.slice(0, -1)) {
+        const next = cursor[segment];
+        if (typeof next !== "object" || next === null || Array.isArray(next)) {
+            cursor[segment] = {};
+        }
+        cursor = cursor[segment];
+    }
+    cursor[segments[segments.length - 1]] = value;
+}
+const GROUPS = [
+    { group: "path_params", declared: "path_params" },
+    { group: "query", declared: "query" },
+    { group: "body", declared: "body" },
+];
+export function bind(capability, args) {
+    let path = capability.path;
+    const query = {};
+    const body = {};
+    for (const { group, declared } of GROUPS) {
+        const supplied = args[group] || {};
+        if (typeof supplied !== "object" ||
+            supplied === null ||
+            Array.isArray(supplied)) {
+            throw new InvocationError(`${group} must be an object of name -> value`);
+        }
+        const params = capability[declared] || [];
+        const byName = new Map(params.map((param) => [param.name, param]));
+        // Unknown arguments are an error rather than being dropped: silently ignoring a
+        // misspelled filter would return a larger result set that looks like a correct answer.
+        const unknown = Object.keys(supplied).filter((name) => !byName.has(name));
+        if (unknown.length > 0) {
+            throw new InvocationError(`unknown ${group}: ${unknown.sort().join(", ")}. accepted: ` +
+                `${[...byName.keys()].sort().join(", ") || "none"}`);
+        }
+        for (const [name, raw] of Object.entries(supplied)) {
+            const param = byName.get(name);
+            const value = coerce(raw, param);
+            if (group === "path_params") {
+                // Encode with nothing exempt: a `/` inside a path value would otherwise rewrite the
+                // route. Schema checking already stops this for integer ids; this covers strings.
+                path = path.replaceAll(`{${name}}`, encodeURIComponent(String(value)));
+            }
+            else if (group === "body") {
+                place(body, param.json_path || `/${name}`, value);
+            }
+            else {
+                query[name] = value;
+            }
+        }
+    }
+    // `required` is enforced for BODY as well as path. It was path-only on the Python side at
+    // first, so a missing required body field passed silently and the product answered with a
+    // 4xx that read like the caller's fault.
+    const missing = [];
+    for (const { group, declared } of GROUPS) {
+        if (group === "query")
+            continue;
+        const supplied = args[group] || {};
+        for (const param of capability[declared] ||
+            []) {
+            if (param.required && !(param.name in supplied))
+                missing.push(param.name);
+        }
+    }
+    if (missing.length > 0) {
+        throw new InvocationError(`missing required parameter(s): ${missing.sort().join(", ")}`);
+    }
+    const leftover = path.match(/\{[a-z_]+\}/gi);
+    if (leftover) {
+        throw new InvocationError(`path placeholder(s) not supplied: ${leftover.join(", ")}`);
+    }
+    return { path, query, body: Object.keys(body).length > 0 ? body : undefined };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Where the index comes from, and where each product lives.
+ *
+ * A product may DECLARE its host in its own index file (`<product>.base_url`, authored in
+ * the harness's product.yaml and carried through by the export). That is the default, not
+ * the last word: config overrides it, and for a region-sharded product account discovery
+ * outranks it — see `resolveBaseUrl`. The same artifact therefore still ships to every
+ * environment, because anything environment- or account-specific is resolved here.
+ */
+import { BrowserStackConfig } from "../../lib/types.js";
+import { HostSource } from "./discovery.js";
+import { Transport } from "./egress.js";
+/**
+ * The environment this DEPLOYMENT points at, e.g. "preprod".
+ *
+ * Process-level on purpose, and the distinction from region matters: an environment is a
+ * property of the deployment (this instance talks to preprod), whereas a REGION is a
+ * property of the account (this user's data lives in EU). That is why region discovery is
+ * per request and never cached under REMOTE_MCP, while the environment is read once here.
+ */
+export declare function selectedEnvironment(): string;
+/** True when this product's host is account-specific and must be discovered per call. */
+export declare function isRegionSharded(product: string, source?: HostSource): boolean;
+/**
+ * Resolve a product's host.
+ *
+ * Atlas resolves: an explicit per-session override, then the host for the session's
+ * environment (`harness.extra_environments[env][product]`), then the profile's own
+ * `base_url`. The same rungs, in the same order, with one addition:
+ *
+ *   1. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>            explicit, environment-agnostic
+ *   2. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>_<ENV>      this environment's host
+ *   3. CAPABILITY_REGISTRY_BASE_URLS {product:{env:url}} the same, as one map
+ *   4. account discovery — the index's `base_urls`, probed
+ *   5. the single host declared in the index, `base_url`
+ *   6. refuse, by name
+ *
+ * DISCOVERY OUTRANKS THE DECLARED HOST, which is where this departs from Atlas. A declared
+ * host is one fixed origin, so for a region-sharded product it would send every account
+ * outside the default region to the wrong host — a failure that only shows up on those
+ * accounts, and so passes any test run from inside the default one. Discovery answers with
+ * the region the account is actually on; `base_url` is the fallback for when the probe
+ * cannot answer at all.
+ *
+ * Refusing rather than guessing is deliberate: a guessed host fails as a DNS error or a 404
+ * that reads like the caller's problem, when it is our missing configuration.
+ */
+export declare function resolveBaseUrl(product: string, config: BrowserStackConfig, source?: HostSource, transport?: Transport): Promise<string>;
+/**
+ * Locate the artifact(s).
+ *
+ * ONE FILE PER PRODUCT, so this returns a list. Explicit env wins; otherwise look for a
+ * `capability/` directory beside the compiled module and at the package root, then fall
+ * back to a single `capability-index.json` for the pre-release layout. The package-root
+ * candidates exist because `tsc` compiles TS and does not copy JSON into `dist`.
+ *
+ * Returns an empty list when nothing is found — the caller logs that and registers no
+ * tools, rather than throwing.
+ */
+export declare function indexPaths(): string[];
+/** Off by default is wrong for a shipped feature, but a kill switch is not. */
+export declare function isEnabled(): boolean;

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

@@ -0,0 +1,218 @@
+/**
+ * Where the index comes from, and where each product lives.
+ *
+ * A product may DECLARE its host in its own index file (`<product>.base_url`, authored in
+ * the harness's product.yaml and carried through by the export). That is the default, not
+ * the last word: config overrides it, and for a region-sharded product account discovery
+ * outranks it — see `resolveBaseUrl`. The same artifact therefore still ships to every
+ * environment, because anything environment- or account-specific is resolved here.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import logger from "../../logger.js";
+import { getTMBaseURL } from "../../lib/tm-base-url.js";
+import { discoverBaseUrl } from "./discovery.js";
+import { fetchTransport } from "./egress.js";
+import { FLAT_SUFFIX, INDEX_FILE, InvocationError } from "./index-loader.js";
+/**
+ * The environment this DEPLOYMENT points at, e.g. "preprod".
+ *
+ * Process-level on purpose, and the distinction from region matters: an environment is a
+ * property of the deployment (this instance talks to preprod), whereas a REGION is a
+ * property of the account (this user's data lives in EU). That is why region discovery is
+ * per request and never cached under REMOTE_MCP, while the environment is read once here.
+ */
+export function selectedEnvironment() {
+    return (process.env.CAPABILITY_REGISTRY_ENV || "").trim();
+}
+/** product -> env -> host, the analogue of Atlas's `harness.extra_environments`. */
+function environmentMap() {
+    const raw = process.env.CAPABILITY_REGISTRY_BASE_URLS;
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        // A malformed map must not silently mean "no override" — that would send a preprod
+        // deployment at production.
+        throw new InvocationError("CAPABILITY_REGISTRY_BASE_URLS is not valid JSON; expected {product: {env: url}}");
+    }
+}
+/**
+ * Built-in host discovery, for a product whose regional hosts are not in its index yet.
+ *
+ * The general mechanism lives in `discovery.ts` and is driven by the index's `base_urls`.
+ * This map is the bridge for products that predate that: tm's hosts are still hardcoded in
+ * `lib/tm-base-url.ts` and shared with the hand-written Test Management tools. Once tm's
+ * product.yaml declares `base_urls`, this entry can go and nothing else changes.
+ */
+const BUILTIN_DISCOVERY = {
+    tm: getTMBaseURL,
+};
+/** True when this product's host is account-specific and must be discovered per call. */
+export function isRegionSharded(product, source) {
+    return (source?.base_urls?.length ?? 0) > 1 || product in BUILTIN_DISCOVERY;
+}
+function credentialsFrom(config) {
+    return {
+        username: config["browserstack-username"],
+        accessKey: config["browserstack-access-key"],
+    };
+}
+/**
+ * Resolve a product's host.
+ *
+ * Atlas resolves: an explicit per-session override, then the host for the session's
+ * environment (`harness.extra_environments[env][product]`), then the profile's own
+ * `base_url`. The same rungs, in the same order, with one addition:
+ *
+ *   1. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>            explicit, environment-agnostic
+ *   2. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>_<ENV>      this environment's host
+ *   3. CAPABILITY_REGISTRY_BASE_URLS {product:{env:url}} the same, as one map
+ *   4. account discovery — the index's `base_urls`, probed
+ *   5. the single host declared in the index, `base_url`
+ *   6. refuse, by name
+ *
+ * DISCOVERY OUTRANKS THE DECLARED HOST, which is where this departs from Atlas. A declared
+ * host is one fixed origin, so for a region-sharded product it would send every account
+ * outside the default region to the wrong host — a failure that only shows up on those
+ * accounts, and so passes any test run from inside the default one. Discovery answers with
+ * the region the account is actually on; `base_url` is the fallback for when the probe
+ * cannot answer at all.
+ *
+ * Refusing rather than guessing is deliberate: a guessed host fails as a DNS error or a 404
+ * that reads like the caller's problem, when it is our missing configuration.
+ */
+export async function resolveBaseUrl(product, config, source, transport) {
+    const key = product.toUpperCase();
+    const environment = selectedEnvironment();
+    const trim = (url) => url.replace(/\/$/, "");
+    const explicit = process.env[`CAPABILITY_REGISTRY_BASE_URL_${key}`];
+    if (explicit)
+        return trim(explicit);
+    if (environment) {
+        const suffixed = process.env[`CAPABILITY_REGISTRY_BASE_URL_${key}_${environment.toUpperCase()}`];
+        if (suffixed)
+            return trim(suffixed);
+        const mapped = environmentMap()[product]?.[environment];
+        if (mapped)
+            return trim(String(mapped));
+        // An environment was named and nothing defines its host. Falling back to discovery or
+        // to the declared production host here would send a preprod deployment at production,
+        // silently.
+        throw new InvocationError(`environment '${environment}' has no host for product '${product}'. Set ` +
+            `CAPABILITY_REGISTRY_BASE_URL_${key}_${environment.toUpperCase()} or add it to ` +
+            `CAPABILITY_REGISTRY_BASE_URLS.`);
+    }
+    /** A declared host is a better answer than none — but only after discovery has tried. */
+    const fallback = (error) => {
+        if (!source?.base_url)
+            throw error;
+        logger.warn("host discovery failed for product %s (%s); falling back to the declared host %s", product, error instanceof Error ? error.message : String(error), source.base_url);
+        return trim(source.base_url);
+    };
+    if ((source?.base_urls?.length ?? 0) > 0) {
+        try {
+            return await discoverBaseUrl(product, source, credentialsFrom(config), transport || fetchTransport());
+        }
+        catch (error) {
+            return fallback(error);
+        }
+    }
+    const builtin = BUILTIN_DISCOVERY[product];
+    if (builtin) {
+        try {
+            return trim(await builtin(config));
+        }
+        catch (error) {
+            return fallback(error);
+        }
+    }
+    if (source?.base_url)
+        return trim(source.base_url);
+    throw new InvocationError(`no host is configured for product '${product}': its index declares none and there ` +
+        `is no override. Set CAPABILITY_REGISTRY_BASE_URL_${key}.`);
+}
+/** The directory holding one subdirectory per product. */
+const INDEX_ROOT = "capability";
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every product index under one directory, sorted so load order is stable.
+ *
+ * `<product>.capability-index.json` is the stored layout — the export publishes that exact
+ * filename, so an artifact drops in unrenamed. `<product>/index.json` is also accepted, so
+ * a checkout using the earlier nested layout keeps working.
+ */
+function filesIn(directory) {
+    if (!isDirectory(directory))
+        return [];
+    const found = [];
+    for (const entry of readdirSync(directory).sort()) {
+        const path = join(directory, entry);
+        if (entry.endsWith(FLAT_SUFFIX)) {
+            found.push(path);
+        }
+        else if (isDirectory(path) && existsSync(join(path, INDEX_FILE))) {
+            found.push(join(path, INDEX_FILE));
+        }
+    }
+    return found;
+}
+/**
+ * Locate the artifact(s).
+ *
+ * ONE FILE PER PRODUCT, so this returns a list. Explicit env wins; otherwise look for a
+ * `capability/` directory beside the compiled module and at the package root, then fall
+ * back to a single `capability-index.json` for the pre-release layout. The package-root
+ * candidates exist because `tsc` compiles TS and does not copy JSON into `dist`.
+ *
+ * Returns an empty list when nothing is found — the caller logs that and registers no
+ * tools, rather than throwing.
+ */
+export function indexPaths() {
+    const configuredFile = process.env.CAPABILITY_REGISTRY_INDEX;
+    if (configuredFile) {
+        return existsSync(configuredFile) ? [resolve(configuredFile)] : [];
+    }
+    const configuredDir = process.env.CAPABILITY_REGISTRY_INDEX_DIR;
+    if (configuredDir)
+        return filesIn(resolve(configuredDir));
+    const here = dirname(fileURLToPath(import.meta.url));
+    const roots = [
+        here,
+        join(here, "..", "..", ".."), // dist/ or src/ -> package root
+        join(here, "..", "..", "..", ".."),
+    ];
+    for (const root of roots) {
+        // `capabilities` (plural) is the layout this shipped with before the move to
+        // `capability/<product>/index.json`; still read so an existing checkout keeps working.
+        for (const name of [INDEX_ROOT, "capabilities"]) {
+            const found = filesIn(join(root, name));
+            if (found.length > 0)
+                return found;
+        }
+        const loose = filesIn(root);
+        if (loose.length > 0)
+            return loose;
+    }
+    for (const root of roots) {
+        const legacy = join(root, "capability-index.json");
+        if (existsSync(legacy))
+            return [legacy];
+    }
+    return [];
+}
+/** Off by default is wrong for a shipped feature, but a kill switch is not. */
+export function isEnabled() {
+    return ((process.env.CAPABILITY_REGISTRY_DISABLED || "").toLowerCase() !== "true");
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Which regional host does THIS account live on?
+ *
+ * Generalised from `lib/tm-base-url.ts`, which asks the question for Test Management by
+ * walking test-management{,-eu,-in}.browserstack.com and keeping the one that authenticates.
+ * The mechanism is not tm-specific — any product sharded by region answers the same way —
+ * so the candidate hosts move into the product's own index (`base_urls`) and this module
+ * performs the walk for all of them.
+ *
+ * A PROBE, NOT A LOOKUP. An account's data lives in exactly one region and the other regions
+ * reject its credentials, so the right host identifies itself. There is no mapping table to
+ * keep in sync, which is the point: a table would go stale silently.
+ */
+import { Credentials, Transport } from "./egress.js";
+import { Capability, ProductIndex } from "./types.js";
+/** What the resolver needs from a product's index to find its host. */
+export type HostSource = Pick<ProductIndex, "base_url" | "base_urls" | "probe_path" | "auth"> & {
+    capabilities?: Capability[];
+};
+/** Exposed for tests; a long-lived process must not pin a stale region forever. */
+export declare function clearDiscoveryCache(): void;
+/**
+ * Pick the endpoint to probe with.
+ *
+ * An explicit `probe_path` in the index wins. Otherwise derive one, and derive it
+ * CONSERVATIVELY — the probe reads a 2xx as "this is the account's region", so an endpoint
+ * that can fail for a reason unrelated to region would walk straight past the right host:
+ *
+ *  * reads only, and never with a path placeholder — there is no id to supply yet;
+ *  * no required query parameters, for the same reason;
+ *  * paginated, because a paged listing is a primary collection by construction;
+ *  * nothing under /admin, which 403s for an ordinary user;
+ *  * shortest path, to prefer the root collection over its variants.
+ *
+ * For tm this lands on `/api/v1/projects`, the same family as the hand-written probe.
+ */
+export declare function probePath(source: HostSource): string | undefined;
+/**
+ * Return the first candidate host that accepts the caller's credentials.
+ *
+ * Probed with the SAME auth the real calls use (`Api-Token`), not a second scheme, so a
+ * host that answers here is one that will answer for the invocation that follows.
+ */
+export declare function discoverBaseUrl(product: string, source: HostSource, credentials: Credentials, transport: Transport): Promise<string>;

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

@@ -0,0 +1,99 @@
+/**
+ * Which regional host does THIS account live on?
+ *
+ * Generalised from `lib/tm-base-url.ts`, which asks the question for Test Management by
+ * walking test-management{,-eu,-in}.browserstack.com and keeping the one that authenticates.
+ * The mechanism is not tm-specific — any product sharded by region answers the same way —
+ * so the candidate hosts move into the product's own index (`base_urls`) and this module
+ * performs the walk for all of them.
+ *
+ * A PROBE, NOT A LOOKUP. An account's data lives in exactly one region and the other regions
+ * reject its credentials, so the right host identifies itself. There is no mapping table to
+ * keep in sync, which is the point: a table would go stale silently.
+ */
+import appConfig from "../../config.js";
+import logger from "../../logger.js";
+import { authHeaders } from "./egress.js";
+import { InvocationError } from "./index-loader.js";
+/**
+ * Cached per product AND per user, so the answer cannot cross accounts.
+ *
+ * `lib/tm-base-url.ts` disables its cache entirely under REMOTE_MCP because a process-wide
+ * single slot would serve the first user's region to everyone after them. Keying by user
+ * fixes that by construction, so the cache stays useful in remote mode too.
+ */
+const cache = new Map();
+/** Exposed for tests; a long-lived process must not pin a stale region forever. */
+export function clearDiscoveryCache() {
+    cache.clear();
+}
+/**
+ * Pick the endpoint to probe with.
+ *
+ * An explicit `probe_path` in the index wins. Otherwise derive one, and derive it
+ * CONSERVATIVELY — the probe reads a 2xx as "this is the account's region", so an endpoint
+ * that can fail for a reason unrelated to region would walk straight past the right host:
+ *
+ *  * reads only, and never with a path placeholder — there is no id to supply yet;
+ *  * no required query parameters, for the same reason;
+ *  * paginated, because a paged listing is a primary collection by construction;
+ *  * nothing under /admin, which 403s for an ordinary user;
+ *  * shortest path, to prefer the root collection over its variants.
+ *
+ * For tm this lands on `/api/v1/projects`, the same family as the hand-written probe.
+ */
+export function probePath(source) {
+    if (source.probe_path)
+        return source.probe_path;
+    const usable = (source.capabilities || []).filter((capability) => capability.mode === "read" &&
+        capability.paginated &&
+        !capability.path.includes("{") &&
+        !capability.path.includes("/admin") &&
+        !(capability.query || []).some((param) => param.required));
+    usable.sort((a, b) => a.path.length - b.path.length || a.path.localeCompare(b.path));
+    return usable[0]?.path;
+}
+/**
+ * Return the first candidate host that accepts the caller's credentials.
+ *
+ * Probed with the SAME auth the real calls use (`Api-Token`), not a second scheme, so a
+ * host that answers here is one that will answer for the invocation that follows.
+ */
+export async function discoverBaseUrl(product, source, credentials, transport) {
+    const candidates = (source.base_urls || []).map((url) => url.replace(/\/$/, ""));
+    if (candidates.length === 0) {
+        throw new InvocationError(`product '${product}' declares no base_urls to probe`);
+    }
+    // One candidate is not a region question; skip the round trip.
+    if (candidates.length === 1)
+        return candidates[0];
+    const key = `${product}\n${credentials.username}`;
+    const cached = cache.get(key);
+    if (cached) {
+        logger.debug("using cached %s host for this account: %s", product, cached);
+        return cached;
+    }
+    const path = probePath(source);
+    if (!path) {
+        throw new InvocationError(`product '${product}' declares several base_urls but no endpoint to probe them with; ` +
+            `set probe_path in its index`);
+    }
+    // The same scheme the invocation will use, so a host that answers here answers there.
+    const headers = authHeaders(credentials, source.auth);
+    const failures = [];
+    for (const candidate of candidates) {
+        const response = await transport("GET", `${candidate}${path}`, headers, {});
+        if (response.status >= 200 && response.status < 300) {
+            // Under REMOTE_MCP the key already carries the user, so this is safe to keep.
+            if (!appConfig.REMOTE_MCP || credentials.username)
+                cache.set(key, candidate);
+            logger.info("resolved %s to %s for this account", product, candidate);
+            return candidate;
+        }
+        failures.push(`${candidate}: HTTP ${response.status || "unreachable"}`);
+    }
+    // Every region refused. Saying which, and with what, is the difference between a
+    // debuggable report and "it did not work".
+    throw new InvocationError(`could not determine which region this account's ${product} lives on. Probed ${path} ` +
+        `on each host — ${failures.join("; ")}`);
+}