@wdio/mcp 3.0.0 → 3.1.1

package/README.md

@@ -216,6 +216,117 @@ appium
 # Server runs at http://127.0.0.1:4723 by default
 ```
 
+## BrowserStack
+
+Run browser and mobile app tests on [BrowserStack](https://www.browserstack.com/) real devices and browsers without any local setup.
+
+### Prerequisites
+
+Set your credentials as environment variables:
+
+```bash
+export BROWSERSTACK_USERNAME=your_username
+export BROWSERSTACK_ACCESS_KEY=your_access_key
+```
+
+Or add them to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "wdio-mcp": {
+      "command": "npx",
+      "args": ["-y", "@wdio/mcp@latest"],
+      "env": {
+        "BROWSERSTACK_USERNAME": "your_username",
+        "BROWSERSTACK_ACCESS_KEY": "your_access_key"
+      }
+    }
+  }
+}
+```
+
+### Browser Sessions
+
+Run a browser on a specific OS/version combination:
+
+```javascript
+start_session({
+  provider: 'browserstack',
+  platform: 'browser',
+  browser: 'chrome',           // chrome | firefox | edge | safari
+  browserVersion: 'latest',    // default: latest
+  os: 'Windows',               // e.g. "Windows", "OS X"
+  osVersion: '11',             // e.g. "11", "Sequoia"
+  reporting: {
+    project: 'My Project',
+    build: 'v1.2.0',
+    session: 'Login flow'
+  }
+})
+```
+
+### Mobile App Sessions
+
+Test on BrowserStack real devices. First upload your app (or use an existing `bs://` URL):
+
+```javascript
+// Upload a local .apk or .ipa (returns a bs:// URL)
+upload_app({ path: '/path/to/app.apk' })
+
+// Start a session with the returned URL
+start_session({
+  provider: 'browserstack',
+  platform: 'android',         // android | ios
+  app: 'bs://abc123...',       // bs:// URL or custom_id from upload
+  deviceName: 'Samsung Galaxy S23',
+  platformVersion: '13.0',
+  reporting: {
+    project: 'My Project',
+    build: 'v1.2.0',
+    session: 'Checkout flow'
+  }
+})
+```
+
+Use `list_apps` to see previously uploaded apps:
+
+```javascript
+list_apps()                               // own uploads, sorted by date
+list_apps({ sortBy: 'app_name' })
+list_apps({ organizationWide: true })     // all uploads in your org
+```
+
+### BrowserStack Local
+
+To test against URLs that are only accessible on your local machine or internal network, enable the BrowserStack Local tunnel:
+
+```javascript
+start_session({
+  provider: 'browserstack',
+  platform: 'browser',
+  browser: 'chrome',
+  browserstackLocal: true      // starts tunnel automatically
+})
+```
+
+### Reporting Labels
+
+All session types support `reporting` labels that appear in the BrowserStack Automate dashboard:
+
+| Field                     | Description                                |
+|---------------------------|--------------------------------------------|
+| `reporting.project`       | Group sessions under a project name        |
+| `reporting.build`         | Tag sessions with a build/version label    |
+| `reporting.session`       | Name for the individual test session       |
+
+### BrowserStack Tools
+
+| Tool          | Description                                                                      |
+|---------------|----------------------------------------------------------------------------------|
+| `upload_app`  | Upload a local `.apk` or `.ipa` to BrowserStack; returns a `bs://` URL          |
+| `list_apps`   | List apps previously uploaded to your BrowserStack account                       |
+
 ## Features
 
 ### Browser Automation

package/lib/server.js

@@ -46,7 +46,7 @@ var package_default = {
     type: "git",
     url: "git://github.com/webdriverio/mcp.git"
   },
-  version: "2.5.3",
+  version: "3.1.0",
   description: "MCP server with WebdriverIO for browser and mobile app automation (iOS/Android via Appium)",
   main: "./lib/server.js",
   module: "./lib/server.js",
