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

package/README.md

@@ -43,7 +43,7 @@ Click on the buttons below to install MCP in your respective IDE:
 
 > **Note:** The hosted Remote MCP server (`mcp.browserstack.com`) is now fully stateless over Streamable HTTP — any Streamable-HTTP client (Claude, Cursor, VS Code, ChatGPT) connects with no configuration change.
 
-#### Note : Ensure you are using Node version >= `18.0` 
+#### Note : Ensure you are using Node version >= `20.9` 
 - Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
 - To Upgrade Node :
 - 1. On macOS `(Homebrew) - brew update && brew upgrade node  or if using (nvm) - nvm install 22.15.0 && nvm use 22.15.0 && nvm alias default 22.15.0`
@@ -158,7 +158,7 @@ Generate test cases from PRDs, convert manual tests to low-code automation, and
 ## 🛠️ Installation
 
 ### 📋 Prerequisites for MCP Setup
-#### Note : Ensure you are using Node version >= `18.0` 
+#### Note : Ensure you are using Node version >= `20.9` 
 - Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
    
 ### **One Click MCP Setup**
@@ -178,7 +178,7 @@ Click on the buttons below to install MCP in your respective IDE:
 
    - Once you have an account (and purchased appropriate plan), note down your `username` and `access_key` from [Account Settings](https://www.browserstack.com/accounts/profile/details).
 
-2. #### Note : Ensure you are using Node version >= `18.0` 
+2. #### Note : Ensure you are using Node version >= `20.9` 
     - Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
    
 
@@ -292,9 +292,11 @@ Select the “Installed” tab. Click the “Configure MCP Servers” button at
    }
    ```
 
+> **File & app uploads:** tools that upload a local file/app (`uploadProductRequirementFile`, `takeAppScreenshot`, `runAppTestsOnBrowserStack`, `runAppLiveSession`) require the `MCP_UPLOAD_BASE_DIR` env var set to a directory containing those files; uploads are restricted to it.
+
 ### 💡 List of BrowserStack MCP Tools
 
-As of now we support 44 tools.
+As of now we support 46 tools.
 
 > **Remote MCP note:** Tools marked _(not available in Remote MCP)_ rely on local file/process state and are disabled in the multi-tenant [Remote MCP Server](#-remote-mcp-server). They are available in the local (npx) setup.
 
@@ -426,18 +428,25 @@ As of now we support 44 tools.
   Get screenshots from Automate session ID abc123xyz for my desktop test run
   ```
 
+ 18. `listSessions` — List the sessions in an Automate/App Automate build. Each record carries `sessionId`, `name`, `status`, `os`, `osVersion`, `browser`, `device`, `browserUrl` (dashboard link), and `videoUrl`, with optional `limit` / `offset` paging and a client-side `status` filter. Takes either the **hashed** build ID from the dashboard URL or the observability build id returned by `getBuildId` / `listBuildId` — an observability id is resolved to the hashed id automatically via the build's sessions. Returned `sessionId` values work with `getFailureLogs`, `fetchAutomationScreenshots`, and `fetchSelfHealedSelectors`.
+  **Prompt example**
+
+  ```text
+  List sessions for Automate hashed build ID <hashed build id>
+  ```
+
 ---
 
 ## 🔍 Observability
 
- 18. `getFailureLogs` — Retrieve error logs for Automate/App Automate sessions (optionally by Build ID for App Automate).
+ 19. `getFailureLogs` — Retrieve error logs for Automate/App Automate sessions. App Automate log endpoints are build-scoped, so a hashed build ID is required there — pass one if you have it, otherwise it is resolved from the session automatically.
   **Prompt example**
 
   ```text
-  Get the error logs from the session ID: 21a864032a7459f1e7634222249b316759d6827f, Build ID: dt7ung4wmjittzff8kksrjadjax9gzvbscoyf9qn of App Automate test session
+  Get the Appium logs for App Automate session ID <session id>
   ```
 
