@wdio/mcp 2.1.0 → 2.2.0

package/lib/server.js

@@ -7,10 +7,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/tools/browser.tool.ts
 import { remote } from "webdriverio";
 import { z } from "zod";
+var supportedBrowsers = ["chrome", "firefox", "edge", "safari"];
+var browserSchema = z.enum(supportedBrowsers).default("chrome");
 var startBrowserToolDefinition = {
   name: "start_browser",
-  description: "starts a browser session and sets it to the current state",
+  description: "starts a browser session (Chrome, Firefox, Edge, Safari) and sets it to the current state",
   inputSchema: {
+    browser: browserSchema.describe("Browser to launch: chrome, firefox, edge, safari (default: chrome)"),
     headless: z.boolean().optional(),
     windowWidth: z.number().min(400).max(3840).optional().default(1920),
     windowHeight: z.number().min(400).max(2160).optional().default(1080),
@@ -38,12 +41,22 @@ var getBrowser = () => {
 };
 getBrowser.__state = state;
 var startBrowserTool = async ({
+  browser = "chrome",
   headless = false,
   windowWidth = 1920,
   windowHeight = 1080,
   navigationUrl
 }) => {
-  const chromeArgs = [
+  const browserDisplayNames = {
+    chrome: "Chrome",
+    firefox: "Firefox",
+    edge: "Edge",
+    safari: "Safari"
+  };
+  const selectedBrowser = browser;
+  const headlessSupported = selectedBrowser !== "safari";
+  const effectiveHeadless = headless && headlessSupported;
+  const chromiumArgs = [
     `--window-size=${windowWidth},${windowHeight}`,
     "--no-sandbox",
     "--disable-search-engine-choice-screen",
@@ -54,37 +67,66 @@ var startBrowserTool = async ({
     "--disable-web-security",
     "--allow-running-insecure-content"
   ];
-  if (headless) {
-    chromeArgs.push("--headless=new");
-    chromeArgs.push("--disable-gpu");
-    chromeArgs.push("--disable-dev-shm-usage");
-  }
-  const browser = await remote({
-    capabilities: {
-      browserName: "chrome",
-      "goog:chromeOptions": {
-        args: chromeArgs
-      },
-      acceptInsecureCerts: true
-    }
+  if (effectiveHeadless) {
+    chromiumArgs.push("--headless=new");
+    chromiumArgs.push("--disable-gpu");
+    chromiumArgs.push("--disable-dev-shm-usage");
+  }
+  const firefoxArgs = [];
+  if (effectiveHeadless && selectedBrowser === "firefox") {
+    firefoxArgs.push("-headless");
+  }
+  const capabilities = {
+    acceptInsecureCerts: true
+  };
+  switch (selectedBrowser) {
+    case "chrome":
+      capabilities.browserName = "chrome";
+      capabilities["goog:chromeOptions"] = { args: chromiumArgs };
+      break;
+    case "edge":
+      capabilities.browserName = "msedge";
+      capabilities["ms:edgeOptions"] = { args: chromiumArgs };
+      break;
+    case "firefox":
+      capabilities.browserName = "firefox";
+      if (firefoxArgs.length > 0) {
+        capabilities["moz:firefoxOptions"] = { args: firefoxArgs };
+      }
+      break;
+    case "safari":
+      capabilities.browserName = "safari";
+      break;
+  }
+  const wdioBrowser = await remote({
+    capabilities
   });
-  const { sessionId } = browser;
-  state.browsers.set(sessionId, browser);
+  const { sessionId } = wdioBrowser;
+  state.browsers.set(sessionId, wdioBrowser);
   state.currentSession = sessionId;
   state.sessionMetadata.set(sessionId, {
     type: "browser",
-    capabilities: browser.capabilities,
+    capabilities: wdioBrowser.capabilities,
     isAttached: false
   });
+  let sizeNote = "";
+  try {
+    await wdioBrowser.setWindowSize(windowWidth, windowHeight);
+  } catch (e) {
+    sizeNote = `
+Note: Unable to set window size (${windowWidth}x${windowHeight}). ${e}`;
+  }
   if (navigationUrl) {
-    await browser.url(navigationUrl);
+    await wdioBrowser.url(navigationUrl);
   }
-  const modeText = headless ? "headless" : "headed";
+  const modeText = effectiveHeadless ? "headless" : "headed";
+  const browserText = browserDisplayNames[selectedBrowser];
   const urlText = navigationUrl ? ` and navigated to ${navigationUrl}` : "";
+  const headlessNote = headless && !headlessSupported ? "\nNote: Safari does not support headless mode. Started in headed mode." : "";
   return {
     content: [{
       type: "text",
-      text: `Browser started in ${modeText} mode with sessionId: ${sessionId} (${windowWidth}x${windowHeight})${urlText}`
+      text: `${browserText} browser started in ${modeText} mode with sessionId: ${sessionId} (${windowWidth}x${windowHeight})${urlText}${headlessNote}${sizeNote}`
     }]
   };
 };
@@ -592,95 +634,12 @@ var elementsScript = (elementType = "interactable") => (function() {
   }
   return getElements();
 })();
-var get_interactable_browser_elements_default = elementsScript;
-
-// src/locators/source-parsing.ts
-import { DOMParser } from "@xmldom/xmldom";
-function childNodesOf(node) {
-  const children = [];
-  if (node.childNodes) {
-    for (let i = 0; i < node.childNodes.length; i++) {
-      const child = node.childNodes.item(i);
-      if (child?.nodeType === 1) {
-        children.push(child);
-      }
-    }
-  }
-  return children;
-}
-function translateRecursively(domNode, parentPath = "", index = null) {
-  const attributes = {};
-  const element = domNode;
-  if (element.attributes) {
-    for (let attrIdx = 0; attrIdx < element.attributes.length; attrIdx++) {
-      const attr = element.attributes.item(attrIdx);
-      if (attr) {
-        attributes[attr.name] = attr.value.replace(/(\n)/gm, "\\n");
-      }
-    }
-  }
-  const path = index === null ? "" : `${parentPath ? parentPath + "." : ""}${index}`;
-  return {
-    children: childNodesOf(domNode).map(
-      (childNode, childIndex) => translateRecursively(childNode, path, childIndex)
-    ),
-    tagName: domNode.nodeName,
-    attributes,
-    path
-  };
-}
-function xmlToJSON(sourceXML) {
-  try {
-    const parser = new DOMParser();
-    const sourceDoc = parser.parseFromString(sourceXML, "text/xml");
-    const parseErrors = sourceDoc.getElementsByTagName("parsererror");
-    if (parseErrors.length > 0) {
-      console.error("[xmlToJSON] XML parsing error:", parseErrors[0].textContent);
-      return null;
-    }
-    const children = childNodesOf(sourceDoc);
-    const firstChild = children[0] || (sourceDoc.documentElement ? childNodesOf(sourceDoc.documentElement)[0] : null);
-    return firstChild ? translateRecursively(firstChild) : { children: [], tagName: "", attributes: {}, path: "" };
-  } catch (e) {
-    console.error("[xmlToJSON] Failed to parse XML:", e);
-    return null;
-  }
-}
-function parseAndroidBounds(bounds) {
-  const match = bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
-  if (!match) {
-    return { x: 0, y: 0, width: 0, height: 0 };
-  }
-  const x1 = parseInt(match[1], 10);
-  const y1 = parseInt(match[2], 10);
-  const x2 = parseInt(match[3], 10);
-  const y2 = parseInt(match[4], 10);
-  return {
-    x: x1,
-    y: y1,
-    width: x2 - x1,
-    height: y2 - y1
-  };
-}
-function parseIOSBounds(attributes) {
-  return {
-    x: parseInt(attributes.x || "0", 10),
-    y: parseInt(attributes.y || "0", 10),
-    width: parseInt(attributes.width || "0", 10),
-    height: parseInt(attributes.height || "0", 10)
-  };
-}
-function countAttributeOccurrences(sourceXML, attribute, value) {
-  const escapedValue = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const pattern = new RegExp(`${attribute}=["']${escapedValue}["']`, "g");
-  const matches = sourceXML.match(pattern);
-  return matches ? matches.length : 0;
-}
-function isAttributeUnique(sourceXML, attribute, value) {
-  return countAttributeOccurrences(sourceXML, attribute, value) === 1;
+async function getBrowserInteractableElements(browser, options = {}) {
+  const { elementType = "interactable" } = options;
+  return browser.execute(elementsScript, elementType);
 }
 
-// src/locators/element-filter.ts
+// src/locators/constants.ts
 var ANDROID_INTERACTABLE_TAGS = [
   // Input elements
   "android.widget.EditText",
@@ -715,43 +674,6 @@ var ANDROID_INTERACTABLE_TAGS = [
   // List/grid items
   "android.widget.AdapterView"
 ];
-var IOS_INTERACTABLE_TAGS = [
-  // Input elements
-  "XCUIElementTypeTextField",
-  "XCUIElementTypeSecureTextField",
-  "XCUIElementTypeTextView",
-  "XCUIElementTypeSearchField",
-  // Button-like elements
-  "XCUIElementTypeButton",
-  "XCUIElementTypeLink",
-  // Text elements (often tappable)
-  "XCUIElementTypeStaticText",
-  // Image elements
-  "XCUIElementTypeImage",
-  "XCUIElementTypeIcon",
-  // Selection elements
-  "XCUIElementTypeSwitch",
-  "XCUIElementTypeSlider",
-  "XCUIElementTypeStepper",
-  "XCUIElementTypeSegmentedControl",
-  "XCUIElementTypePicker",
-  "XCUIElementTypePickerWheel",
-  "XCUIElementTypeDatePicker",
-  "XCUIElementTypePageIndicator",
-  // Table/list items
-  "XCUIElementTypeCell",
-  "XCUIElementTypeMenuItem",
-  "XCUIElementTypeMenuBarItem",
-  // Toggle elements
-  "XCUIElementTypeCheckBox",
-  "XCUIElementTypeRadioButton",
-  "XCUIElementTypeToggle",
-  // Other interactive
-  "XCUIElementTypeKey",
-  "XCUIElementTypeKeyboard",
-  "XCUIElementTypeAlert",
-  "XCUIElementTypeSheet"
-];
 var ANDROID_LAYOUT_CONTAINERS = [
   // Core ViewGroup classes
   "android.view.ViewGroup",
@@ -790,6 +712,43 @@ var ANDROID_LAYOUT_CONTAINERS = [
   "com.android.internal.policy.DecorView",
   "android.widget.DecorView"
 ];
+var IOS_INTERACTABLE_TAGS = [
+  // Input elements
+  "XCUIElementTypeTextField",
+  "XCUIElementTypeSecureTextField",
+  "XCUIElementTypeTextView",
+  "XCUIElementTypeSearchField",
+  // Button-like elements
+  "XCUIElementTypeButton",
+  "XCUIElementTypeLink",
+  // Text elements (often tappable)
+  "XCUIElementTypeStaticText",
+  // Image elements
+  "XCUIElementTypeImage",
+  "XCUIElementTypeIcon",
+  // Selection elements
+  "XCUIElementTypeSwitch",
+  "XCUIElementTypeSlider",
+  "XCUIElementTypeStepper",
+  "XCUIElementTypeSegmentedControl",
+  "XCUIElementTypePicker",
+  "XCUIElementTypePickerWheel",
+  "XCUIElementTypeDatePicker",
+  "XCUIElementTypePageIndicator",
+  // Table/list items
+  "XCUIElementTypeCell",
+  "XCUIElementTypeMenuItem",
+  "XCUIElementTypeMenuBarItem",
+  // Toggle elements
+  "XCUIElementTypeCheckBox",
+  "XCUIElementTypeRadioButton",
+  "XCUIElementTypeToggle",
+  // Other interactive
+  "XCUIElementTypeKey",
+  "XCUIElementTypeKeyboard",
+  "XCUIElementTypeAlert",
+  "XCUIElementTypeSheet"
+];
 var IOS_LAYOUT_CONTAINERS = [
   // Generic containers
   "XCUIElementTypeOther",
@@ -822,6 +781,188 @@ var IOS_LAYOUT_CONTAINERS = [
   // Application root
   "XCUIElementTypeApplication"
 ];
+
+// src/locators/xml-parsing.ts
+import { DOMParser } from "@xmldom/xmldom";
+import xpath from "xpath";
+function childNodesOf(node) {
+  const children = [];
+  if (node.childNodes) {
+    for (let i = 0; i < node.childNodes.length; i++) {
+      const child = node.childNodes.item(i);
+      if (child?.nodeType === 1) {
+        children.push(child);
+      }
+    }
+  }
+  return children;
+}
+function translateRecursively(domNode, parentPath = "", index = null) {
+  const attributes = {};
+  const element = domNode;
+  if (element.attributes) {
+    for (let attrIdx = 0; attrIdx < element.attributes.length; attrIdx++) {
+      const attr = element.attributes.item(attrIdx);
+      if (attr) {
+        attributes[attr.name] = attr.value.replace(/(\n)/gm, "\\n");
+      }
+    }
+  }
+  const path = index === null ? "" : `${parentPath ? parentPath + "." : ""}${index}`;
+  return {
+    children: childNodesOf(domNode).map(
+      (childNode, childIndex) => translateRecursively(childNode, path, childIndex)
+    ),
+    tagName: domNode.nodeName,
+    attributes,
+    path
+  };
+}
+function isSameElement(node1, node2) {
+  if (node1.nodeType !== 1 || node2.nodeType !== 1) return false;
+  const el1 = node1;
+  const el2 = node2;
+  if (el1.nodeName !== el2.nodeName) return false;
+  const bounds1 = el1.getAttribute("bounds");
+  const bounds2 = el2.getAttribute("bounds");
+  if (bounds1 && bounds2) {
+    return bounds1 === bounds2;
+  }
+  const x1 = el1.getAttribute("x");
+  const y1 = el1.getAttribute("y");
+  const x2 = el2.getAttribute("x");
+  const y2 = el2.getAttribute("y");
+  if (x1 && y1 && x2 && y2) {
+    return x1 === x2 && y1 === y2 && el1.getAttribute("width") === el2.getAttribute("width") && el1.getAttribute("height") === el2.getAttribute("height");
+  }
+  return false;
+}
+function xmlToJSON(sourceXML) {
+  try {
+    const parser = new DOMParser();
+    const sourceDoc = parser.parseFromString(sourceXML, "text/xml");
+    const parseErrors = sourceDoc.getElementsByTagName("parsererror");
+    if (parseErrors.length > 0) {
+      console.error("[xmlToJSON] XML parsing error:", parseErrors[0].textContent);
+      return null;
+    }
+    const children = childNodesOf(sourceDoc);
+    const firstChild = children[0] || (sourceDoc.documentElement ? childNodesOf(sourceDoc.documentElement)[0] : null);
+    return firstChild ? translateRecursively(firstChild) : { children: [], tagName: "", attributes: {}, path: "" };
+  } catch (e) {
+    console.error("[xmlToJSON] Failed to parse XML:", e);
+    return null;
+  }
+}
+function xmlToDOM(sourceXML) {
+  try {
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(sourceXML, "text/xml");
+    const parseErrors = doc.getElementsByTagName("parsererror");
+    if (parseErrors.length > 0) {
+      console.error("[xmlToDOM] XML parsing error:", parseErrors[0].textContent);
+      return null;
+    }
+    return doc;
+  } catch (e) {
+    console.error("[xmlToDOM] Failed to parse XML:", e);
+    return null;
+  }
+}
+function evaluateXPath(doc, xpathExpr) {
+  try {
+    const nodes = xpath.select(xpathExpr, doc);
+    if (Array.isArray(nodes)) {
+      return nodes;
+    }
+    return [];
+  } catch (e) {
+    console.error(`[evaluateXPath] Failed to evaluate "${xpathExpr}":`, e);
+    return [];
+  }
+}
+function checkXPathUniqueness(doc, xpathExpr, targetNode) {
+  try {
+    const nodes = evaluateXPath(doc, xpathExpr);
+    const totalMatches = nodes.length;
+    if (totalMatches === 0) {
+      return { isUnique: false };
+    }
+    if (totalMatches === 1) {
+      return { isUnique: true };
+    }
+    if (targetNode) {
+      for (let i = 0; i < nodes.length; i++) {
+        if (nodes[i].isSameNode(targetNode) || isSameElement(nodes[i], targetNode)) {
+          return {
+            isUnique: false,
+            index: i + 1,
+            // 1-based index for XPath
+            totalMatches
+          };
+        }
+      }
+    }
+    return { isUnique: false, totalMatches };
+  } catch (e) {
+    console.error(`[checkXPathUniqueness] Error checking "${xpathExpr}":`, e);
+    return { isUnique: false };
+  }
+}
+function findDOMNodeByPath(doc, path) {
+  if (!path) return doc.documentElement;
+  const indices = path.split(".").map(Number);
+  let current = doc.documentElement;
+  for (const index of indices) {
+    if (!current) return null;
+    const children = [];
+    if (current.childNodes) {
+      for (let i = 0; i < current.childNodes.length; i++) {
+        const child = current.childNodes.item(i);
+        if (child?.nodeType === 1) {
+          children.push(child);
+        }
+      }
+    }
+    current = children[index] || null;
+  }
+  return current;
+}
+function parseAndroidBounds(bounds) {
+  const match = bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+  if (!match) {
+    return { x: 0, y: 0, width: 0, height: 0 };
+  }
+  const x1 = parseInt(match[1], 10);
+  const y1 = parseInt(match[2], 10);
+  const x2 = parseInt(match[3], 10);
+  const y2 = parseInt(match[4], 10);
+  return {
+    x: x1,
+    y: y1,
+    width: x2 - x1,
+    height: y2 - y1
+  };
+}
+function parseIOSBounds(attributes) {
+  return {
+    x: parseInt(attributes.x || "0", 10),
+    y: parseInt(attributes.y || "0", 10),
+    width: parseInt(attributes.width || "0", 10),
+    height: parseInt(attributes.height || "0", 10)
+  };
+}
+function countAttributeOccurrences(sourceXML, attribute, value) {
+  const escapedValue = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`${attribute}=["']${escapedValue}["']`, "g");
+  const matches = sourceXML.match(pattern);
+  return matches ? matches.length : 0;
+}
+function isAttributeUnique(sourceXML, attribute, value) {
+  return countAttributeOccurrences(sourceXML, attribute, value) === 1;
+}
+
+// src/locators/element-filter.ts
 function matchesTagList(tagName, tagList) {
   if (tagList.includes(tagName)) {
     return true;
@@ -902,7 +1043,6 @@ function shouldIncludeElement(element, filters, isNative, automationName) {
   const {
     includeTagNames = [],
     excludeTagNames = ["hierarchy"],
-    // Always exclude root hierarchy node
     requireAttributes = [],
     minAttributeCount = 0,
     fetchableOnly = false,
@@ -949,38 +1089,144 @@ function isValidValue(value) {
 function escapeText(text) {
   return text.replace(/"/g, '\\"').replace(/\n/g, "\\n");
 }
-function getSimpleSuggestedLocators(element, sourceXML, isNative, automationName) {
-  const results = [];
-  const isAndroid = automationName.toLowerCase().includes("uiautomator");
-  const attrs = element.attributes;
-  if (isAndroid) {
-    const resourceId = attrs["resource-id"];
-    if (isValidValue(resourceId) && isAttributeUnique(sourceXML, "resource-id", resourceId)) {
-      results.push(["id", `android=new UiSelector().resourceId("${resourceId}")`]);
+function escapeXPathValue(value) {
+  if (!value.includes("'")) {
+    return `'${value}'`;
+  }
+  if (!value.includes('"')) {
+    return `"${value}"`;
+  }
+  const parts = [];
+  let current = "";
+  for (const char of value) {
+    if (char === "'") {
+      if (current) parts.push(`'${current}'`);
+      parts.push(`"'"`);
+      current = "";
+    } else {
+      current += char;
     }
-    const contentDesc = attrs["content-desc"];
-    if (isValidValue(contentDesc) && isAttributeUnique(sourceXML, "content-desc", contentDesc)) {
-      results.push(["accessibility-id", `~${contentDesc}`]);
+  }
+  if (current) parts.push(`'${current}'`);
+  return `concat(${parts.join(",")})`;
+}
+function generateIndexedXPath(baseXPath, index) {
+  return `(${baseXPath})[${index}]`;
+}
+function generateIndexedUiAutomator(baseSelector, index) {
+  return `${baseSelector}.instance(${index - 1})`;
+}
+function checkUniqueness(ctx, xpath2, targetNode) {
+  if (ctx.parsedDOM) {
+    return checkXPathUniqueness(ctx.parsedDOM, xpath2, targetNode);
+  }
+  const match = xpath2.match(/\/\/\*\[@([^=]+)="([^"]+)"\]/);
+  if (match) {
+    const [, attr, value] = match;
+    return { isUnique: isAttributeUnique(ctx.sourceXML, attr, value) };
+  }
+  return { isUnique: false };
+}
+function getSiblingIndex(element) {
+  const parent = element.parentNode;
+  if (!parent) return 1;
+  const tagName = element.nodeName;
+  let index = 0;
+  for (let i = 0; i < parent.childNodes.length; i++) {
+    const child = parent.childNodes.item(i);
+    if (child?.nodeType === 1 && child.nodeName === tagName) {
+      index++;
+      if (child === element) return index;
+    }
+  }
+  return 1;
+}
+function countSiblings(element) {
+  const parent = element.parentNode;
+  if (!parent) return 1;
+  const tagName = element.nodeName;
+  let count = 0;
+  for (let i = 0; i < parent.childNodes.length; i++) {
+    const child = parent.childNodes.item(i);
+    if (child?.nodeType === 1 && child.nodeName === tagName) {
+      count++;
+    }
+  }
+  return count;
+}
+function findUniqueAttribute(element, ctx) {
+  const attrs = ctx.isAndroid ? ["resource-id", "content-desc", "text"] : ["name", "label", "value"];
+  for (const attr of attrs) {
+    const value = element.getAttribute(attr);
+    if (value && value.trim()) {
+      const xpath2 = `//*[@${attr}=${escapeXPathValue(value)}]`;
+      const result = ctx.parsedDOM ? checkXPathUniqueness(ctx.parsedDOM, xpath2) : { isUnique: isAttributeUnique(ctx.sourceXML, attr, value) };
+      if (result.isUnique) {
+        return `@${attr}=${escapeXPathValue(value)}`;
+      }
     }
-    const text = attrs.text;
-    if (isValidValue(text) && text.length < 100 && isAttributeUnique(sourceXML, "text", text)) {
-      results.push(["text", `android=new UiSelector().text("${escapeText(text)}")`]);
+  }
+  return null;
+}
+function buildHierarchicalXPath(ctx, element, maxDepth = 3) {
+  if (!ctx.parsedDOM) return null;
+  const pathParts = [];
+  let current = element;
+  let depth = 0;
+  while (current && depth < maxDepth) {
+    const tagName = current.nodeName;
+    const uniqueAttr = findUniqueAttribute(current, ctx);
+    if (uniqueAttr) {
+      pathParts.unshift(`//${tagName}[${uniqueAttr}]`);
+      break;
+    } else {
+      const siblingIndex = getSiblingIndex(current);
+      const siblingCount = countSiblings(current);
+      if (siblingCount > 1) {
+        pathParts.unshift(`${tagName}[${siblingIndex}]`);
+      } else {
+        pathParts.unshift(tagName);
+      }
     }
+    const parent = current.parentNode;
+    current = parent && parent.nodeType === 1 ? parent : null;
+    depth++;
+  }
+  if (pathParts.length === 0) return null;
+  let result = pathParts[0];
+  for (let i = 1; i < pathParts.length; i++) {
+    result += "/" + pathParts[i];
+  }
+  if (!result.startsWith("//")) {
+    result = "//" + result;
+  }
+  return result;
+}
+function addXPathLocator(results, xpath2, ctx, targetNode) {
+  const uniqueness = checkUniqueness(ctx, xpath2, targetNode);
+  if (uniqueness.isUnique) {
+    results.push(["xpath", xpath2]);
+  } else if (uniqueness.index) {
+    results.push(["xpath", generateIndexedXPath(xpath2, uniqueness.index)]);
   } else {
-    const name = attrs.name;
-    if (isValidValue(name) && isAttributeUnique(sourceXML, "name", name)) {
-      results.push(["accessibility-id", `~${name}`]);
-    }
-    const label = attrs.label;
-    if (isValidValue(label) && label !== name && isAttributeUnique(sourceXML, "label", label)) {
-      results.push(["predicate-string", `-ios predicate string:label == "${escapeText(label)}"`]);
-    }
-    const value = attrs.value;
-    if (isValidValue(value) && isAttributeUnique(sourceXML, "value", value)) {
-      results.push(["predicate-string", `-ios predicate string:value == "${escapeText(value)}"`]);
+    if (targetNode && ctx.parsedDOM) {
+      const hierarchical = buildHierarchicalXPath(ctx, targetNode);
+      if (hierarchical) {
+        results.push(["xpath", hierarchical]);
+      }
     }
+    results.push(["xpath", xpath2]);
   }
-  return results;
+}
+function isInUiAutomatorScope(element, doc) {
+  if (!doc) return true;
+  const hierarchyNodes = evaluateXPath(doc, "/hierarchy/*");
+  if (hierarchyNodes.length === 0) return true;
+  const lastIndex = hierarchyNodes.length;
+  const pathParts = element.path.split(".");
+  if (pathParts.length === 0 || pathParts[0] === "") return true;
+  const firstIndex = parseInt(pathParts[0], 10);
+  return firstIndex === lastIndex - 1;
 }
 function buildUiAutomatorSelector(element) {
   const attrs = element.attributes;
@@ -1063,19 +1309,86 @@ function buildXPath(element, sourceXML, isAndroid) {
   }
   return `//${tagName}[${conditions.join(" and ")}]`;
 }
-function getComplexSuggestedLocators(element, sourceXML, isNative, automationName) {
+function getSimpleSuggestedLocators(element, ctx, automationName, targetNode) {
+  const results = [];
+  const isAndroid = automationName.toLowerCase().includes("uiautomator");
+  const attrs = element.attributes;
+  const inUiAutomatorScope = isAndroid ? isInUiAutomatorScope(element, ctx.parsedDOM) : true;
+  if (isAndroid) {
+    const resourceId = attrs["resource-id"];
+    if (isValidValue(resourceId)) {
+      const xpath2 = `//*[@resource-id="${resourceId}"]`;
+      const uniqueness = checkUniqueness(ctx, xpath2, targetNode);
+      if (uniqueness.isUnique && inUiAutomatorScope) {
+        results.push(["id", `android=new UiSelector().resourceId("${resourceId}")`]);
+      } else if (uniqueness.index && inUiAutomatorScope) {
+        const base = `android=new UiSelector().resourceId("${resourceId}")`;
+        results.push(["id", generateIndexedUiAutomator(base, uniqueness.index)]);
+      }
+    }
+    const contentDesc = attrs["content-desc"];
+    if (isValidValue(contentDesc)) {
+      const xpath2 = `//*[@content-desc="${contentDesc}"]`;
+      const uniqueness = checkUniqueness(ctx, xpath2, targetNode);
+      if (uniqueness.isUnique) {
+        results.push(["accessibility-id", `~${contentDesc}`]);
+      }
+    }
+    const text = attrs.text;
+    if (isValidValue(text) && text.length < 100) {
+      const xpath2 = `//*[@text="${escapeText(text)}"]`;
+      const uniqueness = checkUniqueness(ctx, xpath2, targetNode);
+      if (uniqueness.isUnique && inUiAutomatorScope) {
+        results.push(["text", `android=new UiSelector().text("${escapeText(text)}")`]);
+      } else if (uniqueness.index && inUiAutomatorScope) {
+        const base = `android=new UiSelector().text("${escapeText(text)}")`;
+        results.push(["text", generateIndexedUiAutomator(base, uniqueness.index)]);
+      }
+    }
+  } else {
+    const name = attrs.name;
+    if (isValidValue(name)) {
+      const xpath2 = `//*[@name="${name}"]`;
+      const uniqueness = checkUniqueness(ctx, xpath2, targetNode);
+      if (uniqueness.isUnique) {
+        results.push(["accessibility-id", `~${name}`]);
+      }
+    }
+    const label = attrs.label;
+    if (isValidValue(label) && label !== attrs.name) {
+      const xpath2 = `//*[@label="${escapeText(label)}"]`;
+      const uniqueness = checkUniqueness(ctx, xpath2, targetNode);
+      if (uniqueness.isUnique) {
+        results.push(["predicate-string", `-ios predicate string:label == "${escapeText(label)}"`]);
+      }
+    }
+    const value = attrs.value;
+    if (isValidValue(value)) {
+      const xpath2 = `//*[@value="${escapeText(value)}"]`;
+      const uniqueness = checkUniqueness(ctx, xpath2, targetNode);
+      if (uniqueness.isUnique) {
+        results.push(["predicate-string", `-ios predicate string:value == "${escapeText(value)}"`]);
+      }
+    }
+  }
+  return results;
+}
+function getComplexSuggestedLocators(element, ctx, automationName, targetNode) {
   const results = [];
   const isAndroid = automationName.toLowerCase().includes("uiautomator");
+  const inUiAutomatorScope = isAndroid ? isInUiAutomatorScope(element, ctx.parsedDOM) : true;
   if (isAndroid) {
-    const uiAutomator = buildUiAutomatorSelector(element);
-    if (uiAutomator) {
-      results.push(["uiautomator", uiAutomator]);
+    if (inUiAutomatorScope) {
+      const uiAutomator = buildUiAutomatorSelector(element);
+      if (uiAutomator) {
+        results.push(["uiautomator", uiAutomator]);
+      }
     }
-    const xpath = buildXPath(element, sourceXML, true);
-    if (xpath) {
-      results.push(["xpath", xpath]);
+    const xpath2 = buildXPath(element, ctx.sourceXML, true);
+    if (xpath2) {
+      addXPathLocator(results, xpath2, ctx, targetNode);
     }
-    if (isValidValue(element.attributes.class)) {
+    if (inUiAutomatorScope && isValidValue(element.attributes.class)) {
       results.push([
         "class-name",
         `android=new UiSelector().className("${element.attributes.class}")`
@@ -1090,9 +1403,9 @@ function getComplexSuggestedLocators(element, sourceXML, isNative, automationNam
     if (classChain) {
       results.push(["class-chain", classChain]);
     }
-    const xpath = buildXPath(element, sourceXML, false);
-    if (xpath) {
-      results.push(["xpath", xpath]);
+    const xpath2 = buildXPath(element, ctx.sourceXML, false);
+    if (xpath2) {
+      addXPathLocator(results, xpath2, ctx, targetNode);
     }
     const type = element.tagName;
     if (type.startsWith("XCUIElementType")) {
@@ -1101,9 +1414,14 @@ function getComplexSuggestedLocators(element, sourceXML, isNative, automationNam
   }
   return results;
 }
-function getSuggestedLocators(element, sourceXML, isNative, automationName) {
-  const simpleLocators = getSimpleSuggestedLocators(element, sourceXML, isNative, automationName);
-  const complexLocators = getComplexSuggestedLocators(element, sourceXML, isNative, automationName);
+function getSuggestedLocators(element, sourceXML, automationName, ctx, targetNode) {
+  const locatorCtx = ctx ?? {
+    sourceXML,
+    parsedDOM: null,
+    isAndroid: automationName.toLowerCase().includes("uiautomator")
+  };
+  const simpleLocators = getSimpleSuggestedLocators(element, locatorCtx, automationName, targetNode);
+  const complexLocators = getComplexSuggestedLocators(element, locatorCtx, automationName, targetNode);
   const seen = /* @__PURE__ */ new Set();
   const results = [];
   for (const locator of [...simpleLocators, ...complexLocators]) {
@@ -1124,7 +1442,7 @@ function locatorsToObject(locators) {
   return result;
 }
 
-// src/locators/generate-all-locators.ts
+// src/locators/index.ts
 function parseBounds(element, platform) {
   return platform === "android" ? parseAndroidBounds(element.attributes.bounds || "") : parseIOSBounds(element.attributes);
 }
@@ -1160,7 +1478,14 @@ function shouldProcess(element, ctx) {
 function processElement(element, ctx) {
   if (!shouldProcess(element, ctx)) return;
   try {
-    const locators = getSuggestedLocators(element, ctx.sourceXML, ctx.isNative, ctx.automationName);
+    const targetNode = ctx.parsedDOM ? findDOMNodeByPath(ctx.parsedDOM, element.path) : void 0;
+    const locators = getSuggestedLocators(
+      element,
+      ctx.sourceXML,
+      ctx.automationName,
+      { sourceXML: ctx.sourceXML, parsedDOM: ctx.parsedDOM, isAndroid: ctx.platform === "android" },
+      targetNode || void 0
+    );
     if (locators.length === 0) return;
     const transformed = transformElement(element, locators, ctx);
     if (Object.keys(transformed.locators).length === 0) return;
@@ -1182,6 +1507,7 @@ function generateAllElementLocators(sourceXML, options) {
     console.error("[generateAllElementLocators] Failed to parse page source XML");
     return [];
   }
+  const parsedDOM = xmlToDOM(sourceXML);
   const ctx = {
     sourceXML,
     platform: options.platform,
@@ -1189,7 +1515,8 @@ function generateAllElementLocators(sourceXML, options) {
     isNative: options.isNative ?? true,
     viewportSize: options.viewportSize ?? { width: 9999, height: 9999 },
     filters: options.filters ?? {},
-    results: []
+    results: [],
+    parsedDOM
   };
   traverseTree(sourceJSON, ctx);
   return ctx.results;
@@ -1240,7 +1567,8 @@ function toMobileElementInfo(element, includeBounds) {
     resourceId: element.resourceId || "",
     accessibilityId: accessId || "",
     isEnabled: element.enabled !== false,
-    alternativeSelectors: selectedLocators.length > 1 ? selectedLocators.slice(1) : []
+    altSelector: selectedLocators[1] || ""
+    // Single alternative (flattened for tabular)
   };
   if (includeBounds) {
     info.bounds = element.bounds;
@@ -1310,7 +1638,7 @@ var getVisibleElementsTool = async (args) => {
       const platform = browser.isAndroid ? "android" : "ios";
       elements = await getMobileVisibleElements(browser, platform, { includeContainers, includeBounds });
     } else {
-      elements = await browser.execute(get_interactable_browser_elements_default, elementType);
+      elements = await getBrowserInteractableElements(browser, { elementType });
     }
     if (inViewportOnly) {
       elements = elements.filter((el) => el.isInViewport !== false);
@@ -1501,29 +1829,15 @@ var deleteCookiesTool = async ({ name }) => {
   }
 };
 
-// src/tools/get-accessibility-tree.tool.ts
-import { encode as encode2 } from "@toon-format/toon";
-import { z as z10 } from "zod";
-var getAccessibilityToolDefinition = {
-  name: "get_accessibility",
-  description: "gets accessibility tree snapshot with semantic information about page elements (roles, names, states). Browser-only - use when get_visible_elements does not return expected elements.",
-  inputSchema: {
-    limit: z10.number().optional().describe("Maximum number of nodes to return. Default: 100. Use 0 for unlimited."),
-    offset: z10.number().optional().describe("Number of nodes to skip (for pagination). Default: 0."),
-    roles: z10.array(z10.string()).optional().describe('Filter to specific roles (e.g., ["button", "link", "textbox"]). Default: all roles.'),
-    namedOnly: z10.boolean().optional().describe("Only return nodes with a name/label. Default: true. Filters out anonymous containers.")
-  }
-};
+// src/scripts/get-browser-accessibility-tree.ts
 function flattenAccessibilityTree(node, result = []) {
   if (!node) return result;
   if (node.role !== "WebArea" || node.name) {
     const entry = {
-      // Primary identifiers (most useful)
       role: node.role || "",
       name: node.name || "",
       value: node.value ?? "",
       description: node.description || "",
-      // Boolean states (empty string = not applicable/false)
       disabled: node.disabled ? "true" : "",
       focused: node.focused ? "true" : "",
       selected: node.selected ? "true" : "",
@@ -1532,7 +1846,6 @@ function flattenAccessibilityTree(node, result = []) {
       pressed: node.pressed === true ? "true" : node.pressed === false ? "false" : node.pressed === "mixed" ? "mixed" : "",
       readonly: node.readonly ? "true" : "",
       required: node.required ? "true" : "",
-      // Less common properties
       level: node.level ?? "",
       valuemin: node.valuemin ?? "",
       valuemax: node.valuemax ?? "",
@@ -1556,6 +1869,35 @@ function flattenAccessibilityTree(node, result = []) {
   }
   return result;
 }
+async function getBrowserAccessibilityTree(browser) {
+  const puppeteer = await browser.getPuppeteer();
+  const pages = await puppeteer.pages();
+  if (pages.length === 0) {
+    return [];
+  }
+  const page = pages[0];
+  const snapshot = await page.accessibility.snapshot({
+    interestingOnly: true
+  });
+  if (!snapshot) {
+    return [];
+  }
+  return flattenAccessibilityTree(snapshot);
+}
+
+// src/tools/get-accessibility-tree.tool.ts
+import { encode as encode2 } from "@toon-format/toon";
+import { z as z10 } from "zod";
+var getAccessibilityToolDefinition = {
+  name: "get_accessibility",
+  description: "gets accessibility tree snapshot with semantic information about page elements (roles, names, states). Browser-only - use when get_visible_elements does not return expected elements.",
+  inputSchema: {
+    limit: z10.number().optional().describe("Maximum number of nodes to return. Default: 100. Use 0 for unlimited."),
+    offset: z10.number().optional().describe("Number of nodes to skip (for pagination). Default: 0."),
+    roles: z10.array(z10.string()).optional().describe('Filter to specific roles (e.g., ["button", "link", "textbox"]). Default: all roles.'),
+    namedOnly: z10.boolean().optional().describe("Only return nodes with a name/label. Default: true. Filters out anonymous containers.")
+  }
+};
 var getAccessibilityTreeTool = async (args) => {
   try {
     const browser = getBrowser();
@@ -1568,24 +1910,12 @@ var getAccessibilityTreeTool = async (args) => {
       };
     }
     const { limit = 100, offset = 0, roles, namedOnly = true } = args || {};
-    const puppeteer = await browser.getPuppeteer();
-    const pages = await puppeteer.pages();
-    if (pages.length === 0) {
-      return {
-        content: [{ type: "text", text: "No active pages found" }]
-      };
-    }
-    const page = pages[0];
-    const snapshot = await page.accessibility.snapshot({
-      interestingOnly: true
-      // Filter to only interesting/semantic nodes
-    });
-    if (!snapshot) {
+    let nodes = await getBrowserAccessibilityTree(browser);
+    if (nodes.length === 0) {
       return {
         content: [{ type: "text", text: "No accessibility tree available" }]
       };
     }
-    let nodes = flattenAccessibilityTree(snapshot);
     if (namedOnly) {
       nodes = nodes.filter((n) => n.name && n.name.trim() !== "");
     }
@@ -2017,11 +2347,21 @@ var package_default = {
     type: "git",
     url: "git://github.com/webdriverio/mcp.git"
   },
-  version: "2.0.0",
+  version: "2.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",
   types: "./lib/server.d.ts",
+  exports: {
+    ".": {
+      import: "./lib/server.js",
+      types: "./lib/server.d.ts"
+    },
+    "./snapshot": {
+      import: "./lib/snapshot.js",
+      types: "./lib/snapshot.d.ts"
+    }
+  },
   bin: {
     "wdio-mcp": "lib/server.js"
   },
@@ -2045,6 +2385,7 @@ var package_default = {
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "1.25",
+    xpath: "^0.0.34",
     "@toon-format/toon": "^2.1.0",
     "@wdio/protocols": "^9.16.2",
     "@xmldom/xmldom": "^0.8.11",
@@ -2082,7 +2423,7 @@ var server = new McpServer({
   description: package_default.description,
   websiteUrl: "https://github.com/webdriverio/mcp"
 }, {
-  instructions: "MCP server for browser and mobile app automation using WebDriverIO. Supports Chrome browser control (headed/headless) and iOS/Android native app testing via Appium.",
+  instructions: "MCP server for browser and mobile app automation using WebDriverIO. Supports Chrome, Firefox, Edge, and Safari browser control plus iOS/Android native app testing via Appium.",
   capabilities: {
     tools: {}
   }