@@ -77,46 +77,44 @@ var package_default = {
     prebundle: "rimraf lib --glob ./*.tgz",
     bundle: "tsup && shx chmod +x lib/server.js",
     postbundle: "npm pack",
-    lint: "npm run lint:src && npm run lint:tests",
-    "lint:src": "eslint src/ --fix && tsc --noEmit",
-    "lint:tests": "eslint tests/ --fix && tsc -p tsconfig.test.json --noEmit",
+    lint: "eslint src/ tests/ --fix && tsc --noEmit",
     start: "node lib/server.js",
     dev: "tsx --watch src/server.ts",
     prepare: "husky",
     test: "vitest run"
   },
   dependencies: {
-    "@modelcontextprotocol/sdk": "1.27",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "@toon-format/toon": "^2.1.0",
-    "@wdio/protocols": "^9.16.2",
-    "@xmldom/xmldom": "^0.8.11",
-    "puppeteer-core": "^24.35.0",
+    "@wdio/protocols": "^9.27.0",
+    "@xmldom/xmldom": "^0.8.12",
+    "puppeteer-core": "^24.40.0",
     sharp: "^0.34.5",
-    webdriverio: "9.24",
+    webdriverio: "^9.27.0",
     xpath: "^0.0.34",
-    zod: "^4.3.5"
+    zod: "^4.3.6"
   },
   devDependencies: {
-    "@release-it/conventional-changelog": "^10.0.4",
-    "@types/node": "^20.11.0",
+    "@release-it/conventional-changelog": "^10.0.6",
+    "@types/node": "^20.19.37",
     "@wdio/eslint": "^0.1.3",
-    "@wdio/types": "^9.20.0",
-    eslint: "^9.39.2",
-    "happy-dom": "^20.7.0",
+    "@wdio/types": "^9.27.0",
+    eslint: "^9.39.4",
+    "happy-dom": "^20.8.9",
     husky: "^9.1.7",
-    "release-it": "^19.2.3",
-    rimraf: "^6.1.2",
+    "release-it": "^19.2.4",
+    rimraf: "^6.1.3",
     shx: "^0.4.0",
     tsup: "^8.5.1",
     tsx: "^4.21.0",
-    typescript: "5.9",
-    vitest: "^4.0.18"
+    typescript: "~5.9.3",
+    vitest: "^4.1.2"
   },
   packageManager: "pnpm@10.32.1"
 };
 
 // src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/tools/navigate.tool.ts
@@ -2073,8 +2071,88 @@ function withRecording(toolName, callback) {
   };
 }
 
+// src/resources/browserstack-local.resource.ts
+function getLocalBinaryInfo() {
+  const platform2 = process.platform;
+  const arch = process.arch;
+  if (platform2 === "darwin") {
+    return {
+      downloadUrl: "https://local-downloads.browserstack.com/BrowserStackLocal-darwin-x64.zip",
+      platform: "macOS",
+      arch: arch === "arm64" ? "Apple Silicon (via Rosetta 2)" : "Intel x64",
+      binaryName: "BrowserStackLocal",
+      note: arch === "arm64" ? "macOS binary is Intel-only. Rosetta 2 must be installed (it is on most Apple Silicon Macs by default)." : void 0
+    };
+  }
+  if (platform2 === "win32") {
+    return {
+      downloadUrl: "https://local-downloads.browserstack.com/BrowserStackLocal-win32.zip",
+      platform: "Windows",
+      arch: "x86/x64",
+      binaryName: "BrowserStackLocal.exe"
+    };
+  }
+  if (arch === "arm64") {
+    return {
+      downloadUrl: "https://local-downloads.browserstack.com/BrowserStackLocal-linux-arm64.zip",
+      platform: "Linux",
+      arch: "ARM64",
+      binaryName: "BrowserStackLocal"
+    };
+  }
+  if (arch === "ia32") {
+    return {
+      downloadUrl: "https://local-downloads.browserstack.com/BrowserStackLocal-linux-ia32.zip",
+      platform: "Linux",
+      arch: "x86 32-bit",
+      binaryName: "BrowserStackLocal"
+    };
+  }
+  return {
+    downloadUrl: "https://local-downloads.browserstack.com/BrowserStackLocal-linux-x64.zip",
+    platform: "Linux",
+    arch: "x64",
+    binaryName: "BrowserStackLocal"
+  };
+}
+var browserstackLocalBinaryResource = {
+  name: "browserstack-local-binary",
+  uri: "wdio://browserstack/local-binary",
+  description: "BrowserStack Local binary download URL and daemon setup instructions for the current platform. MUST be read and followed before using browserstackLocal: true in start_session.",
+  handler: async () => {
+    const info = getLocalBinaryInfo();
+    const accessKey = process.env.BROWSERSTACK_ACCESS_KEY ?? "<BROWSERSTACK_ACCESS_KEY>";
+    const content = {
+      requirement: "MUST start the BrowserStack Local daemon BEFORE calling start_session with browserstackLocal: true. Without it, all navigation to local/internal URLs will fail with ERR_TUNNEL_CONNECTION_FAILED.",
+      platform: info.platform,
+      arch: info.arch,
+      downloadUrl: info.downloadUrl,
+      ...info.note ? { note: info.note } : {},
+      setup: [
+        `1. Download: curl -O ${info.downloadUrl}`,
+        `2. Unzip: unzip ${info.downloadUrl.split("/").pop()}`,
+        `3. Make executable (macOS/Linux): chmod +x ${info.binaryName}`,
+        `4. Start daemon: ./${info.binaryName} --key ${accessKey} --force-local --daemon start`
+      ],
+      commands: {
+        start: `./${info.binaryName} --key ${accessKey} --force-local --daemon start`,
+        stop: `./${info.binaryName} --key ${accessKey} --daemon stop`,
+        status: `./${info.binaryName} --daemon list`
+      },
+      afterDaemonIsRunning: "Call start_session with browserstackLocal: true to route BrowserStack traffic through the tunnel."
+    };
+    return {
+      contents: [{
+        uri: "wdio://browserstack/local-binary",
+        mimeType: "application/json",
+        text: JSON.stringify(content, null, 2)
+      }]
+    };
+  }
+};
+
 // src/resources/sessions.resource.ts
