Merge pull request #35 from webdriverio/feature/attach-emulate-tools

Introduction of browser `attach` and `emulate` tools

Author: Winify

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:**

src/server.ts

@@ -54,6 +54,8 @@ import {
   setGeolocationToolDefinition,
 } from './tools/device.tool';
 import { executeScriptTool, executeScriptToolDefinition } from './tools/execute-script.tool';
+import { attachBrowserTool, attachBrowserToolDefinition } from './tools/attach-browser.tool';
+import { emulateDeviceTool, emulateDeviceToolDefinition } from './tools/emulate-device.tool';
 import pkg from '../package.json' with { type: 'json' };
 
 // IMPORTANT: Redirect all console output to stderr to avoid messing with MCP protocol (Chrome writes to console)
@@ -91,6 +93,8 @@ const registerTool = (definition: ToolDefinition, callback: ToolCallback) =>
 registerTool(startBrowserToolDefinition, startBrowserTool);
 registerTool(startAppToolDefinition, startAppTool);
 registerTool(closeSessionToolDefinition, closeSessionTool);
+registerTool(attachBrowserToolDefinition, attachBrowserTool);
+registerTool(emulateDeviceToolDefinition, emulateDeviceTool);
 registerTool(navigateToolDefinition, navigateTool);
 
 // Element Discovery

src/tools/app-session.tool.ts

@@ -28,7 +28,7 @@ export const startAppToolDefinition: ToolDefinition = {
     udid: z.string().optional().describe('Unique Device Identifier for iOS real device testing (e.g., "00008030-001234567890002E")'),
     noReset: z.boolean().optional().describe('Do not reset app state before session (preserves app data). Default: false'),
     fullReset: z.boolean().optional().describe('Uninstall app before/after session. Default: true. Set to false with noReset=true to preserve app state completely'),
-    newCommandTimeout: z.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: z.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: z.record(z.string(), z.unknown()).optional().describe('Additional Appium/WebDriver capabilities to merge with defaults (e.g. appium:udid, appium:chromedriverExecutable, appium:autoWebview)'),
   },
 };