- 19. `fetchBuildInsights` — Fetch insights about a BrowserStack build by combining build details and quality-gate results.
+ 20. `fetchBuildInsights` — Fetch insights about a BrowserStack build by combining build details and quality-gate results. Includes `hashed_id` (the hashed build id `listSessions` takes) and `session_type`, resolved through the build's sessions when the build ran on Automate / App Automate.
   **Prompt example**
 
   ```text
@@ -448,7 +457,7 @@ As of now we support 44 tools.
 
 ## 📱 App Live
 
- 20. `runAppLiveSession` — Start a manual app testing session on a real device in the cloud.
+ 21. `runAppLiveSession` — Start a manual app testing session on a real device in the cloud.
   **Prompt example**
 
   ```text
@@ -459,7 +468,7 @@ As of now we support 44 tools.
 
 ## 💻 Live
 
- 21. `runBrowserLiveSession` — Start a Live session for website testing on desktop or mobile browsers.
+ 22. `runBrowserLiveSession` — Start a Live session for website testing on desktop or mobile browsers.
   **Prompt example**
 
   ```text
@@ -470,21 +479,21 @@ As of now we support 44 tools.
 
 ## 📲 App Automate
 
- 22. `takeAppScreenshot` — Launch the app on a specified device and capture a quick verification screenshot to confirm your app has launched.
+ 23. `takeAppScreenshot` — Launch the app on a specified device and capture a quick verification screenshot to confirm your app has launched.
   **Prompt example**
 
   ```text
   Take a screenshot of my app on Google Pixel 6 with Android 12 while testing on App Automate. App file path: /Users/xyz/app-debug.apk
   ```
 
- 23. `runAppTestsOnBrowserStack` — Run pre-built native mobile test suites (Espresso/XCUITest) by direct upload of compiled .apk/.ipa test files.
+ 24. `runAppTestsOnBrowserStack` — Run pre-built native mobile test suites (Espresso/XCUITest) by direct upload of compiled .apk/.ipa test files.
   **Prompt example**
 
   ```text
   Run Espresso tests from /tests/checkout.zip on Galaxy S21 and Pixel 6 with Android 12. App path is /apps/beta-release.apk under project 'Checkout Flow'
   ```
 
- 24. `setupBrowserStackAppAutomateTests` — Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing.
+ 25. `setupBrowserStackAppAutomateTests` — Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing.
   **Prompt example**
 
   ```text
@@ -495,35 +504,35 @@ As of now we support 44 tools.
 
 ## ♿ Accessibility
 
- 25. `accessibilityExpert` — Ask the A11y Expert (WCAG 2.0/2.1/2.2, mobile/web usability, best practices).
+ 26. `accessibilityExpert` — Ask the A11y Expert (WCAG 2.0/2.1/2.2, mobile/web usability, best practices).
   **Prompt example**
 
   ```text
   What WCAG guidelines apply to form field error messages on mobile web?
   ```
 
- 26. `startAccessibilityScan` — Start a web accessibility scan and retrieve a local CSV report path.
+ 27. `startAccessibilityScan` — Start a web accessibility scan and retrieve a local CSV report path.
   **Prompt example**
 
   ```text
   Run accessibility scan for "www.example.com"
   ```
 
- 27. `createAccessibilityAuthConfig` — Create an authentication configuration (form-based or basic) for accessibility scans behind a login.
+ 28. `createAccessibilityAuthConfig` — Create an authentication configuration (form-based or basic) for accessibility scans behind a login.
   **Prompt example**
 
   ```text
   Create a basic-auth accessibility config named 'site-login' for https://www.example.com with username testuser and password <password>
   ```
 
- 28. `getAccessibilityAuthConfig` — Retrieve an existing accessibility authentication configuration by ID.
+ 29. `getAccessibilityAuthConfig` — Retrieve an existing accessibility authentication configuration by ID.
   **Prompt example**
 
   ```text
   Get accessibility auth config with ID <config-id>
   ```
 