-import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/recording/code-generator.ts
 function escapeStr(value) {
@@ -2266,13 +2344,41 @@ var sessionCodeResource = {
   }
 };
 
+// src/resources/capabilities.resource.ts
+init_state();
+var capabilitiesResource = {
+  name: "session-current-capabilities",
+  uri: "wdio://session/current/capabilities",
+  description: "Raw capabilities returned by the WebDriver/Appium server for the current session. Use for debugging \u2014 shows the actual values the driver accepted, including defaults applied by BrowserStack or Appium.",
+  handler: async () => {
+    try {
+      const browser = getBrowser();
+      return {
+        contents: [{
+          uri: "wdio://session/current/capabilities",
+          mimeType: "application/json",
+          text: JSON.stringify(browser.capabilities, null, 2)
+        }]
+      };
+    } catch (e) {
+      return {
+        contents: [{
+          uri: "wdio://session/current/capabilities",
+          mimeType: "application/json",
+          text: JSON.stringify({ error: String(e) })
+        }]
+      };
+    }
+  }
+};
+
 // src/resources/elements.resource.ts
 init_state();
 import { encode as encode2 } from "@toon-format/toon";
 var elementsResource = {
   name: "session-current-elements",
   uri: "wdio://session/current/elements",
-  description: "Interactable elements on the current page",
+  description: "Interactable elements on the current page. Prefer this over screenshot \u2014 returns ready-to-use selectors, faster, and far fewer tokens. Only use screenshot for visual verification or debugging.",
   handler: async () => {
     try {
       const browser = getBrowser();
@@ -2680,7 +2786,7 @@ var cookiesResource = {
 
 // src/resources/app-state.resource.ts
 init_state();
-import { ResourceTemplate as ResourceTemplate2 } from "@modelcontextprotocol/sdk/server/mcp";
+import { ResourceTemplate as ResourceTemplate2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 async function readAppState(bundleId) {
   try {
     const browser = getBrowser();
@@ -3047,10 +3153,11 @@ function buildAndroidCapabilities(appPath, options) {
 var LocalAppiumProvider = class {
   name = "local-appium";
   getConnectionConfig(options) {
+    const appiumConfig = options.appiumConfig;
     const config = getAppiumServerConfig({
-      hostname: options.appiumHost,
-      port: options.appiumPort,
-      path: options.appiumPath
+      hostname: appiumConfig?.host,
+      port: appiumConfig?.port,
+      path: appiumConfig?.path
     });
     return { protocol: "http", ...config };
   }
@@ -3112,6 +3219,82 @@ var LocalAppiumProvider = class {
 };
 var localAppiumProvider = new LocalAppiumProvider();
 
+// src/providers/cloud/browserstack.provider.ts
+var BrowserStackProvider = class {
+  name = "browserstack";
+  getConnectionConfig(_options) {
+    return {
+      protocol: "https",
+      hostname: "hub.browserstack.com",
+      port: 443,
+      path: "/wd/hub",
+      user: process.env.BROWSERSTACK_USERNAME,
+      key: process.env.BROWSERSTACK_ACCESS_KEY
+    };
+  }
+  buildCapabilities(options) {
+    const platform2 = options.platform;
+    const userCapabilities = options.capabilities ?? {};
+    const browserstackLocal = options.browserstackLocal;
+    if (platform2 === "browser") {
+      const bstackOptions2 = {
+        browserVersion: options.browserVersion ?? "latest"
+      };
+      if (options.os) bstackOptions2.os = options.os;
+      if (options.osVersion) bstackOptions2.osVersion = options.osVersion;
+      if (browserstackLocal) bstackOptions2.local = true;
+      const reporting2 = options.reporting;
+      if (reporting2?.project) bstackOptions2.projectName = reporting2.project;
+      if (reporting2?.build) bstackOptions2.buildName = reporting2.build;
+      if (reporting2?.session) bstackOptions2.sessionName = reporting2.session;
+      return {
+        browserName: options.browser ?? "chrome",
+        "bstack:options": bstackOptions2,
+        ...userCapabilities
+      };
+    }
+    const bstackOptions = {
+      platformName: platform2,
+      deviceName: options.deviceName,
+      platformVersion: options.platformVersion,
+      deviceType: "phone",
+      appiumVersion: "3.1.0"
+    };
+    if (browserstackLocal) bstackOptions.local = true;
+    const reporting = options.reporting;
+    if (reporting?.project) bstackOptions.projectName = reporting.project;
+    if (reporting?.build) bstackOptions.buildName = reporting.build;
+    if (reporting?.session) bstackOptions.sessionName = reporting.session;
+    const autoAcceptAlerts = options.autoAcceptAlerts;
+    const autoDismissAlerts = options.autoDismissAlerts;
+    return {
+      platformName: platform2,
+      "appium:app": options.app,
+      "appium:autoGrantPermissions": options.autoGrantPermissions ?? true,
+      "appium:autoAcceptAlerts": autoDismissAlerts ? void 0 : autoAcceptAlerts ?? true,
+      "appium:autoDismissAlerts": autoDismissAlerts,
+      "appium:newCommandTimeout": options.newCommandTimeout ?? 300,
+      "bstack:options": bstackOptions,
+      ...userCapabilities
+    };
+  }
+  getSessionType(options) {
+    const platform2 = options.platform;
+    if (platform2 === "browser") return "browser";
+    return platform2;
+  }
+  shouldAutoDetach(_options) {
+    return false;
+  }
+};
+var browserStackProvider = new BrowserStackProvider();
+
+// src/providers/registry.ts
+function getProvider(providerName, platform2) {
+  if (providerName === "browserstack") return browserStackProvider;
+  return platform2 === "browser" ? localBrowserProvider : localAppiumProvider;
+}
+
 // src/tools/session.tool.ts
 var platformEnum = z14.enum(["browser", "ios", "android"]);
 var browserEnum = z14.enum(["chrome", "firefox", "edge", "safari"]);
@@ -3120,8 +3303,18 @@ var startSessionToolDefinition = {
   name: "start_session",
   description: "Starts a browser or mobile app session. For local browser, use browser platform. For mobile apps, use ios or android platform. Use attach mode to connect to an existing Chrome instance.",
   inputSchema: {
+    provider: z14.enum(["local", "browserstack"]).optional().default("local").describe("Session provider (default: local)"),
     platform: platformEnum.describe("Session platform type"),
     browser: browserEnum.optional().describe("Browser to launch (required for browser platform)"),
+    browserVersion: z14.string().optional().describe("Browser version (BrowserStack only, default: latest)"),
+    os: z14.string().optional().describe('Operating system (BrowserStack browser only, e.g. "Windows", "OS X")'),
+    osVersion: z14.string().optional().describe('OS version (BrowserStack browser only, e.g. "11", "Sequoia")'),
+    app: z14.string().optional().describe("BrowserStack app URL (bs://...) or custom_id for mobile sessions"),
+    reporting: z14.object({
+      project: z14.string().optional(),
+      build: z14.string().optional(),
+      session: z14.string().optional()
+    }).optional().describe("BrowserStack reporting labels (project, build, session)"),
     headless: coerceBoolean.optional().default(true).describe("Run browser in headless mode (default: true)"),
     windowWidth: z14.number().min(400).max(3840).optional().default(1920).describe("Browser window width"),
     windowHeight: z14.number().min(400).max(2160).optional().default(1080).describe("Browser window height"),
@@ -3138,11 +3331,16 @@ var startSessionToolDefinition = {
     fullReset: coerceBoolean.optional().describe("Uninstall app before/after session"),
     newCommandTimeout: z14.number().min(0).optional().default(300).describe("Appium command timeout in seconds"),
     attach: coerceBoolean.optional().default(false).describe("Attach to existing Chrome instead of launching"),
-    port: z14.number().optional().default(9222).describe("Chrome remote debugging port (for attach mode)"),
-    host: z14.string().optional().default("localhost").describe("Chrome host (for attach mode)"),
-    appiumHost: z14.string().optional().describe("Appium server hostname"),
-    appiumPort: z14.number().optional().describe("Appium server port"),
-    appiumPath: z14.string().optional().describe("Appium server path"),
+    attachConfig: z14.object({
+      port: z14.number().optional().default(9222),
+      host: z14.string().optional().default("localhost")
+    }).optional().describe("Chrome remote debugging connection (attach mode only, defaults: port 9222, host localhost)"),
+    appiumConfig: z14.object({
+      host: z14.string().optional(),
+      port: z14.number().optional(),
+      path: z14.string().optional()
+    }).optional().describe("Appium server connection (local provider only)"),
+    browserstackLocal: coerceBoolean.optional().default(false).describe("Enable BrowserStack Local tunnel for testing against local/internal URLs (BrowserStack only, default: false). IMPORTANT: The BrowserStack Local binary daemon MUST already be running before calling start_session, otherwise all navigation to local/internal URLs will fail with ERR_TUNNEL_CONNECTION_FAILED. Read the wdio://browserstack/local-binary resource for the platform-specific download URL and the exact daemon start command. Do not set this to true without first confirming the daemon is running."),
     navigationUrl: z14.string().optional().describe("URL to navigate to after starting"),
     capabilities: z14.record(z14.string(), z14.unknown()).optional().describe("Additional capabilities to merge")
   }
@@ -3202,12 +3400,14 @@ async function waitForCDP2(host, port, timeoutMs = 1e4) {
   throw new Error(`Chrome did not expose CDP on ${host}:${port} within ${timeoutMs}ms`);
 }
 async function startBrowserSession(args) {
-  const browser = args.browser ?? "chrome";
-  const headless = args.headless ?? true;
-  const windowWidth = args.windowWidth ?? 1920;
-  const windowHeight = args.windowHeight ?? 1080;
-  const navigationUrl = args.navigationUrl;
-  const userCapabilities = args.capabilities ?? {};
+  const {
+    browser = "chrome",
+    headless = true,
+    windowWidth = 1920,
+    windowHeight = 1080,
+    navigationUrl,
+    capabilities: userCapabilities = {}
+  } = args;
   const browserDisplayNames = {
     chrome: "Chrome",
     firefox: "Firefox",
@@ -3216,14 +3416,17 @@ async function startBrowserSession(args) {
   };
   const headlessSupported = browser !== "safari";
   const effectiveHeadless = headless && headlessSupported;
-  const mergedCapabilities = localBrowserProvider.buildCapabilities({
+  const provider = getProvider(args.provider ?? "local", "browser");
+  const connectionConfig = provider.getConnectionConfig(args);
+  const mergedCapabilities = provider.buildCapabilities({
+    ...args,
     browser,
     headless,
     windowWidth,
     windowHeight,
     capabilities: userCapabilities
   });
-  const wdioBrowser = await remote({ capabilities: mergedCapabilities });
+  const wdioBrowser = await remote({ ...connectionConfig, capabilities: mergedCapabilities });
   const { sessionId } = wdioBrowser;
   const sessionMetadata = {
     type: "browser",
@@ -3258,8 +3461,8 @@ Note: Unable to set window size (${windowWidth}x${windowHeight}). ${e}`;
   };
 }
 async function startMobileSession(args) {
-  const { platform: platform2, appPath, deviceName, noReset } = args;
-  if (!appPath && noReset !== true) {
+  const { platform: platform2, appPath, app, deviceName, noReset } = args;
+  if (!appPath && !app && noReset !== true) {
     return {
       content: [{
         type: "text",
@@ -3267,18 +3470,13 @@ async function startMobileSession(args) {
       }]
     };
   }
-  const serverConfig = localAppiumProvider.getConnectionConfig(args);
-  const mergedCapabilities = localAppiumProvider.buildCapabilities(args);
-  const browser = await remote({
-    protocol: serverConfig.protocol,
-    hostname: serverConfig.hostname,
-    port: serverConfig.port,
-    path: serverConfig.path,
-    capabilities: mergedCapabilities
-  });
+  const provider = getProvider(args.provider ?? "local", args.platform);
+  const serverConfig = provider.getConnectionConfig(args);
+  const mergedCapabilities = provider.buildCapabilities(args);
+  const browser = await remote({ ...serverConfig, capabilities: mergedCapabilities });
   const { sessionId } = browser;
-  const shouldAutoDetach = localAppiumProvider.shouldAutoDetach(args);
-  const sessionType = localAppiumProvider.getSessionType(args);
+  const shouldAutoDetach = provider.shouldAutoDetach(args);
+  const sessionType = provider.getSessionType(args);
   const metadata = {
     type: sessionType,
     capabilities: mergedCapabilities,
@@ -3307,9 +3505,8 @@ Appium Server: ${serverConfig.hostname}:${serverConfig.port}${serverConfig.path}
   };
 }
 async function attachBrowserSession(args) {
-  const port = args.port ?? 9222;
-  const host = args.host ?? "localhost";
-  const navigationUrl = args.navigationUrl;
+  const { port = 9222, host = "localhost" } = args.attachConfig ?? {};
+  const { navigationUrl } = args;
   await waitForCDP2(host, port);
   const { activeTabUrl, allTabUrls } = await closeStaleMappers(host, port);
   const capabilities = {
@@ -3419,6 +3616,98 @@ var switchTabTool = async ({ handle, index }) => {
   }
 };
 
+// src/tools/browserstack.tool.ts
+import { existsSync as existsSync2, createReadStream } from "fs";
+import { z as z16 } from "zod";
+var BS_API = "https://api-cloud.browserstack.com";
+function getAuth() {
+  const user = process.env.BROWSERSTACK_USERNAME;
+  const key = process.env.BROWSERSTACK_ACCESS_KEY;
+  if (!user || !key) return null;
+  return Buffer.from(`${user}:${key}`).toString("base64");
+}
+function formatAppList(apps) {
+  if (apps.length === 0) return "No apps found.";
+  return apps.map((a) => {
+    const id = a.custom_id ? ` [${a.custom_id}]` : "";
+    return `${a.app_name} v${a.app_version}${id} \u2014 ${a.app_url} (${a.uploaded_at})`;
+  }).join("\n");
+}
+var listAppsToolDefinition = {
+  name: "list_apps",
+  description: "List apps uploaded to BrowserStack App Automate. Reads BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY from environment.",
+  inputSchema: {
+    sortBy: z16.enum(["app_name", "uploaded_at"]).optional().default("uploaded_at").describe("Sort order for results"),
+    organizationWide: coerceBoolean.optional().default(false).describe("List apps uploaded by all users in the organization (uses recent_group_apps endpoint). Defaults to false (own uploads only)."),
+    limit: z16.number().int().min(1).optional().default(20).describe("Maximum number of apps to return (only applies when organizationWide is true, default 20)")
+  }
+};
+var listAppsTool = async ({ sortBy = "uploaded_at", organizationWide = false, limit = 20 }) => {
+  const auth = getAuth();
+  if (!auth) {
+    return { isError: true, content: [{ type: "text", text: "Missing credentials: set BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY environment variables." }] };
+  }
+  try {
+    let url = `${BS_API}/app-automate/${organizationWide ? "recent_group_apps" : "recent_apps"}`;
+    if (organizationWide && limit) url += `?limit=${limit}`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Basic ${auth}` }
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      return { isError: true, content: [{ type: "text", text: `BrowserStack API error ${res.status}: ${body}` }] };
+    }
+    const raw = await res.json();
+    let apps = Array.isArray(raw) ? raw : [];
+    apps = sortBy === "app_name" ? apps.sort((a, b) => a.app_name.localeCompare(b.app_name)) : apps.sort((a, b) => new Date(b.uploaded_at).getTime() - new Date(a.uploaded_at).getTime());
+    return { content: [{ type: "text", text: formatAppList(apps) }] };
+  } catch (e) {
+    return { isError: true, content: [{ type: "text", text: `Error listing apps: ${e}` }] };
+  }
+};
+var uploadAppToolDefinition = {
+  name: "upload_app",
+  description: "Upload a local .apk or .ipa to BrowserStack App Automate. Returns a bs:// URL for use in start_session.",
+  inputSchema: {
+    path: z16.string().describe("Absolute path to the .apk or .ipa file"),
+    customId: z16.string().optional().describe("Optional custom ID for the app (used to reference it later)")
+  }
+};
+var uploadAppTool = async ({ path, customId }) => {
+  const auth = getAuth();
+  if (!auth) {
+    return { isError: true, content: [{ type: "text", text: "Missing credentials: set BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY environment variables." }] };
+  }
+  if (!existsSync2(path)) {
+    return { isError: true, content: [{ type: "text", text: `File not found: ${path}` }] };
+  }
+  try {
+    const form = new FormData();
+    const stream = createReadStream(path);
+    const fileName = path.split("/").pop() ?? "app";
+    form.append("file", new Blob([stream]), fileName);
+    if (customId) form.append("custom_id", customId);
+    const res = await fetch(`${BS_API}/app-automate/upload`, {
+      method: "POST",
+      headers: { Authorization: `Basic ${auth}` },
+      body: form
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      return { isError: true, content: [{ type: "text", text: `Upload failed ${res.status}: ${body}` }] };
+    }
+    const data = await res.json();
+    const customIdNote = data.custom_id ? `
+Custom ID: ${data.custom_id}` : "";
+    return { content: [{ type: "text", text: `Upload successful.
+App URL: ${data.app_url}${customIdNote}
+
+Use this URL as the "app" parameter in start_session with provider: "browserstack".` }] };
+  } catch (e) {
+    return { isError: true, content: [{ type: "text", text: `Error uploading app: ${e}` }] };
+  }
+};
+
 // src/server.ts
 console.log = (...args) => console.error("[LOG]", ...args);
 console.info = (...args) => console.error("[INFO]", ...args);
@@ -3478,11 +3767,15 @@ registerTool(hideKeyboardToolDefinition, hideKeyboardTool);
 registerTool(setGeolocationToolDefinition, setGeolocationTool);
 registerTool(executeScriptToolDefinition, withRecording("execute_script", executeScriptTool));
 registerTool(getElementsToolDefinition, getElementsTool);
+registerTool(listAppsToolDefinition, listAppsTool);
+registerTool(uploadAppToolDefinition, uploadAppTool);
 registerResource(sessionsIndexResource);
 registerResource(sessionCurrentStepsResource);
 registerResource(sessionCurrentCodeResource);
 registerResource(sessionStepsResource);
 registerResource(sessionCodeResource);
+registerResource(browserstackLocalBinaryResource);
+registerResource(capabilitiesResource);
 registerResource(elementsResource);
 registerResource(accessibilityResource);
 registerResource(screenshotResource);