@wdio/mcp 2.3.1 → 2.4.0

package/README.md

@@ -83,6 +83,8 @@ appium
 - **Page Analysis**: Get visible elements, accessibility trees, take screenshots
 - **Cookie Management**: Get, set, and delete cookies
 - **Scrolling**: Smooth scrolling with configurable distances
+- **Attach to running Chrome**: Connect to an existing Chrome window via `--remote-debugging-port` — ideal for testing authenticated or pre-configured sessions
+- **Device emulation**: Apply mobile/tablet presets (iPhone 15, Pixel 7, etc.) to simulate responsive layouts without a physical device
 
 ### Mobile App Automation (iOS/Android)
 
@@ -102,6 +104,8 @@ appium
 | `start_browser`     | Start a browser session (Chrome, Firefox, Edge, Safari; headless/headed, custom dimensions) |
 | `start_app_session` | Start an iOS or Android app session via Appium (supports state preservation via noReset) |
 | `close_session`     | Close or detach from the current browser or app session (supports detach mode)           |
+| `attach_browser`    | Attach to a running Chrome instance via `--remote-debugging-port` (CDP) |
+| `emulate_device`    | Emulate a mobile/tablet device preset (viewport, DPR, UA, touch); requires BiDi session |
 
 ### Navigation & Page Interaction (Web & Mobile)
 