- 29. `fetchAccessibilityIssues` — Fetch accessibility issues from a completed scan, with pagination support.
+ 30. `fetchAccessibilityIssues` — Fetch accessibility issues from a completed scan, with pagination support.
   **Prompt example**
 
   ```text
@@ -534,49 +543,49 @@ As of now we support 44 tools.
 
 ## 🎨 Percy Visual Testing
 
- 30. `percyVisualTestIntegrationAgent` — Integrate Percy visual testing into a new project and demonstrate visual change detection with a step-by-step simulation.
+ 31. `percyVisualTestIntegrationAgent` — Integrate Percy visual testing into a new project and demonstrate visual change detection with a step-by-step simulation.
   **Prompt example**
 
   ```text
   Integrate Percy for this project
   ```
 
- 31. `expandPercyVisualTesting` — Set up or expand Percy visual testing coverage for existing projects (Percy Web Standalone and Percy Automate).
+ 32. `expandPercyVisualTesting` — Set up or expand Percy visual testing coverage for existing projects (Percy Web Standalone and Percy Automate).
   **Prompt example**
 
   ```text
   Expand Percy coverage for this project
   ```
 
- 32. `addPercySnapshotCommands` — Add Percy snapshot commands to the specified test files. _(not available in Remote MCP)_
+ 33. `addPercySnapshotCommands` — Add Percy snapshot commands to the specified test files. _(not available in Remote MCP)_
   **Prompt example**
 
   ```text
   Add Percy snapshot commands to my Cypress test files
   ```
 
- 33. `listTestFiles` — List all test files for a given set of directories. _(not available in Remote MCP)_
+ 34. `listTestFiles` — List all test files for a given set of directories. _(not available in Remote MCP)_
   **Prompt example**
 
   ```text
   List the test files under my ./tests directory
   ```
 
- 34. `runPercyScan` — Run a Percy visual test scan. _(not available in Remote MCP)_
+ 35. `runPercyScan` — Run a Percy visual test scan. _(not available in Remote MCP)_
   **Prompt example**
 
   ```text
   Run this Percy build
   ```
 
- 35. `fetchPercyChanges` — Retrieve and summarize visual changes detected by Percy AI between the latest and previous builds.
+ 36. `fetchPercyChanges` — Retrieve and summarize visual changes detected by Percy AI between the latest and previous builds.
   **Prompt example**
 
   ```text
   Summarize the visual changes Percy detected in my latest build
   ```
 
- 36. `managePercyBuildApproval` — Approve or reject a Percy build.
+ 37. `managePercyBuildApproval` — Approve or reject a Percy build.
   **Prompt example**
 
   ```text
@@ -587,61 +596,68 @@ As of now we support 44 tools.
 
 ## 🤖 BrowserStack AI Agents
 
- 37. `uploadProductRequirementFile` — Upload a PRD/screenshot/PDF and get a file mapping ID (used with `createTestCasesFromFile`). _(not available in Remote MCP)_
+ 38. `uploadProductRequirementFile` — Upload a PRD/screenshot/PDF and get a file mapping ID (used with `createTestCasesFromFile`). _(not available in Remote MCP)_
   **Prompt example**
 
   ```text
   Upload PRD from /Users/xyz/Desktop/login-flow.pdf and use BrowserStack AI to generate test cases
   ```
 
- 38. `createLCASteps` — Generate Low Code Automation (LCA) steps from a manual test case in Test Management.
+ 39. `createLCASteps` — Generate Low Code Automation (LCA) steps from a manual test case in Test Management.
   **Prompt example**
 
   ```text
   Convert the manual test case 'Add to Cart' in the 'Shopping App' project into LCA steps
   ```
 
- 39. `fetchSelfHealedSelectors` — Retrieve AI self-healed selectors (plus test source) to fix flaky tests caused by DOM changes.
+ 40. `fetchSelfHealedSelectors` — Retrieve AI self-healed selectors (plus test source) to fix flaky tests caused by DOM changes.
   **Prompt example**
 
   ```text
   Fetch and fix flaky test selectors in Automate session ID session_9482 using MCP
   ```
 