@@ -82,7 +82,7 @@ export const startAppTool: ToolCallback = async (args: {
       udid,
       noReset,
       fullReset,
-      newCommandTimeout,
+      newCommandTimeout = 300,
       capabilities: userCapabilities = {},
     } = args;
 

src/tools/attach-browser.tool.ts

@@ -0,0 +1,104 @@
+import { remote } from 'webdriverio';
+import type { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types';
+import type { ToolDefinition } from '../types/tool';
+import { z } from 'zod';
+import { getBrowser } from './browser.tool';
+
+export const attachBrowserToolDefinition: ToolDefinition = {
+  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 — 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 — 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 — with real profile:
+    google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/google-chrome" --profile-directory=Default &
+
+  Linux — 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: z.number().default(9222).describe('Chrome remote debugging port (default: 9222)'),
+    host: z.string().default('localhost').describe('Host where Chrome is running (default: localhost)'),
+    userDataDir: z.string().default('/tmp/chrome-debug').describe('Chrome user data directory — 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: z.string().optional().describe('URL to navigate to immediately after attaching'),
+  },
+};
+
+async function getActiveTabUrl(host: string, port: number): Promise<string | null> {
+  try {
+    const res = await fetch(`http://${host}:${port}/json`);
+    const tabs = await res.json() as { type: string; url: string }[];
+    const page = tabs.find((t) => t.type === 'page' && t.url && !t.url.startsWith('devtools://'));
+    return page?.url ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export const attachBrowserTool: ToolCallback = async ({
+  port = 9222,
+  host = 'localhost',
+  userDataDir = '/tmp/chrome-debug',
+  navigationUrl,
+}: {
+  port?: number;
+  host?: string;
+  userDataDir?: string;
+  navigationUrl?: string;
+}): Promise<CallToolResult> => {
+  try {
+    const state = (getBrowser as any).__state;
+
+    // Capture the active tab URL before WebDriver blanks it
+    const activeUrl = navigationUrl ?? await getActiveTabUrl(host, port);
+
+    const browser = await remote({
+      capabilities: {
+        browserName: 'chrome',
+        'goog:chromeOptions': {
+          debuggerAddress: `${host}:${port}`,
+          args: [`--user-data-dir=${userDataDir}`],
+        },
+      },
+    });
+
+    const { sessionId } = browser;
+    state.browsers.set(sessionId, browser);
+    state.currentSession = sessionId;
+    state.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}\nSession ID: ${sessionId}\nCurrent page: "${title}" (${url})`,
+      }],
+    };
+  } catch (e) {
+    return {
+      content: [{ type: 'text', text: `Error attaching to browser: ${e}` }],
+    };
+  }
+};

src/tools/browser.tool.ts

@@ -196,8 +196,9 @@ export const closeSessionTool: ToolCallback = async (args: { detach?: boolean }
     const sessionId = state.currentSession;
     const metadata = state.sessionMetadata.get(sessionId);
 
-    // Only delete session if not detaching
-    if (!args.detach) {
+    // Skip deleteSession for attached sessions (not created by us) or when user explicitly detaches
+    const effectiveDetach = args.detach || !!metadata?.isAttached;
+    if (!effectiveDetach) {
       await browser.deleteSession();
     }
 
@@ -206,7 +207,7 @@ export const closeSessionTool: ToolCallback = async (args: { detach?: boolean }
     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.'
       : '';

src/tools/emulate-device.tool.ts

@@ -0,0 +1,111 @@
+import type { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types';
+import type { ToolDefinition } from '../types/tool';
+// DeviceName is not in webdriverio's public exports but is required to satisfy browser.emulate('device', ...) overloads.
+// This is a type-only import — it is stripped at build time by tsup and has no runtime impact.
+import type { DeviceName } from 'webdriverio/build/deviceDescriptorsSource.js';
+import { z } from 'zod';
+import { getBrowser } from './browser.tool';
+
+// Stores restore functions returned by browser.emulate(), keyed by sessionId
+const restoreFunctions = new Map<string, () => Promise<void>>();
+
+export const emulateDeviceToolDefinition: ToolDefinition = {
+  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()                    — list available device presets
+  emulate_device({ device: "iPhone 15" })  — activate emulation
+  emulate_device({ device: "reset" }) — restore desktop defaults`,
+  inputSchema: {
+    device: z.string().optional().describe(
+      'Device preset name (e.g. "iPhone 15", "Pixel 7"). Omit to list available presets. Pass "reset" to restore desktop defaults.'
+    ),
+  },
+};
+
+export const emulateDeviceTool: ToolCallback = async ({
+  device,
+}: {
+  device?: string;
+}): Promise<CallToolResult> => {
+  try {
+    const browser = getBrowser();
+    const state = (getBrowser as any).__state;
+    const sessionId = state.currentSession as string;
+    const metadata = state.sessionMetadata.get(sessionId);
+
+    // Guard: mobile sessions
+    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.' }],
+      };
+    }
+
+    // Guard: BiDi required
+    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 } })',
+        }],
+      };
+    }
+
+    // List presets by triggering a known-bad device name and parsing the error
+    if (!device) {
+      try {
+        await browser.emulate('device', '\u0000' as DeviceName);
+      } 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}):\n${names.join('\n')}` }],
+          };
+        }
+        return { content: [{ type: 'text', text: `Error listing devices: ${e}` }] };
+      }
+      return { content: [{ type: 'text', text: 'Could not retrieve device list.' }] };
+    }
+
+    // Reset
+    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.' }] };
+    }
+
+    // Emulate device
+    try {
+      const restoreFn = await browser.emulate('device', device as DeviceName);
+      restoreFunctions.set(sessionId, restoreFn as () => Promise<void>);
+      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}` }],
+    };
+  }
+};