@@ -231,6 +235,37 @@ start_browser({
 })
 ```
 
+**Attach to a running Chrome instance:**
+
+```
+// First, launch Chrome with remote debugging enabled:
+//
+//   macOS (must quit Chrome first — open -a ignores args if Chrome is already running):
+//     pkill -x "Google Chrome" && sleep 1
+//     /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+//       --remote-debugging-port=9222 \
+//       --user-data-dir=/tmp/chrome-debug &
+//
+//   Linux:
+//     google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug &
+//
+//   Verify it's ready: curl http://localhost:9222/json/version
+attach_browser()
+attach_browser({port: 9333})
+attach_browser({port: 9222, navigationUrl: 'https://app.example.com'})
+```
+
+**Device emulation (requires BiDi session):**
+
+```
+// Device emulation (requires BiDi session)
+start_browser({capabilities: {webSocketUrl: true}})
+emulate_device()                         // list available presets
+emulate_device({device: 'iPhone 15'})    // activate emulation
+emulate_device({device: 'Pixel 7'})      // switch device
+emulate_device({device: 'reset'})        // restore desktop defaults
+```
+
 ### Mobile App Automation
 
 **Testing an iOS app on simulator:**

package/lib/server.js

@@ -164,13 +164,14 @@ var closeSessionTool = async (args = {}) => {
     const browser = getBrowser();
     const sessionId = state.currentSession;
     const metadata = state.sessionMetadata.get(sessionId);
-    if (!args.detach) {
+    const effectiveDetach = args.detach || !!metadata?.isAttached;
+    if (!effectiveDetach) {
       await browser.deleteSession();
     }
     state.browsers.delete(sessionId);
     state.sessionMetadata.delete(sessionId);
     state.currentSession = null;
-    const action = args.detach ? "detached from" : "closed";
+    const action = effectiveDetach ? "detached from" : "closed";
     const note = args.detach && !metadata?.isAttached ? "\nNote: Session will remain active on Appium server." : "";
     return {
       content: [{ type: "text", text: `Session ${sessionId} ${action}${note}` }]
@@ -375,7 +376,7 @@ var startAppToolDefinition = {
     udid: z5.string().optional().describe('Unique Device Identifier for iOS real device testing (e.g., "00008030-001234567890002E")'),
     noReset: z5.boolean().optional().describe("Do not reset app state before session (preserves app data). Default: false"),
     fullReset: z5.boolean().optional().describe("Uninstall app before/after session. Default: true. Set to false with noReset=true to preserve app state completely"),
-    newCommandTimeout: z5.number().min(0).optional().describe("How long (in seconds) Appium will wait for a new command before assuming the client has quit and ending the session. Default: 60. Set to 300 for 5 minutes, etc."),
+    newCommandTimeout: z5.number().min(0).optional().default(300).describe("How long (in seconds) Appium will wait for a new command before assuming the client has quit and ending the session. Default: 300."),
     capabilities: z5.record(z5.string(), z5.unknown()).optional().describe("Additional Appium/WebDriver capabilities to merge with defaults (e.g. appium:udid, appium:chromedriverExecutable, appium:autoWebview)")
   }
 };
@@ -404,7 +405,7 @@ var startAppTool = async (args) => {
       udid,
       noReset,
       fullReset,
-      newCommandTimeout,
+      newCommandTimeout = 300,
       capabilities: userCapabilities = {}
     } = args;
     if (!appPath && noReset !== true) {
@@ -2569,6 +2570,186 @@ var executeScriptTool = async (args) => {
   }
 };
 
+// src/tools/attach-browser.tool.ts
+import { remote as remote3 } from "webdriverio";
+import { z as z16 } from "zod";
+var attachBrowserToolDefinition = {
+  name: "attach_browser",
+  description: `Attach to a Chrome instance already running with --remote-debugging-port.
+
+Start Chrome first (quit any running Chrome instance before launching):
+
+  macOS \u2014 with real profile (preserves extensions, cookies, logins):
+    pkill -x "Google Chrome" && sleep 1
+    /Applications/Google Chrome.app/Contents/MacOS/Google Chrome --remote-debugging-port=9222 --user-data-dir="$HOME/Library/Application Support/Google/Chrome" --profile-directory=Default &
+
+  macOS \u2014 with fresh profile (lightweight, no extensions):
+    pkill -x "Google Chrome" && sleep 1
+    /Applications/Google Chrome.app/Contents/MacOS/Google Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug &
+
+  Linux \u2014 with real profile:
+    google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/google-chrome" --profile-directory=Default &
+
+  Linux \u2014 with fresh profile:
+    google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug &
+
+Verify Chrome is ready: curl http://localhost:9222/json/version
+
+Then call attach_browser() to hand control to the AI. All other tools (navigate, click, get_visible_elements, etc.) will work on the attached session. Use close_session() to detach without closing Chrome.`,
+  inputSchema: {
+    port: z16.number().default(9222).describe("Chrome remote debugging port (default: 9222)"),
+    host: z16.string().default("localhost").describe("Host where Chrome is running (default: localhost)"),
+    userDataDir: z16.string().default("/tmp/chrome-debug").describe('Chrome user data directory \u2014 must match the --user-data-dir used when launching Chrome. Use your real profile path (e.g. "$HOME/Library/Application Support/Google/Chrome") to preserve extensions and logins, or /tmp/chrome-debug for a fresh profile (default: /tmp/chrome-debug)'),
+    navigationUrl: z16.string().optional().describe("URL to navigate to immediately after attaching")
+  }
+};
+async function getActiveTabUrl(host, port) {
+  try {
+    const res = await fetch(`http://${host}:${port}/json`);
+    const tabs = await res.json();
+    const page = tabs.find((t) => t.type === "page" && t.url && !t.url.startsWith("devtools://"));
+    return page?.url ?? null;
+  } catch {
+    return null;
+  }
+}
+var attachBrowserTool = async ({
+  port = 9222,
+  host = "localhost",
+  userDataDir = "/tmp/chrome-debug",
+  navigationUrl
+}) => {
+  try {
+    const state2 = getBrowser.__state;
+    const activeUrl = navigationUrl ?? await getActiveTabUrl(host, port);
+    const browser = await remote3({
+      capabilities: {
+        browserName: "chrome",
+        "goog:chromeOptions": {
+          debuggerAddress: `${host}:${port}`,
+          args: [`--user-data-dir=${userDataDir}`]
+        }
+      }
+    });
+    const { sessionId } = browser;
+    state2.browsers.set(sessionId, browser);
+    state2.currentSession = sessionId;
+    state2.sessionMetadata.set(sessionId, {
+      type: "browser",
+      capabilities: browser.capabilities,
+      isAttached: true
+    });
+    if (activeUrl) {
+      await browser.url(activeUrl);
+    }
+    const title = await browser.getTitle();
+    const url = await browser.getUrl();
+    return {
+      content: [{
+        type: "text",
+        text: `Attached to Chrome on ${host}:${port}
+Session ID: ${sessionId}
+Current page: "${title}" (${url})`
+      }]
+    };
+  } catch (e) {
+    return {
+      content: [{ type: "text", text: `Error attaching to browser: ${e}` }]
+    };
+  }
+};
+
+// src/tools/emulate-device.tool.ts
+import { z as z17 } from "zod";
+var restoreFunctions = /* @__PURE__ */ new Map();
+var emulateDeviceToolDefinition = {
+  name: "emulate_device",
+  description: `Emulate a mobile or tablet device in the current browser session (sets viewport, DPR, user-agent, touch events).
+
+Requires a BiDi-enabled session: start_browser({ capabilities: { webSocketUrl: true } })
+
+Usage:
+  emulate_device()                    \u2014 list available device presets
+  emulate_device({ device: "iPhone 15" })  \u2014 activate emulation
+  emulate_device({ device: "reset" }) \u2014 restore desktop defaults`,
+  inputSchema: {
+    device: z17.string().optional().describe(
+      'Device preset name (e.g. "iPhone 15", "Pixel 7"). Omit to list available presets. Pass "reset" to restore desktop defaults.'
+    )
+  }
+};
+var emulateDeviceTool = async ({
+  device
+}) => {
+  try {
+    const browser = getBrowser();
+    const state2 = getBrowser.__state;
+    const sessionId = state2.currentSession;
+    const metadata = state2.sessionMetadata.get(sessionId);
+    if (metadata?.type === "ios" || metadata?.type === "android") {
+      return {
+        content: [{ type: "text", text: "Error: emulate_device is only supported for web browser sessions, not iOS/Android." }]
+      };
+    }
+    if (!browser.isBidi) {
+      return {
+        content: [{
+          type: "text",
+          text: "Error: emulate_device requires a BiDi-enabled session.\nRestart the browser with: start_browser({ capabilities: { webSocketUrl: true } })"
+        }]
+      };
+    }
+    if (!device) {
+      try {
+        await browser.emulate("device", "\0");
+      } catch (e) {
+        const msg = String(e);
+        const match = msg.match(/please use one of the following: (.+)$/);
+        if (match) {
+          const names = match[1].split(", ").sort();
+          return {
+            content: [{ type: "text", text: `Available devices (${names.length}):
+${names.join("\n")}` }]
+          };
+        }
+        return { content: [{ type: "text", text: `Error listing devices: ${e}` }] };
+      }
+      return { content: [{ type: "text", text: "Could not retrieve device list." }] };
+    }
+    if (device === "reset") {
+      const restoreFn = restoreFunctions.get(sessionId);
+      if (!restoreFn) {
+        return { content: [{ type: "text", text: "No active device emulation to reset." }] };
+      }
+      await restoreFn();
+      restoreFunctions.delete(sessionId);
+      return { content: [{ type: "text", text: "Device emulation reset to desktop defaults." }] };
+    }
+    try {
+      const restoreFn = await browser.emulate("device", device);
+      restoreFunctions.set(sessionId, restoreFn);
+      return {
+        content: [{ type: "text", text: `Emulating "${device}".` }]
+      };
+    } catch (e) {
+      const msg = String(e);
+      if (msg.includes("Unknown device name")) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error: Unknown device "${device}". Call emulate_device() with no arguments to list valid names.`
+          }]
+        };
+      }
+      return { content: [{ type: "text", text: `Error: ${e}` }] };
+    }
+  } catch (e) {
+    return {
+      content: [{ type: "text", text: `Error: ${e}` }]
+    };
+  }
+};
+
 // package.json
 var package_default = {
   name: "@wdio/mcp",
@@ -2577,7 +2758,7 @@ var package_default = {
     type: "git",
     url: "git://github.com/webdriverio/mcp.git"
   },
-  version: "2.3.0",
+  version: "2.3.1",
   description: "MCP server with WebdriverIO for browser and mobile app automation (iOS/Android via Appium)",
   main: "./lib/server.js",
   module: "./lib/server.js",
@@ -2669,6 +2850,8 @@ var registerTool = (definition, callback) => server.registerTool(definition.name
 registerTool(startBrowserToolDefinition, startBrowserTool);
 registerTool(startAppToolDefinition, startAppTool);
 registerTool(closeSessionToolDefinition, closeSessionTool);
+registerTool(attachBrowserToolDefinition, attachBrowserTool);
+registerTool(emulateDeviceToolDefinition, emulateDeviceTool);
 registerTool(navigateToolDefinition, navigateTool);
 registerTool(getVisibleElementsToolDefinition, getVisibleElementsTool);
 registerTool(getAccessibilityToolDefinition, getAccessibilityTreeTool);