- 40. `prepareSelfHealingPlan` — Build a self-healing edit plan that bundles locator pairs with test source for your LLM to apply. Does NOT modify files itself.
+ 41. `prepareSelfHealingPlan` — Build a self-healing edit plan that bundles locator pairs with test source for your LLM to apply. Does NOT modify files itself.
   **Prompt example**
 
   ```text
   Prepare a self-healing plan from the self-healed selectors for my build
   ```
 
- 41. `fetchRCA` — Fetch AI Root Cause Analysis for your failed Automate/App-Automate tests (by numeric test ID). Suggests fixes only; never auto-applies.
+ 42. `fetchRCA` — Fetch AI Root Cause Analysis for your failed Automate/App-Automate tests (by numeric test ID). Suggests fixes only; never auto-applies.
   **Prompt example**
 
   ```text
   Fetch the root cause analysis for failed test IDs 101 and 102 on BrowserStack
   ```
 
- 42. `getBuildId` — Get the BrowserStack build ID for a given project and build name, scoped to your builds.
+ 43. `getBuildId` — Get the BrowserStack build ID for a given project and build name, scoped to your builds.
   **Prompt example**
 
   ```text
   Get the build ID for build 'nightly-regression' in project 'Checkout Flow'
   ```
 
- 43. `listBuildId` — Get the latest build ID for a project and build name, across all users (no user filter).
+ 44. `listBuildId` — Get the latest build ID for a project and build name, across all users (no user filter).
   **Prompt example**
 
   ```text
   Get the latest build ID for build 'nightly-regression' in project 'Checkout Flow'
   ```
 
- 44. `listTestIds` — List test IDs from a BrowserStack Automate build, filtered by status (passed/failed/pending/skipped).
+ 45. `listTestIds` — List the tests in a BrowserStack build (Automate or App Automate) with each test's `status` and `session_id`, optionally filtered by status (passed/failed/pending/skipped). The `session_id` feeds `getFailureLogs` and `fetchAutomationScreenshots` directly.
   **Prompt example**
 
   ```text
   List the failed test IDs from build UUID <your-build-uuid> on BrowserStack
   ```
+ 46. `askBrowserStackAI` *(Alpha, limited availability)* — Hand a multi-step task to BrowserStack's agent in plain language; it decides which calls to make and returns the answer plus the steps it took. Covers Test Management and Test Reporting & Analytics. Anything that would change data pauses for your confirmation in your own client; deletes are refused outright. Requires the account to be enrolled — otherwise it returns an entitlement error and nothing runs.
+  **Prompt example**
+
+  ```text
+  Find all payment test cases in project Shopping App and add the 'regression' tag to them
+  ```
+
 
 ##  🚀 Remote MCP Server
 

package/dist/config.d.ts

@@ -11,7 +11,10 @@ export declare class Config {
     readonly O11Y_TFA_RCA_BASE_URL: string;
     readonly BROWSERSTACK_AUTOMATION_BASE_URL: string;
     readonly BROWSERSTACK_O11Y_UI_BASE_URL: string;
-    constructor(DEV_MODE: boolean, browserstackLocalOptions: Record<string, any>, USE_OWN_LOCAL_BINARY_PROCESS: boolean, REMOTE_MCP: boolean, UPLOAD_BASE_DIR: string | undefined, O11Y_TFA_RCA_BASE_URL: string, BROWSERSTACK_AUTOMATION_BASE_URL: string, BROWSERSTACK_O11Y_UI_BASE_URL: string);
+    readonly ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY: boolean;
+    readonly ASK_BROWSERSTACK_ATLAS_URL: string | undefined;
+    readonly ASK_BROWSERSTACK_AUTH_TOKEN_URL: string | undefined;
+    constructor(DEV_MODE: boolean, browserstackLocalOptions: Record<string, any>, USE_OWN_LOCAL_BINARY_PROCESS: boolean, REMOTE_MCP: boolean, UPLOAD_BASE_DIR: string | undefined, O11Y_TFA_RCA_BASE_URL: string, BROWSERSTACK_AUTOMATION_BASE_URL: string, BROWSERSTACK_O11Y_UI_BASE_URL: string, ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY: boolean, ASK_BROWSERSTACK_ATLAS_URL: string | undefined, ASK_BROWSERSTACK_AUTH_TOKEN_URL: string | undefined);
 }
 declare const config: Config;
 export default config;

