@wdio/mcp 3.5.0 → 3.5.2

package/lib/server.js

@@ -46,7 +46,7 @@ var package_default = {
     type: "git",
     url: "git://github.com/webdriverio/mcp.git"
   },
-  version: "3.4.4",
+  version: "3.5.1",
   description: "MCP server with WebdriverIO for browser and mobile app automation (iOS/Android via Appium)",
   main: "./lib/server.js",
   module: "./lib/server.js",
@@ -97,6 +97,7 @@ var package_default = {
     "@xmldom/xmldom": "^0.9.10",
     "browserstack-local": "^1.5.12",
     "puppeteer-core": "^24.40.0",
+    saucelabs: "^9.0.2",
     sharp: "^0.34.5",
     webdriverio: "^9.27.0",
     xpath: "^0.0.34",
@@ -2130,9 +2131,7 @@ init_state();
 import sharp from "sharp";
 
 // src/trace/state.ts
-import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
-var { version: LIBRARY_VERSION } = require2("../../package.json");
+var libraryVersion = package_default.version;
 var traceSessions = /* @__PURE__ */ new Map();
 function createTraceSession(sessionId, browserName, viewport, title, sessionType = "browser") {
   const prefix = sessionId.slice(0, 8);
@@ -2156,7 +2155,7 @@ function createTraceSession(sessionId, browserName, viewport, title, sessionType
     type: "context-options",
     origin: "library",
     libraryName: "@wdio/mcp",
-    libraryVersion: LIBRARY_VERSION,
+    libraryVersion,
     browserName,
     platform: process.platform === "darwin" ? "darwin" : process.platform === "win32" ? "windows" : "linux",
     wallTime: session.startWallTime,
@@ -2429,6 +2428,71 @@ var browserstackLocalBinaryResource = {
   }
 };
 
+// src/resources/saucelabs-local.resource.ts
+function getLocalBinaryInfo2() {
+  const platform2 = process.platform;
+  const arch = process.arch;
+  if (platform2 === "darwin") {
+    return {
+      downloadUrl: "https://saucelabs.com/downloads/sc-4.9.2-osx.zip",
+      platform: "macOS",
+      arch: arch === "arm64" ? "Apple Silicon" : "Intel x64",
+      binaryName: "sc"
+    };
+  }
+  if (platform2 === "win32") {
+    return {
+      downloadUrl: "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
+      platform: "Windows",
+      arch: "x86/x64",
+      binaryName: "sc.exe"
+    };
+  }
+  return {
+    downloadUrl: "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
+    platform: "Linux",
+    arch: arch === "arm64" ? "ARM64" : "x64",
+    binaryName: "sc"
+  };
+}
+var saucelabsLocalBinaryResource = {
+  name: "saucelabs-local-binary",
+  uri: "wdio://saucelabs/local-binary",
+  description: "Sauce Connect Proxy binary download URL and daemon setup instructions for the current platform. Only needed for tunnel: 'external' \u2014 when tunnel: true the SDK auto-manages Sauce Connect for you.",
+  handler: async () => {
+    const info = getLocalBinaryInfo2();
+    const username = process.env.SAUCE_USERNAME ?? "<SAUCE_USERNAME>";
+    const accessKey = process.env.SAUCE_ACCESS_KEY ?? "<SAUCE_ACCESS_KEY>";
+    const region = process.env.SAUCE_REGION ?? "eu-central-1";
+    const content = {
+      requirement: "ONLY needed for tunnel: 'external'. Use tunnel: true instead \u2014 the SDK starts and stops Sauce Connect automatically. With tunnel: 'external', you MUST start the daemon manually BEFORE calling start_session, and set tunnelName to match the running tunnel.",
+      platform: info.platform,
+      arch: info.arch,
+      downloadUrl: info.downloadUrl,
+      ...info.note ? { note: info.note } : {},
+      setup: [
+        `1. Download: curl -O ${info.downloadUrl}`,
+        `2. Unzip: ${info.downloadUrl.endsWith(".tar.gz") ? `tar -xzf ${info.downloadUrl.split("/").pop()}` : `unzip ${info.downloadUrl.split("/").pop()}`}`,
+        `3. Make executable (macOS/Linux): chmod +x ${info.binaryName}`,
+        `4. Start daemon: ./${info.binaryName} -u ${username} -k ${accessKey} --region ${region}`
+      ],
+      commands: {
+        start: `./${info.binaryName} -u ${username} -k ${accessKey} --region ${region}`,
+        stop: `./${info.binaryName} --stop`,
+        status: `./${info.binaryName} --status`
+      },
+      afterDaemonIsRunning: "Call start_session with tunnel: 'external' and tunnelName matching this daemon to route traffic through it."
+    };
+    return {
+      contents: [{
+        uri: "wdio://saucelabs/local-binary",
+        mimeType: "application/json",
+        text: JSON.stringify(content, null, 2)
+      }]
+    };
+  }
+};
+
 // src/resources/sessions.resource.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -2455,6 +2519,7 @@ function generateStep(step, history) {
     case "start_session": {
       const platform2 = p.platform;
       const isBrowserStack = "bstack:options" in history.capabilities;
+      const isSauceLabs = "sauce:options" in history.capabilities;
       const capJson = indentJson(history.capabilities).split("\n").map((line, i) => i > 0 ? `  ${line}` : line).join("\n");
       if (isBrowserStack) {
         const nav = platform2 === "browser" && p.navigationUrl ? `
@@ -2471,6 +2536,22 @@ await browser.url('${escapeStr(p.navigationUrl)}');` : "";
           `});${nav}`
         ].join("\n");
       }
+      if (isSauceLabs) {
+        const region = history.capabilities["sauce:options"]?.region ?? "eu-central-1";
+        const nav = platform2 === "browser" && p.navigationUrl ? `
+await browser.url('${escapeStr(p.navigationUrl)}');` : "";
+        return [
+          "const browser = await remote({",
+          "  protocol: 'https',",
+          `  hostname: 'ondemand.${region}.saucelabs.com',`,
+          "  port: 443,",
+          "  path: '/wd/hub',",
+          "  user: process.env.SAUCE_USERNAME,",
+          "  key: process.env.SAUCE_ACCESS_KEY,",
+          `  capabilities: ${capJson}`,
+          `});${nav}`
+        ].join("\n");
+      }
       if (platform2 === "browser") {
         const nav = p.navigationUrl ? `
 await browser.url('${escapeStr(p.navigationUrl)}');` : "";
@@ -2533,8 +2614,10 @@ function bsStatusUpdateLines(sessionType) {
 }
 function generateCode(history) {
   const bstackOptions = history.capabilities["bstack:options"];
+  const sauceOptions = history.capabilities["sauce:options"];
   const isBrowserStack = bstackOptions !== void 0;
-  const usesBrowserstackLocal = bstackOptions?.local === true;
+  const isSauceLabs = sauceOptions !== void 0;
+  const usesLocalTunnel = isBrowserStack ? bstackOptions?.local === true : sauceOptions?.tunnelName !== void 0;
   const steps = history.steps.map((step) => generateStep(step, history)).join("\n").split("\n").map((line) => `  ${line}`).join("\n");
   if (isBrowserStack) {
     const bsSteps = steps.replace(/const browser = await remote\(/g, "browser = await remote(");
@@ -2545,7 +2628,7 @@ function generateCode(history) {
 ${statusUpdate}
     await browser.deleteSession();
   }`;
-    if (usesBrowserstackLocal) {
+    if (usesLocalTunnel) {
       const tunnelSetup = [
         "",
         "const tunnel = new BrowserstackTunnel();",
@@ -2581,6 +2664,64 @@ ${statusUpdate}
       "}"
     ].join("\n");
   }
+  if (isSauceLabs) {
+    const slSteps = steps.replace(/const browser = await remote\(/g, "browser = await remote(");
+    const preamble = "let browser;\nlet slStatus = 'passed';\nlet slReason;";
+    const catchBlock = "} catch (e) {\n  slStatus = 'failed';\n  slReason = String(e);\n  throw e;";
+    const slRegion = sauceOptions?.region ?? "eu-central-1";
+    const statusUpdate = [
+      "    const slAuth = Buffer.from(`${process.env.SAUCE_USERNAME}:${process.env.SAUCE_ACCESS_KEY}`).toString('base64');",
+      `    await fetch(\`https://api.${slRegion}.saucelabs.com/rest/v1/\${process.env.SAUCE_USERNAME}/jobs/\` + browser.sessionId, {`,
+      "      method: 'PUT',",
+      "      headers: { Authorization: 'Basic ' + slAuth, 'Content-Type': 'application/json' },",
+      "      body: JSON.stringify({ passed: slStatus === 'passed' })",
+      "    });"
+    ].join("\n");
+    const finallyLines = [
+      "  if (browser) {",
+      statusUpdate,
+      "    await browser.deleteSession();",
+      "  }"
+    ];
+    if (usesLocalTunnel) {
+      const tunnelSetup = [
+        "",
+        "import SauceLabs from 'saucelabs';",
+        "",
+        "const sl = new SauceLabs({",
+        "  user: process.env.SAUCE_USERNAME,",
+        "  key: process.env.SAUCE_ACCESS_KEY,",
+        `  region: '${slRegion}',`,
+        "});",
+        "const sc = await sl.startSauceConnect({ tunnelName: 'wdio-mcp-tunnel' });",
+        "const stopTunnel = () => sc.close();",
+        ""
+      ].join("\n");
+      return [
+        "import { remote } from 'webdriverio';",
+        tunnelSetup,
+        preamble,
+        "try {",
+        slSteps,
+        catchBlock,
+        "} finally {",
+        ...finallyLines,
+        "  await stopTunnel();",
+        "}"
+      ].join("\n");
+    }
+    return [
+      "import { remote } from 'webdriverio';",
+      "",
+      preamble,
+      "try {",
+      slSteps,
+      catchBlock,
+      "} finally {",
+      ...finallyLines,
+      "}"
+    ].join("\n");
+  }
   return `import { remote } from 'webdriverio';
 
 try {
@@ -3278,7 +3419,7 @@ import { z as z14 } from "zod";
 // src/session/lifecycle.ts
 init_state();
 import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 
 // src/providers/local-browser.provider.ts
 var LocalBrowserProvider = class {
@@ -3533,6 +3674,13 @@ import { promisify } from "util";
 import { tmpdir as tmpdir2 } from "os";
 import { join as join2 } from "path";
 import { Local as BrowserstackTunnel } from "browserstack-local";
+
+// src/utils/auth.ts
+function basicAuth(user, key) {
+  return Buffer.from(`${user}:${key}`).toString("base64");
+}
+
+// src/providers/cloud/browserstack.provider.ts
 var BrowserStackProvider = class {
   name = "browserstack";
   getConnectionConfig(options) {
@@ -3550,7 +3698,7 @@ var BrowserStackProvider = class {
   buildCapabilities(options) {
     const platform2 = options.platform;
     const userCapabilities = options.capabilities ?? {};
-    const browserstackLocal = options.browserstackLocal;
+    const browserstackLocal = options.tunnel ?? options.browserstackLocal;
     if (platform2 === "browser") {
       const bstackOptions2 = {
         browserVersion: options.browserVersion ?? "latest"
@@ -3628,7 +3776,7 @@ var BrowserStackProvider = class {
     const key = process.env.BROWSERSTACK_ACCESS_KEY;
     if (!user || !key) return;
     const baseUrl = sessionType === "browser" ? "https://api.browserstack.com/automate/sessions" : "https://api-cloud.browserstack.com/app-automate/sessions";
-    const auth = Buffer.from(`${user}:${key}`).toString("base64");
+    const auth = basicAuth(user, key);
     const body = { status: result.status, ...result.reason ? { reason: result.reason } : {} };
     await fetch(`${baseUrl}/${sessionId}.json`, {
       method: "PUT",
@@ -3639,11 +3787,153 @@ var BrowserStackProvider = class {
 };
 var browserStackProvider = new BrowserStackProvider();
 
+// src/providers/cloud/saucelabs.provider.ts
+import { tmpdir as tmpdir3 } from "os";
+import { join as join3 } from "path";
+var SauceLabsProvider = class {
+  name = "saucelabs";
+  resolveRegion(options) {
+    return options.region ?? "eu-central-1";
+  }
+  getConnectionConfig(options) {
+    const region = this.resolveRegion(options);
+    return {
+      protocol: "https",
+      hostname: `ondemand.${region}.saucelabs.com`,
+      port: 443,
+      path: "/wd/hub",
+      user: process.env.SAUCE_USERNAME,
+      key: process.env.SAUCE_ACCESS_KEY
+    };
+  }
+  buildCapabilities(options) {
+    const platform2 = options.platform;
+    const region = this.resolveRegion(options);
+    const userCapabilities = options.capabilities ?? {};
+    const saucelabsLocal = options.tunnel ?? options.saucelabsLocal;
+    const reporting = options.reporting;
+    const sauceOptions = { region };
+    if (reporting?.build) sauceOptions.build = reporting.build;
+    if (reporting?.session) sauceOptions.name = reporting.session;
+    else if (reporting?.project) sauceOptions.name = reporting.project;
+    if (saucelabsLocal) {
+      sauceOptions.tunnelName = options.tunnelName;
+    }
+    if (platform2 === "browser") {
+      return {
+        browserName: options.browser ?? "chrome",
+        browserVersion: options.browserVersion ?? "latest",
+        platformName: options.os ?? "Linux",
+        "sauce:options": sauceOptions,
+        ...userCapabilities
+      };
+    }
+    const mobileBrowser = options.browser;
+    if (mobileBrowser) {
+      sauceOptions.appiumVersion = "2.11.0";
+      if (options.deviceOrientation) sauceOptions.deviceOrientation = options.deviceOrientation;
+      const caps = {
+        platformName: platform2,
+        browserName: mobileBrowser,
+        "appium:deviceName": options.deviceName,
+        "appium:platformVersion": options.platformVersion,
+        "appium:automationName": options.automationName ?? (platform2 === "ios" ? "XCUITest" : "UiAutomator2"),
+        "appium:newCommandTimeout": options.newCommandTimeout ?? 300,
+        "sauce:options": sauceOptions
+      };
+      return { ...caps, ...userCapabilities };
+    }
+    sauceOptions.appiumVersion = "latest";
+    const autoAcceptAlerts = options.autoAcceptAlerts;
+    const autoDismissAlerts = options.autoDismissAlerts;
+    return {
+      platformName: platform2,
+      "appium:app": options.app,
+      "appium:deviceName": options.deviceName,
+      "appium:platformVersion": options.platformVersion,
+      "appium:automationName": options.automationName ?? (platform2 === "ios" ? "XCUITest" : "UiAutomator2"),
+      "appium:autoGrantPermissions": options.autoGrantPermissions ?? true,
+      "appium:autoAcceptAlerts": autoDismissAlerts ? void 0 : autoAcceptAlerts ?? true,
+      "appium:autoDismissAlerts": autoDismissAlerts,
+      "appium:newCommandTimeout": options.newCommandTimeout ?? 300,
+      "sauce:options": sauceOptions,
+      ...userCapabilities
+    };
+  }
+  getSessionType(options) {
+    const platform2 = options.platform;
+    if (platform2 === "browser") return "browser";
+    return platform2;
+  }
+  shouldAutoDetach(_options) {
+    return false;
+  }
+  async startTunnel(options) {
+    const region = this.resolveRegion(options);
+    const tunnelName = options.tunnelName ?? `wdio-mcp-${Date.now()}`;
+    const logFile = join3(tmpdir3(), "sauce-connect.log");
+    console.error(`[SauceLabs] Starting tunnel "${tunnelName}" (region: ${region})`);
+    try {
+      const { default: SauceLabs } = await import("saucelabs");
+      const api = new SauceLabs({ user: process.env.SAUCE_USERNAME ?? "", key: process.env.SAUCE_ACCESS_KEY ?? "", region });
+      return api.startSauceConnect({
+        tunnelName,
+        logFile,
+        logger: (msg) => console.error(`[SauceConnect] ${msg}`)
+      });
+    } catch (e) {
+      const msg = (e !== null && typeof e === "object" ? e.message : void 0) ?? String(e);
+      if (msg.includes("already running") || msg.includes("another instance")) {
+        console.error("[SauceLabs] Tunnel already running \u2014 reusing existing tunnel");
+        return null;
+      }
+      throw e;
+    }
+  }
+  async onSessionClose(sessionId, _sessionType, result, _tunnelHandle, _browser, region) {
+    const effectiveRegion = region ?? "eu-central-1";
+    const user = process.env.SAUCE_USERNAME;
+    const key = process.env.SAUCE_ACCESS_KEY;
+    if (user && key) {
+      try {
+        const auth = basicAuth(user, key);
+        const body = { passed: result.status === "passed" };
+        const apiUrl = `https://api.${effectiveRegion}.saucelabs.com/rest/v1/${user}/jobs/${sessionId}`;
+        console.error(`[SauceLabs] Setting job status for ${sessionId}: ${result.status}`);
+        await fetch(apiUrl, {
+          method: "PUT",
+          headers: {
+            Authorization: `Basic ${auth}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(body)
+        });
+        console.error("[SauceLabs] Job result set successfully via REST API");
+      } catch (e) {
+        console.error("[SauceLabs] Failed to set job result via REST API:", e);
+      }
+    }
+  }
+  async stopTunnel(tunnelHandle) {
+    if (tunnelHandle) {
+      const sc = tunnelHandle;
+      await sc.close();
+    }
+  }
+};
+var sauceLabsProvider = new SauceLabsProvider();
+
 // src/providers/registry.ts
-function getProvider(providerName, platform2) {
-  if (providerName === "browserstack") return browserStackProvider;
+var providers = /* @__PURE__ */ new Map([
+  ["browserstack", browserStackProvider],
+  ["saucelabs", sauceLabsProvider]
+]);
+function getDefaultProvider(platform2) {
   return platform2 === "browser" ? localBrowserProvider : localAppiumProvider;
 }
+function getProvider(providerName, platform2) {
+  return providers.get(providerName) ?? getDefaultProvider(platform2);
+}
 
 // src/trace/zip-writer.ts
 import yazl from "yazl";
@@ -3673,10 +3963,10 @@ async function finalizeTrace(sessionId, browser) {
   if (!traceSession) return;
   try {
     await traceSession.screenshotChain;
-    const traceDir = join3(process.cwd(), ".trace");
+    const traceDir = join4(process.cwd(), ".trace");
     mkdirSync2(traceDir, { recursive: true });
     const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const outPath = join3(traceDir, `${timestamp}-${sessionId.slice(0, 8)}.zip`);
+    const outPath = join4(traceDir, `${timestamp}-${sessionId.slice(0, 8)}.zip`);
     const zipBuffer = await buildTraceZip(traceSession);
     writeFileSync2(outPath, zipBuffer);
     console.error(`[TRACE] Saved to ${outPath}`);
@@ -3728,11 +4018,16 @@ function registerSession(sessionId, browser, metadata, historyEntry) {
         if (oldMetadata?.provider) {
           const oldHistory = state2.sessionHistory.get(oldSessionId);
           const provider = getProvider(oldMetadata.provider, oldMetadata.type);
-          await provider.onSessionClose?.(oldSessionId, oldMetadata.type, getSessionResult(oldHistory), oldMetadata.tunnelHandle).catch(() => {
+          await provider.onSessionClose?.(oldSessionId, oldMetadata.type, getSessionResult(oldHistory), oldMetadata.tunnelHandle, oldBrowser, oldMetadata.region).catch(() => {
           });
         }
         await oldBrowser.deleteSession().catch(() => {
         });
+        if (oldMetadata?.provider && oldMetadata?.tunnelHandle) {
+          const provider = getProvider(oldMetadata.provider, oldMetadata.type);
+          await provider.stopTunnel?.(oldMetadata.tunnelHandle).catch(() => {
+          });
+        }
       })();
       state2.browsers.delete(oldSessionId);
       state2.sessionMetadata.delete(oldSessionId);
@@ -3755,12 +4050,20 @@ async function closeSession(sessionId, detach, isAttached, force) {
     if (metadata?.provider) {
       try {
         const provider = getProvider(metadata.provider, metadata.type);
-        await provider.onSessionClose?.(sessionId, metadata.type, getSessionResult(history), metadata.tunnelHandle);
+        await provider.onSessionClose?.(sessionId, metadata.type, getSessionResult(history), metadata.tunnelHandle, browser, metadata.region);
       } catch (e) {
         console.error("[WARN] Failed to run provider onSessionClose:", e);
       }
     }
     await browser.deleteSession();
+    if (metadata?.provider && metadata?.tunnelHandle) {
+      try {
+        const provider = getProvider(metadata.provider, metadata.type);
+        await provider.stopTunnel?.(metadata.tunnelHandle);
+      } catch (e) {
+        console.error("[WARN] Failed to stop tunnel:", e);
+      }
+    }
   }
   state2.browsers.delete(sessionId);
   state2.sessionMetadata.delete(sessionId);
@@ -3778,18 +4081,18 @@ var startSessionToolDefinition = {
   description: 'Starts a browser or mobile automation session. Only one active session at a time \u2014 starting a new one closes the existing session first. Use platform "browser" with a browser name, or "ios"/"android" with deviceName. Set attach: true to connect to a running Chrome via CDP instead of launching a new browser.',
   annotations: { title: "Start Session", destructiveHint: false },
   inputSchema: {
-    provider: z14.enum(["local", "browserstack"]).optional().default("local").describe("Session provider (default: local)"),
+    provider: z14.enum(["local", "browserstack", "saucelabs"]).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"),
+    browserVersion: z14.string().optional().describe("Browser version (cloud providers only, default: latest)"),
+    os: z14.string().optional().describe('Operating system (cloud providers only, e.g. "Windows", "OS X")'),
+    osVersion: z14.string().optional().describe('OS version (cloud providers only, e.g. "11", "Sequoia")'),
+    app: z14.string().optional().describe("App URL (bs://...) for BrowserStack or storage:filename= for Sauce Labs 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)"),
+    }).optional().describe("Cloud provider 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"),
@@ -3817,7 +4120,11 @@ var startSessionToolDefinition = {
       path: z14.string().optional(),
       protocol: z14.string().optional()
     }).optional().describe("Appium server connection (local provider only)"),
-    browserstackLocal: z14.union([coerceBoolean, z14.literal("external")]).optional().default(false).describe('Enable BrowserStack Local tunnel routing (BrowserStack only, default: false). true = auto-start tunnel before session and stop on close. "external" = tunnel already running externally, set local: true in capabilities only.'),
+    region: z14.enum(["us-west-1", "eu-central-1", "apac-southeast-1"]).optional().default("eu-central-1").describe('Sauce Labs region (default: eu-central-1). Only used with provider: "saucelabs".'),
+    tunnel: z14.union([z14.literal("external"), coerceBoolean]).optional().default(false).describe('Enable local tunnel routing (cloud providers only, default: false). true = auto-start tunnel before session and stop on close. "external" = tunnel already running externally.'),
+    tunnelName: z14.string().optional().describe('Tunnel identifier name. With tunnel: "external" this must match the running tunnel. With tunnel: true a unique name is auto-generated if not provided.'),
+    browserstackLocal: z14.union([z14.literal("external"), coerceBoolean]).optional().describe('Deprecated: use "tunnel" instead. Enable BrowserStack Local tunnel routing.'),
+    saucelabsLocal: z14.union([z14.literal("external"), coerceBoolean]).optional().describe('Deprecated: use "tunnel" instead. Enable Sauce Connect tunnel routing.'),
     navigationUrl: z14.string().optional().describe("URL to navigate to after starting"),
     capabilities: z14.record(z14.string(), z14.unknown()).optional().describe("Additional capabilities to merge")
   }
@@ -3896,15 +4203,19 @@ async function startBrowserSession(args) {
   const effectiveHeadless = headless && headlessSupported;
   const provider = getProvider(args.provider ?? "local", "browser");
   const connectionConfig = provider.getConnectionConfig(args);
+  const effectiveTunnel = args.tunnel ?? args.browserstackLocal ?? args.saucelabsLocal ?? false;
+  const tunnelEnabled = effectiveTunnel === true;
+  const tunnelName = tunnelEnabled && !args.tunnelName ? `wdio-mcp-${Date.now()}` : args.tunnelName;
   const mergedCapabilities = provider.buildCapabilities({
     ...args,
     browser,
     headless,
     windowWidth,
     windowHeight,
-    capabilities: userCapabilities
+    capabilities: userCapabilities,
+    tunnelName
   });
-  const tunnelHandle = args.browserstackLocal === true ? await provider.startTunnel?.(args) : void 0;
+  const tunnelHandle = tunnelEnabled ? await provider.startTunnel?.({ ...args, tunnelName }) : void 0;
   const wdioBrowser = await remote({ ...connectionConfig, capabilities: mergedCapabilities });
   const { sessionId } = wdioBrowser;
   const sessionMetadata = {
@@ -3912,6 +4223,8 @@ async function startBrowserSession(args) {
     capabilities: mergedCapabilities,
     isAttached: false,
     provider: args.provider ?? "local",
+    region: args.region,
+    tunnelName,
     tunnelHandle,
     trace: args.trace ?? false
   };
@@ -3960,8 +4273,11 @@ async function startMobileSession(args) {
   }
   const provider = getProvider(args.provider ?? "local", args.platform);
   const serverConfig = provider.getConnectionConfig(args);
-  const mergedCapabilities = provider.buildCapabilities(args);
-  const tunnelHandle = args.browserstackLocal === true ? await provider.startTunnel?.(args) : void 0;
+  const effectiveTunnel = args.tunnel ?? args.browserstackLocal ?? args.saucelabsLocal ?? false;
+  const tunnelEnabled = effectiveTunnel === true;
+  const tunnelName = tunnelEnabled && !args.tunnelName ? `wdio-mcp-${Date.now()}` : args.tunnelName;
+  const mergedCapabilities = provider.buildCapabilities({ ...args, tunnelName });
+  const tunnelHandle = tunnelEnabled ? await provider.startTunnel?.({ ...args, tunnelName }) : void 0;
   const browser = await remote({ ...serverConfig, capabilities: mergedCapabilities });
   const { sessionId } = browser;
   const shouldAutoDetach = provider.shouldAutoDetach(args);
@@ -3971,6 +4287,8 @@ async function startMobileSession(args) {
     capabilities: mergedCapabilities,
     isAttached: shouldAutoDetach,
     provider: args.provider ?? "local",
+    region: args.region,
+    tunnelName,
     tunnelHandle,
     trace: args.trace ?? false
   };
@@ -4154,51 +4472,112 @@ var switchFrameTool = async ({
   }
 };
 
-// src/tools/browserstack.tool.ts
-import { existsSync as existsSync2, createReadStream } from "fs";
+// src/tools/cloud-provider.tool.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
 import { z as z17 } 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})`;
+    const id = a.customId ? ` [${a.customId}]` : "";
+    const ts = a.uploadedAt ?? "unknown";
+    return `${a.name}${id} \u2014 ${a.ref} (${ts})`;
   }).join("\n");
 }
+var PROVIDER_CONFIGS = {
+  browserstack: {
+    name: "BrowserStack",
+    apiBase: "https://api-cloud.browserstack.com",
+    credsEnvNames: ["BROWSERSTACK_USERNAME", "BROWSERSTACK_ACCESS_KEY"],
+    listPath: "/app-automate/recent_apps",
+    supportsOrgWide: true,
+    parseListResponse: (raw) => {
+      const apps = Array.isArray(raw) ? raw : [];
+      return apps.map((a) => ({
+        name: `${a.app_name}`,
+        ref: `${a.app_url}`,
+        uploadedAt: `${a.uploaded_at}`,
+        customId: a.custom_id
+      }));
+    },
+    uploadPath: "/app-automate/upload",
+    uploadField: "file",
+    parseUploadResponse: (raw, fileName) => {
+      const data = raw;
+      return { appRef: data.app_url, appName: fileName };
+    }
+  },
+  saucelabs: {
+    name: "Sauce Labs",
+    apiBase: "https://api.eu-central-1.saucelabs.com",
+    // region overridden via param
+    credsEnvNames: ["SAUCE_USERNAME", "SAUCE_ACCESS_KEY"],
+    listPath: "/v1/storage/files",
+    supportsOrgWide: false,
+    parseListResponse: (raw) => {
+      const data = raw;
+      return (data.items ?? []).map((a) => ({
+        name: a.name,
+        ref: `storage:filename=${a.name}`,
+        uploadedAt: a.uploadTimestamp ? new Date(a.uploadTimestamp).toISOString() : void 0,
+        customId: a.customId
+      }));
+    },
+    uploadPath: "/v1/storage/upload",
+    uploadField: "payload",
+    parseUploadResponse: (raw, fileName) => {
+      const data = raw;
+      const name = data.item?.name ?? fileName;
+      return { appRef: `storage:filename=${name}`, appName: name };
+    }
+  }
+};
+function getProviderConfig(provider, region) {
+  const base = PROVIDER_CONFIGS[provider];
+  if (!base) return { error: `Unknown provider: ${provider}` };
+  const [userEnv, keyEnv] = base.credsEnvNames;
+  const user = process.env[userEnv];
+  const key = process.env[keyEnv];
+  if (!user || !key) {
+    const vars = base.credsEnvNames.join(" and ");
+    return { error: `Missing credentials: set ${vars} environment variables.` };
+  }
+  const config = provider === "saucelabs" ? { ...base, apiBase: `https://api.${region ?? "eu-central-1"}.saucelabs.com` } : base;
+  return { config, auth: basicAuth(user, key) };
+}
 var listAppsToolDefinition = {
   name: "list_apps",
-  description: "List apps uploaded to BrowserStack App Automate. Reads BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY from environment.",
-  annotations: { title: "List BrowserStack Apps", readOnlyHint: true, idempotentHint: true },
+  description: "List apps uploaded to a cloud provider (BrowserStack App Automate or Sauce Labs App Storage). Reads provider-specific credentials from environment.",
+  annotations: { title: "List Cloud Provider Apps", readOnlyHint: true, idempotentHint: true },
   inputSchema: {
+    provider: z17.enum(["browserstack", "saucelabs"]).describe("Cloud provider"),
     sortBy: z17.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: z17.number().int().min(1).optional().default(20).describe("Maximum number of apps to return (only applies when organizationWide is true, default 20)")
+    organizationWide: coerceBoolean.optional().default(false).describe("(BrowserStack only) List apps uploaded by all users in the organization. Defaults to false (own uploads only)."),
+    limit: z17.number().int().min(1).optional().default(20).describe("Maximum number of apps to return (only applies when organizationWide is true, default 20)"),
+    region: z17.enum(["us-west-1", "eu-central-1", "apac-southeast-1"]).optional().default("eu-central-1").describe("Sauce Labs region (default: eu-central-1)")
   }
 };
-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." }] };
+var listAppsTool = async (args) => {
+  const { provider, sortBy = "uploaded_at", organizationWide = false, limit = 20, region = "eu-central-1" } = args;
+  const resolved = getProviderConfig(provider, region);
+  if ("error" in resolved) {
+    return { isError: true, content: [{ type: "text", text: resolved.error }] };
   }
+  const { config, auth } = resolved;
   try {
-    let url = `${BS_API}/app-automate/${organizationWide ? "recent_group_apps" : "recent_apps"}`;
-    if (organizationWide && limit) url += `?limit=${limit}`;
+    let url = `${config.apiBase}${config.listPath}`;
+    if (config.supportsOrgWide && organizationWide) {
+      url = `${config.apiBase}/app-automate/recent_group_apps?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}` }] };
+      return { isError: true, content: [{ type: "text", text: `${config.name} 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());
+    let apps = config.parseListResponse(raw);
+    apps = sortBy === "app_name" ? apps.sort((a, b) => a.name.localeCompare(b.name)) : apps.sort((a, b) => (b.uploadedAt ?? "").localeCompare(a.uploadedAt ?? ""));
     return { content: [{ type: "text", text: formatAppList(apps) }] };
   } catch (e) {
     return { isError: true, content: [{ type: "text", text: `Error listing apps: ${e}` }] };
@@ -4206,28 +4585,33 @@ var listAppsTool = async ({ sortBy = "uploaded_at", organizationWide = false, li
 };
 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.",
-  annotations: { title: "Upload App to BrowserStack", destructiveHint: false },
+  description: "Upload a local .apk or .ipa to a cloud provider (BrowserStack App Automate or Sauce Labs App Storage). Returns the app URL for use in start_session.",
+  annotations: { title: "Upload App to Cloud Provider", destructiveHint: false },
   inputSchema: {
+    provider: z17.enum(["browserstack", "saucelabs"]).describe("Cloud provider"),
     path: z17.string().describe("Absolute path to the .apk or .ipa file"),
-    customId: z17.string().optional().describe("Optional custom ID for the app (used to reference it later)")
+    customId: z17.string().optional().describe("Optional custom ID for the app (used to reference it later)"),
+    region: z17.enum(["us-west-1", "eu-central-1", "apac-southeast-1"]).optional().default("eu-central-1").describe("Sauce Labs region (default: eu-central-1)")
   }
 };
-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." }] };
+var uploadAppTool = async (args) => {
+  const { provider, path, customId, region = "eu-central-1" } = args;
+  const resolved = getProviderConfig(provider, region);
+  if ("error" in resolved) {
+    return { isError: true, content: [{ type: "text", text: resolved.error }] };
   }
+  const { config, auth } = resolved;
   if (!existsSync2(path)) {
     return { isError: true, content: [{ type: "text", text: `File not found: ${path}` }] };
   }
+  const fileName = path.split("/").pop() ?? "app";
   try {
     const form = new FormData();
-    const stream = createReadStream(path);
-    const fileName = path.split("/").pop() ?? "app";
-    form.append("file", new Blob([stream]), fileName);
+    const fileBuffer = readFileSync(path);
+    const fileBlob = new Blob([fileBuffer], { type: "application/octet-stream" });
+    form.append(config.uploadField, fileBlob, fileName);
     if (customId) form.append("custom_id", customId);
-    const res = await fetch(`${BS_API}/app-automate/upload`, {
+    const res = await fetch(`${config.apiBase}${config.uploadPath}`, {
       method: "POST",
       headers: { Authorization: `Basic ${auth}` },
       body: form
@@ -4236,13 +4620,14 @@ var uploadAppTool = async ({ path, customId }) => {
       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}` : "";
+    const raw = await res.json();
+    const { appRef } = config.parseUploadResponse(raw, fileName);
+    const customIdNote = customId ? `
+Custom ID: ${customId}` : "";
     return { content: [{ type: "text", text: `Upload successful.
-App URL: ${data.app_url}${customIdNote}
+App: ${appRef}${customIdNote}
 
-Use this URL as the "app" parameter in start_session with provider: "browserstack".` }] };
+Use "${appRef}" as the "app" parameter in start_session with provider: "${provider}".` }] };
   } catch (e) {
     return { isError: true, content: [{ type: "text", text: `Error uploading app: ${e}` }] };
   }
@@ -4433,6 +4818,7 @@ function createServer() {
   registerResource(sessionStepsResource);
   registerResource(sessionCodeResource);
   registerResource(browserstackLocalBinaryResource);
+  registerResource(saucelabsLocalBinaryResource);
   registerResource(capabilitiesResource);
   registerResource(elementsResource);
   registerResource(accessibilityResource);