package/dist/config.js

@@ -47,7 +47,18 @@ export class Config {
     O11Y_TFA_RCA_BASE_URL;
     BROWSERSTACK_AUTOMATION_BASE_URL;
     BROWSERSTACK_O11Y_UI_BASE_URL;
-    constructor(DEV_MODE, browserstackLocalOptions, USE_OWN_LOCAL_BINARY_PROCESS, REMOTE_MCP, UPLOAD_BASE_DIR, O11Y_TFA_RCA_BASE_URL, BROWSERSTACK_AUTOMATION_BASE_URL, BROWSERSTACK_O11Y_UI_BASE_URL) {
+    ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY;
+    ASK_BROWSERSTACK_ATLAS_URL;
+    ASK_BROWSERSTACK_AUTH_TOKEN_URL;
+    constructor(DEV_MODE, browserstackLocalOptions, USE_OWN_LOCAL_BINARY_PROCESS, REMOTE_MCP, UPLOAD_BASE_DIR, O11Y_TFA_RCA_BASE_URL, BROWSERSTACK_AUTOMATION_BASE_URL, BROWSERSTACK_O11Y_UI_BASE_URL, 
+    // askBrowserStackAI's process-startup settings. Declared here rather than read from
+    // process.env inside src/tools/, per rules/tool-design.md — and so the remote wrapper,
+    // which only forwards env it knows about, has one place to look.
+    //
+    // ASK_BROWSERSTACK_DISABLED is deliberately NOT here: it is a kill switch, and reading
+    // it per call keeps it effective without a restart. Fixing it at boot would mean a pod
+    // roll to disable the tool, which is slowest exactly when you need it fastest.
+    ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY, ASK_BROWSERSTACK_ATLAS_URL, ASK_BROWSERSTACK_AUTH_TOKEN_URL) {
         this.DEV_MODE = DEV_MODE;
         this.browserstackLocalOptions = browserstackLocalOptions;
         this.USE_OWN_LOCAL_BINARY_PROCESS = USE_OWN_LOCAL_BINARY_PROCESS;
@@ -56,6 +67,9 @@ export class Config {
         this.O11Y_TFA_RCA_BASE_URL = O11Y_TFA_RCA_BASE_URL;
         this.BROWSERSTACK_AUTOMATION_BASE_URL = BROWSERSTACK_AUTOMATION_BASE_URL;
         this.BROWSERSTACK_O11Y_UI_BASE_URL = BROWSERSTACK_O11Y_UI_BASE_URL;
+        this.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY = ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY;
+        this.ASK_BROWSERSTACK_ATLAS_URL = ASK_BROWSERSTACK_ATLAS_URL;
+        this.ASK_BROWSERSTACK_AUTH_TOKEN_URL = ASK_BROWSERSTACK_AUTH_TOKEN_URL;
     }
 }
 const config = new Config(process.env.DEV_MODE === "true", browserstackLocalOptions, process.env.USE_OWN_LOCAL_BINARY_PROCESS === "true", process.env.REMOTE_MCP === "true", process.env.MCP_UPLOAD_BASE_DIR && process.env.MCP_UPLOAD_BASE_DIR.length > 0
@@ -69,5 +83,12 @@ const config = new Config(process.env.DEV_MODE === "true", browserstackLocalOpti
     : DEFAULT_BROWSERSTACK_AUTOMATION_BASE_URL, process.env.BROWSERSTACK_O11Y_UI_BASE_URL &&
     process.env.BROWSERSTACK_O11Y_UI_BASE_URL.length > 0
     ? process.env.BROWSERSTACK_O11Y_UI_BASE_URL
-    : DEFAULT_BROWSERSTACK_O11Y_UI_BASE_URL);
+    : DEFAULT_BROWSERSTACK_O11Y_UI_BASE_URL, (process.env.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY || "").toLowerCase() ===
+    "true", process.env.ASK_BROWSERSTACK_ATLAS_URL &&
+    process.env.ASK_BROWSERSTACK_ATLAS_URL.trim().length > 0
+    ? process.env.ASK_BROWSERSTACK_ATLAS_URL
+    : undefined, process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL &&
+    process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL.trim().length > 0
+    ? process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL
+    : undefined);
 export default config;

package/dist/index.d.ts

@@ -2,6 +2,7 @@
 import "dotenv/config";
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";
-export { trackMCP } from "./lib/instrumentation.js";
+export { trackMCP, withToolCall } from "./lib/instrumentation.js";
+export { instrumentToolLatency } from "./lib/tool-latency.js";
 export { default as addTfaRcaCollaborationTools } from "./tools/tfa-rca-collaboration.js";
 export declare const PackageJsonVersion: any;

package/dist/index.js

@@ -29,12 +29,16 @@ async function main() {
     await mcpServer.getInstance().connect(transport);
 }
 main().catch(console.error);
-// Ensure logs are flushed before exit
+// 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.
 process.on("exit", () => {
-    logger.flush();
+    logger.flush?.();
 });
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";
-export { trackMCP } from "./lib/instrumentation.js";
+export { trackMCP, withToolCall } from "./lib/instrumentation.js";
+export { instrumentToolLatency } from "./lib/tool-latency.js";
 export { default as addTfaRcaCollaborationTools } from "./tools/tfa-rca-collaboration.js";
 export const PackageJsonVersion = packageJson.version;

package/dist/lib/constants.d.ts

@@ -2,15 +2,18 @@ export declare const SessionType: {
     readonly Automate: "automate";
     readonly AppAutomate: "app-automate";
 };
+export declare const SessionVideoLogType: "video";
 export declare const AutomateLogType: {
     readonly NetworkLogs: "networkLogs";
     readonly SessionLogs: "sessionLogs";
     readonly ConsoleLogs: "consoleLogs";
+    readonly Video: "video";
 };
 export declare const AppAutomateLogType: {
     readonly DeviceLogs: "deviceLogs";
     readonly AppiumLogs: "appiumLogs";
     readonly CrashLogs: "crashLogs";
+    readonly Video: "video";
 };
 export type SessionType = (typeof SessionType)[keyof typeof SessionType];
 export type AutomateLogType = (typeof AutomateLogType)[keyof typeof AutomateLogType];

package/dist/lib/constants.js

@@ -2,13 +2,16 @@ export const SessionType = {
     Automate: "automate",
     AppAutomate: "app-automate",
 };
+export const SessionVideoLogType = "video";
 export const AutomateLogType = {
     NetworkLogs: "networkLogs",
     SessionLogs: "sessionLogs",
     ConsoleLogs: "consoleLogs",
+    Video: SessionVideoLogType,
 };
 export const AppAutomateLogType = {
     DeviceLogs: "deviceLogs",
     AppiumLogs: "appiumLogs",
     CrashLogs: "crashLogs",
+    Video: SessionVideoLogType,
 };

package/dist/lib/instrumentation.d.ts

@@ -1,4 +1,16 @@
-export declare function trackMCP(toolName: string, clientInfo: {
+export type ClientInfo = {
     name?: string;
     version?: string;
-}, error?: unknown, config?: any): void;
+};
+export type ToolOutcome = "ok" | "error_result" | "threw";
+/**
+ * Inside `withToolCall` this only records into the call's context; the single row is
+ * written when the handler settles. Outside one (`started` heartbeat, unwrapped host
+ * tools) it posts a row immediately, as before.
+ */
+export declare function trackMCP(toolName: string, clientInfo: ClientInfo, error?: unknown, config?: any): void;
+/**
+ * Runs a tool handler and writes one MCPInstrumentation row when it settles: success,
+ * duration_ms, outcome (ok / error_result / threw), error fields on failure.
+ */
+export declare function withToolCall<T>(toolName: string, getClientInfo: () => ClientInfo, config: any, fn: () => Promise<T> | T): Promise<T>;

package/dist/lib/instrumentation.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import logger from "../logger.js";
 import { getBrowserStackAuth } from "./get-auth.js";
 import { createRequire } from "module";
@@ -5,42 +6,31 @@ const require = createRequire(import.meta.url);
 const packageJson = require("../../package.json");
 import { apiClient } from "./apiClient.js";
 import globalConfig from "../config.js";
-export function trackMCP(toolName, clientInfo, error, config) {
-    const instrumentationEndpoint = "https://api.browserstack.com/sdk/v1/event";
-    const isSuccess = !error;
-    const mcpClient = clientInfo?.name || "unknown";
-    // Log client information
-    if (clientInfo?.name) {
-        logger.info(`Client connected: ${clientInfo.name} (version: ${clientInfo.version})`);
-    }
-    else {
-        logger.info("Client connected: unknown client");
-    }
-    const event = {
-        event_type: "MCPInstrumentation",
-        event_properties: {
-            mcp_version: packageJson.version,
-            tool_name: toolName,
-            mcp_client: mcpClient,
-            success: isSuccess,
-            is_remote: globalConfig.REMOTE_MCP,
-        },
+const INSTRUMENTATION_ENDPOINT = "https://api.browserstack.com/sdk/v1/event";
+function baseProperties(toolName, clientInfo) {
+    return {
+        mcp_version: packageJson.version,
+        tool_name: toolName,
+        mcp_client: clientInfo?.name || "unknown",
+        node_version: process.versions.node,
+        is_remote: globalConfig.REMOTE_MCP,
     };
-    // Add error details if applicable
-    if (error) {
-        event.event_properties.error_message =
-            error instanceof Error ? error.message : String(error);
-        event.event_properties.error_type =
-            error instanceof Error ? error.constructor.name : "Unknown";
-    }
-    let authHeader = undefined;
+}
+function errorProperties(error) {
+    return {
+        error_message: error instanceof Error ? error.message : String(error),
+        error_type: error instanceof Error ? error.constructor.name : "Unknown",
+    };
+}
+function sendEvent(event, config) {
+    let authHeader;
     if (config) {
         const authString = getBrowserStackAuth(config);
         authHeader = `Basic ${Buffer.from(authString).toString("base64")}`;
     }
     apiClient
         .post({
-        url: instrumentationEndpoint,
+        url: INSTRUMENTATION_ENDPOINT,
         body: event,
         headers: {
             "Content-Type": "application/json",
@@ -51,3 +41,88 @@ export function trackMCP(toolName, clientInfo, error, config) {
     })
         .catch(() => { });
 }
+const callContext = new AsyncLocalStorage();
+/**
+ * Inside `withToolCall` this only records into the call's context; the single row is
+ * written when the handler settles. Outside one (`started` heartbeat, unwrapped host
+ * tools) it posts a row immediately, as before.
+ */
+export function trackMCP(toolName, clientInfo, error, config) {
+    const ctx = callContext.getStore();
+    if (ctx) {
+        if (clientInfo?.name && !ctx.clientInfo?.name)
+            ctx.clientInfo = clientInfo;
+        if (config && !ctx.config)
+            ctx.config = config;
+        if (error)
+            ctx.error = error;
+        return;
+    }
+    if (clientInfo?.name) {
+        logger.info(`Client connected: ${clientInfo.name} (version: ${clientInfo.version})`);
+    }
+    else {
+        logger.info("Client connected: unknown client");
+    }
+    const event = {
+        event_type: "MCPInstrumentation",
+        event_properties: {
+            ...baseProperties(toolName, clientInfo),
+            success: !error,
+            ...(error ? errorProperties(error) : {}),
+        },
+    };
+    sendEvent(event, config);
+}
+function isErrorResult(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        result.isError === true);
+}
+/**
+ * Runs a tool handler and writes one MCPInstrumentation row when it settles: success,
+ * duration_ms, outcome (ok / error_result / threw), error fields on failure.
+ */
+export async function withToolCall(toolName, getClientInfo, config, fn) {
+    const ctx = { toolName, clientInfo: {}, config };
+    const startedAt = performance.now();
+    let outcome = "ok";
+    try {
+        const result = await callContext.run(ctx, fn);
+        if (isErrorResult(result))
+            outcome = "error_result";
+        return result;
+    }
+    catch (error) {
+        outcome = "threw";
+        ctx.error ??= error;
+        throw error;
+    }
+    finally {
+        try {
+            let clientInfo = ctx.clientInfo;
+            try {
+                const live = getClientInfo();
+                if (live?.name)
+                    clientInfo = live;
+            }
+            catch {
+                /* client info is optional */
+            }
+            const event = {
+                event_type: "MCPInstrumentation",
+                event_properties: {
+                    ...baseProperties(toolName, clientInfo),
+                    success: ctx.error === undefined && outcome !== "threw",
+                    duration_ms: Math.max(0, Math.round(performance.now() - startedAt)),
+                    outcome,
+                    ...(ctx.error !== undefined ? errorProperties(ctx.error) : {}),
+                },
+            };
+            sendEvent(event, ctx.config ?? config);
+        }
+        catch {
+            /* telemetry must never affect the call */
+        }
+    }
+}

package/dist/lib/node-version-notice.d.ts

@@ -0,0 +1 @@
+export declare function nodeUpgradeNotice(version?: string): string;

package/dist/lib/node-version-notice.js

@@ -0,0 +1,9 @@
+const RECOMMENDED_NODE_MAJOR = 22;
+export function nodeUpgradeNotice(version = process.versions.node) {
+    const major = Number(version.split(".")[0]) || 0;
+    if (major >= RECOMMENDED_NODE_MAJOR)
+        return "";
+    return (`⚠️ Please use Node version > ${RECOMMENDED_NODE_MAJOR - 1}.x.x ` +
+        `(Node ${RECOMMENDED_NODE_MAJOR} LTS recommended). This server is running on ` +
+        `Node ${version}; older versions will be unsupported.`);
+}

package/dist/lib/tool-latency.d.ts

@@ -0,0 +1,4 @@
+import { RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ClientInfo } from "./instrumentation.js";
+/** Wraps every function handler in `withToolCall`. Idempotent; skips task-style handlers. */
+export declare function instrumentToolLatency(tools: Record<string, RegisteredTool>, getClientInfo: () => ClientInfo, config?: unknown): void;

package/dist/lib/tool-latency.js

@@ -0,0 +1,16 @@
+import { withToolCall } from "./instrumentation.js";
+const WRAPPED = Symbol.for("browserstack.mcp.latencyWrapped");
+/** Wraps every function handler in `withToolCall`. Idempotent; skips task-style handlers. */
+export function instrumentToolLatency(tools, getClientInfo, config) {
+    for (const [name, tool] of Object.entries(tools)) {
+        const inner = tool.handler;
+        if (typeof inner !== "function")
+            continue;
+        if (inner[WRAPPED])
+            continue;
+        const wrapped = (...args) => withToolCall(name, getClientInfo, config, () => inner(...args));
+        wrapped[WRAPPED] = true;
+        // Direct assignment: tool.update() would also fire tools/list_changed.
+        tool.handler = wrapped;
+    }
+}

package/dist/lib/untrusted-content.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Wrap untrusted external content before it is returned into the calling LLM's
+ * context. "Untrusted" = anything the server did not author itself: RAG chunks,
+ * device/console/session logs, backend AI-service output (RCA, Percy, TCG),
+ * scanned-page HTML, or text derived from user-uploaded files.
+ *
+ * The block is delimited with a per-call random nonce so injected content cannot
+ * forge the closing marker to break out, and prefixed with an instruction to
+ * treat the content strictly as data. Mitigates indirect prompt injection
+ *
+ * `source` is a short trusted label for the kind of data (e.g. "device logs").
+ * Pass a string literal only — never interpolate external/untrusted data into
+ * it, since it appears outside the quarantined block.
+ */
+export declare function wrapUntrusted(source: string, content: string): string;