@hypothesi/tauri-mcp-server 0.8.2 → 0.8.3

package/dist/driver/scripts/dom-snapshot.js

@@ -18,12 +18,13 @@
  *
  * @param {Object} params
  * @param {string} params.type - Snapshot type ('accessibility' or 'structure')
- * @param {string|null} params.selector - Optional CSS selector to scope snapshot
+ * @param {string|null} params.selector - Optional selector to scope snapshot (CSS, XPath, text, or ref ID)
+ * @param {string} params.strategy - Selector strategy: 'css', 'xpath', or 'text'
  */
 (function(params) {
    'use strict';
 
-   const { type, selector } = params;
+   const { type, selector, strategy } = params;
 
    // ARIA states to include in snapshot (used by accessibility type)
    const ARIA_STATES = [
@@ -445,18 +446,17 @@
 
       if (selector) {
          try {
-            document.querySelector(selector);
+            var structureElements = window.__MCP__.resolveAll(selector, strategy);
          } catch (e) {
-            return 'Error: Invalid CSS selector "' + selector + '": ' + e.message;
+            return 'Error: Invalid selector "' + selector + '" (strategy: ' + strategy + '): ' + e.message;
          }
 
-         var structureElements = document.querySelectorAll(selector);
          if (structureElements.length === 0) {
-            return 'Error: No elements found matching selector "' + selector + '"';
+            return 'Error: No elements found matching selector "' + selector + '" (strategy: ' + strategy + ')';
          }
 
-         structureRoots = Array.from(structureElements);
-         structureScopeInfo = '# Scoped to: ' + selector + '\n';
+         structureRoots = structureElements;
+         structureScopeInfo = '# Scoped to: ' + selector + (strategy !== 'css' ? ' (strategy: ' + strategy + ')' : '') + '\n';
          if (structureRoots.length > 1) structureScopeInfo += '# ' + structureRoots.length + ' elements matched\n';
       } else {
          structureRoots = [document.body];
@@ -498,18 +498,17 @@
 
    if (selector) {
       try {
-         document.querySelector(selector);
+         var elements = window.__MCP__.resolveAll(selector, strategy);
       } catch (e) {
-         return 'Error: Invalid CSS selector "' + selector + '": ' + e.message;
+         return 'Error: Invalid selector "' + selector + '" (strategy: ' + strategy + '): ' + e.message;
       }
 
-      var elements = document.querySelectorAll(selector);
       if (elements.length === 0) {
-         return 'Error: No elements found matching selector "' + selector + '"';
+         return 'Error: No elements found matching selector "' + selector + '" (strategy: ' + strategy + ')';
       }
 
-      roots = Array.from(elements);
-      scopeInfo = '# Scoped to: ' + selector + '\n';
+      roots = elements;
+      scopeInfo = '# Scoped to: ' + selector + (strategy !== 'css' ? ' (strategy: ' + strategy + ')' : '') + '\n';
       if (roots.length > 1) scopeInfo += '# ' + roots.length + ' elements matched\n';
    } else {
       roots = [document.body];

package/dist/driver/scripts/find-element.js

@@ -7,36 +7,8 @@
  */
 (function(params) {
    const { selector, strategy } = params;
-   let element;
 
-   // Check if it's a ref ID first (works with any strategy)
-   if (/^\[?(?:ref=)?(e\d+)\]?$/.test(selector)) {
-      element = window.__MCP__.resolveRef(selector);
-   } else if (strategy === 'text') {
-      // Find element containing text
-      const xpath = "//*[contains(text(), '" + selector + "')]";
-      const result = document.evaluate(
-         xpath,
-         document,
-         null,
-         XPathResult.FIRST_ORDERED_NODE_TYPE,
-         null
-      );
-      element = result.singleNodeValue;
-   } else if (strategy === 'xpath') {
-      // XPath selector
-      const result = document.evaluate(
-         selector,
-         document,
-         null,
-         XPathResult.FIRST_ORDERED_NODE_TYPE,
-         null
-      );
-      element = result.singleNodeValue;
-   } else {
-      // CSS selector (default)
-      element = window.__MCP__.resolveRef(selector);
-   }
+   var element = window.__MCP__.resolveRef(selector, strategy);
 
    if (element) {
       const outerHTML = element.outerHTML;
@@ -44,7 +16,10 @@
       const truncated = outerHTML.length > 5000
          ? outerHTML.substring(0, 5000) + '...'
          : outerHTML;
-      return 'Found element: ' + truncated;
+      var msg = 'Found element: ' + truncated;
+      var count = window.__MCP__.countAll(selector, strategy);
+      if (count > 1) msg += '\n(+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+      return msg;
    }
 
    return 'Element not found';

package/dist/driver/scripts/focus.js

@@ -2,19 +2,23 @@
  * Focus an element
  *
  * @param {Object} params
- * @param {string} params.selector - CSS selector or ref ID (e.g., "ref=e3") for element to focus
+ * @param {string} params.selector - CSS selector, XPath, text, or ref ID (e.g., "ref=e3") for element to focus
+ * @param {string} params.strategy - Selector strategy: 'css', 'xpath', or 'text'
  */
 (function(params) {
-   const { selector } = params;
+   const { selector, strategy } = params;
 
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var el = window.__MCP__.resolveRef(selectorOrRef);
+      var el = window.__MCP__.resolveRef(selectorOrRef, strategy);
       if (!el) throw new Error('Element not found: ' + selectorOrRef);
       return el;
    }
 
    const element = resolveElement(selector);
    element.focus();
-   return `Focused element: ${selector}`;
+   var msg = 'Focused element: ' + selector;
+   var count = window.__MCP__.countAll(selector, strategy);
+   if (count > 1) msg += ' (+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+   return msg;
 })

package/dist/driver/scripts/get-styles.js

@@ -2,36 +2,33 @@
  * Get computed CSS styles for elements
  *
  * @param {Object} params
- * @param {string} params.selector - CSS selector or ref ID (e.g., "ref=e3") for element(s)
+ * @param {string} params.selector - CSS selector, XPath, text, or ref ID (e.g., "ref=e3") for element(s)
+ * @param {string} params.strategy - Selector strategy: 'css', 'xpath', or 'text'
  * @param {string[]} params.properties - Specific CSS properties to retrieve
  * @param {boolean} params.multiple - Whether to get styles for all matching elements
  */
 (function(params) {
-   const { selector, properties, multiple } = params;
+   const { selector, strategy, properties, multiple } = params;
 
-   function resolveElement(selectorOrRef) {
-      if (!selectorOrRef) return null;
-      var el = window.__MCP__.resolveRef(selectorOrRef);
-      if (!el) throw new Error('Element not found: ' + selectorOrRef);
-      return el;
-   }
+   var elements;
 
-   // Check if selector is a ref ID - if so, multiple doesn't apply
-   const isRef = /^\[?(?:ref=)?(e\d+)\]?$/.test(selector);
-   const elements = isRef
-      ? [resolveElement(selector)]
-      : (multiple ? Array.from(document.querySelectorAll(selector)) : [document.querySelector(selector)]);
+   if (multiple) {
+      elements = window.__MCP__.resolveAll(selector, strategy);
+   } else {
+      var el = window.__MCP__.resolveRef(selector, strategy);
+      elements = el ? [el] : [];
+   }
 
    if (!elements[0]) {
-      throw new Error(`Element not found: ${selector}`);
+      throw new Error('Element not found: ' + selector);
    }
 
-   const results = elements.map(element => {
+   const results = elements.map(function(element) {
       const styles = window.getComputedStyle(element);
 
       if (properties.length > 0) {
          const result = {};
-         properties.forEach(prop => {
+         properties.forEach(function(prop) {
             result[prop] = styles.getPropertyValue(prop);
          });
          return result;

package/dist/driver/scripts/html2canvas-loader.js

@@ -22,7 +22,11 @@ export function getHtml2CanvasSource() {
         // Resolve the path to html2canvas-pro.js (UMD build)
         // Note: We use the main entry point since the minified version isn't exported
         const html2canvasProPath = require.resolve('html2canvas-pro');
-        html2canvasProSource = readFileSync(html2canvasProPath, 'utf-8');
+        html2canvasProSource = readFileSync(html2canvasProPath, 'utf-8')
+            // Strip sourceMappingURL to prevent the browser from trying to fetch the
+            // .map file relative to the page's base URL (which fails when the app is
+            // served under a sub-path like '/some/path/').
+            .replace(/\/\/[#@]\s*sourceMappingURL=.*/g, '');
     }
     return html2canvasProSource;
 }

package/dist/driver/scripts/index.js

@@ -41,14 +41,17 @@ export function buildScript(script, params) {
 /**
  * Build a script for typing text (uses the keyboard script's typeText function)
  */
-export function buildTypeScript(selector, text) {
+export function buildTypeScript(selector, text, strategy) {
     const escapedText = text.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    const escapedSelector = selector.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    const strat = strategy || 'css';
     return `
       (function() {
-         const selector = '${selector}';
+         const selector = '${escapedSelector}';
+         const strategy = '${strat}';
          const text = '${escapedText}';
 
-         var element = window.__MCP__.resolveRef(selector);
+         var element = window.__MCP__.resolveRef(selector, strategy);
          if (!element) throw new Error('Element not found: ' + selector);
 
          element.focus();
@@ -56,7 +59,10 @@ export function buildTypeScript(selector, text) {
          element.dispatchEvent(new Event('input', { bubbles: true }));
          element.dispatchEvent(new Event('change', { bubbles: true }));
 
-         return 'Typed "' + text + '" into ' + selector;
+         var msg = 'Typed "' + text + '" into ' + selector;
+         var count = window.__MCP__.countAll(selector, strategy);
+         if (count > 1) msg += ' (+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+         return msg;
       })()
    `;
 }

package/dist/driver/scripts/interact.js

@@ -4,7 +4,8 @@
  *
  * @param {Object} params
  * @param {string} params.action - The action to perform
- * @param {string|null} params.selector - CSS selector or ref ID (e.g., "ref=e3") for the element
+ * @param {string|null} params.selector - CSS selector, XPath, text, or ref ID (e.g., "ref=e3") for the element
+ * @param {string} params.strategy - Selector strategy: 'css', 'xpath', or 'text'
  * @param {number|null} params.x - X coordinate
  * @param {number|null} params.y - Y coordinate
  * @param {number} params.duration - Duration for long-press
@@ -12,15 +13,22 @@
  * @param {number} params.scrollY - Vertical scroll amount
  */
 (function(params) {
-   const { action, selector, x, y, duration, scrollX, scrollY } = params;
+   const { action, selector, strategy, x, y, duration, scrollX, scrollY } = params;
 
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var el = window.__MCP__.resolveRef(selectorOrRef);
+      var el = window.__MCP__.resolveRef(selectorOrRef, strategy);
       if (!el) throw new Error('Element not found: ' + selectorOrRef);
       return el;
    }
 
+   function matchHint() {
+      if (!selector) return '';
+      var count = window.__MCP__.countAll(selector, strategy);
+      if (count > 1) return ' (+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+      return '';
+   }
+
    let element = null;
    let targetX, targetY;
 
@@ -60,7 +68,7 @@
          element.dispatchEvent(new MouseEvent('mouseup', eventOptions));
          element.dispatchEvent(new MouseEvent('click', eventOptions));
       }
-      return `Clicked at (${targetX}, ${targetY})`;
+      return `Clicked at (${targetX}, ${targetY})` + matchHint();
    }
 
    if (action === 'double-click') {
@@ -73,7 +81,7 @@
          element.dispatchEvent(new MouseEvent('click', eventOptions));
          element.dispatchEvent(new MouseEvent('dblclick', eventOptions));
       }
-      return `Double-clicked at (${targetX}, ${targetY})`;
+      return `Double-clicked at (${targetX}, ${targetY})` + matchHint();
    }
 
    if (action === 'long-press') {
@@ -83,7 +91,7 @@
             element.dispatchEvent(new MouseEvent('mouseup', eventOptions));
          }, duration);
       }
-      return `Long-pressed at (${targetX}, ${targetY}) for ${duration}ms`;
+      return `Long-pressed at (${targetX}, ${targetY}) for ${duration}ms` + matchHint();
    }
 
    if (action === 'scroll') {
@@ -95,7 +103,7 @@
             scrollTarget.scrollLeft += scrollX;
             scrollTarget.scrollTop += scrollY;
          }
-         return `Scrolled by (${scrollX}, ${scrollY}) pixels`;
+         return `Scrolled by (${scrollX}, ${scrollY}) pixels` + matchHint();
       }
       return 'No scroll performed (scrollX and scrollY are both 0)';
    }

package/dist/driver/scripts/resolve-ref.js

@@ -1,16 +1,43 @@
 /**
  * Shared ref resolver - always available via window.__MCP__.resolveRef.
- * Accepts a ref ID ("e3", "ref=e3", "[ref=e3]") or CSS selector.
+ * Accepts a ref ID ("e3", "ref=e3", "[ref=e3]"), CSS selector, XPath, or text.
  * Returns the DOM element, or null if not found.
  *
  * Reads window.__MCP__.reverseRefs dynamically at call time so it always
  * uses the latest snapshot's data.
+ *
+ * Also provides:
+ * - resolveAll(selector, strategy) - returns an Array of matching elements
+ * - countAll(selector, strategy)   - returns the total match count
  */
 (function() {
    window.__MCP__ = window.__MCP__ || {};
-   window.__MCP__.resolveRef = function(selectorOrRef) {
+
+   var REF_PATTERN = /^\[?(?:ref=)?(e\d+)\]?$/;
+
+   function xpathForText(text) {
+      // Escape single quotes for XPath by splitting on ' and using concat()
+      if (text.indexOf("'") === -1) {
+         return "//*[contains(text(), '" + text + "')]";
+      }
+      var parts = text.split("'");
+      var expr = 'concat(' + parts.map(function(p, i) {
+         return (i > 0 ? ",\"'\",": '') + "'" + p + "'";
+      }).join('') + ')';
+      return '//*[contains(text(), ' + expr + ')]';
+   }
+
+   /**
+    * Resolve a single element by selector and strategy.
+    * @param {string} selectorOrRef - Selector, ref ID, XPath, or text
+    * @param {string} [strategy]    - 'css' (default), 'xpath', or 'text'
+    * @returns {Element|null}
+    */
+   window.__MCP__.resolveRef = function(selectorOrRef, strategy) {
       if (!selectorOrRef) return null;
-      var refMatch = selectorOrRef.match(/^\[?(?:ref=)?(e\d+)\]?$/);
+
+      // Ref IDs always take priority regardless of strategy
+      var refMatch = selectorOrRef.match(REF_PATTERN);
       if (refMatch) {
          var reverseRefs = window.__MCP__.reverseRefs;
          if (!reverseRefs) {
@@ -18,6 +45,68 @@
          }
          return reverseRefs.get(refMatch[1]) || null;
       }
+
+      if (strategy === 'text') {
+         var xpath = xpathForText(selectorOrRef);
+         var result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+         return result.singleNodeValue;
+      }
+
+      if (strategy === 'xpath') {
+         var result = document.evaluate(selectorOrRef, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+         return result.singleNodeValue;
+      }
+
+      // Default: CSS selector
       return document.querySelector(selectorOrRef);
    };
+
+   /**
+    * Resolve all matching elements as an Array.
+    * @param {string} selector  - Selector, XPath, or text
+    * @param {string} [strategy] - 'css' (default), 'xpath', or 'text'
+    * @returns {Element[]}
+    */
+   window.__MCP__.resolveAll = function(selector, strategy) {
+      if (!selector) return [];
+
+      // Ref IDs resolve to a single element
+      var refMatch = selector.match(REF_PATTERN);
+      if (refMatch) {
+         var el = window.__MCP__.resolveRef(selector);
+         return el ? [el] : [];
+      }
+
+      if (strategy === 'text') {
+         var xpath = xpathForText(selector);
+         var snapshot = document.evaluate(xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+         var results = [];
+         for (var i = 0; i < snapshot.snapshotLength; i++) {
+            results.push(snapshot.snapshotItem(i));
+         }
+         return results;
+      }
+
+      if (strategy === 'xpath') {
+         var snapshot = document.evaluate(selector, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+         var results = [];
+         for (var i = 0; i < snapshot.snapshotLength; i++) {
+            results.push(snapshot.snapshotItem(i));
+         }
+         return results;
+      }
+
+      // Default: CSS
+      return Array.from(document.querySelectorAll(selector));
+   };
+
+   /**
+    * Count all matching elements.
+    * @param {string} selector  - Selector, XPath, or text
+    * @param {string} [strategy] - 'css' (default), 'xpath', or 'text'
+    * @returns {number}
+    */
+   window.__MCP__.countAll = function(selector, strategy) {
+      return window.__MCP__.resolveAll(selector, strategy).length;
+   };
 })();

package/dist/driver/scripts/wait-for.js

@@ -4,34 +4,38 @@
  * @param {Object} params
  * @param {string} params.type - What to wait for: 'selector', 'text', 'ipc-event'
  * @param {string} params.value - Selector/ref ID, text, or event name to wait for
+ * @param {string} params.strategy - Selector strategy (applies when type is 'selector'): 'css', 'xpath', or 'text'
  * @param {number} params.timeout - Timeout in milliseconds
  */
 (async function(params) {
-   const { type, value, timeout } = params;
+   const { type, value, strategy, timeout } = params;
    const startTime = Date.now();
 
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      return window.__MCP__.resolveRef(selectorOrRef);
+      return window.__MCP__.resolveRef(selectorOrRef, strategy);
    }
 
-   return new Promise((resolve, reject) => {
+   return new Promise(function(resolve, reject) {
       function check() {
          if (Date.now() - startTime > timeout) {
-            reject(new Error(`Timeout waiting for ${type}: ${value}`));
+            reject(new Error('Timeout waiting for ' + type + ': ' + value));
             return;
          }
 
          if (type === 'selector') {
-            const element = resolveElement(value);
+            var element = resolveElement(value);
             if (element) {
-               resolve(`Element found: ${value}`);
+               var msg = 'Element found: ' + value;
+               var count = window.__MCP__.countAll(value, strategy);
+               if (count > 1) msg += ' (+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+               resolve(msg);
                return;
             }
          } else if (type === 'text') {
-            const found = document.body.innerText.includes(value);
+            var found = document.body.innerText.includes(value);
             if (found) {
-               resolve(`Text found: ${value}`);
+               resolve('Text found: ' + value);
                return;
             }
          } else if (type === 'ipc-event') {

package/dist/driver/webview-interactions.js

@@ -15,12 +15,22 @@ export const WindowTargetSchema = z.object({
     appIdentifier: z.union([z.string(), z.number()]).optional().describe('App port or bundle ID to target. Defaults to the only connected app or the default app if multiple are connected.'),
 });
 // ============================================================================
+// Shared Selector Strategy
+// ============================================================================
+/**
+ * Reusable strategy field for tools that accept a selector.
+ * Defaults to 'css' for backward compatibility.
+ */
+const selectorStrategyField = z.enum(['css', 'xpath', 'text']).default('css').describe('Selector strategy: "css" (default) for CSS selectors, "xpath" for XPath expressions, ' +
+    '"text" to find elements containing the given text. Ref IDs (e.g., "ref=e3") work with any strategy.');
+// ============================================================================
 // Schemas
 // ============================================================================
 export const InteractSchema = WindowTargetSchema.extend({
     action: z.enum(['click', 'double-click', 'long-press', 'scroll', 'swipe', 'focus'])
         .describe('Type of interaction to perform'),
-    selector: z.string().optional().describe('CSS selector for the element to interact with'),
+    selector: z.string().optional().describe('Element selector: CSS selector (default), XPath expression, text content, or ref ID (e.g., "ref=e3")'),
+    strategy: selectorStrategyField,
     x: z.number().optional().describe('X coordinate for direct coordinate interaction'),
     y: z.number().optional().describe('Y coordinate for direct coordinate interaction'),
     duration: z.number().optional()
@@ -42,7 +52,9 @@ export const ScreenshotSchema = WindowTargetSchema.extend({
 export const KeyboardSchema = WindowTargetSchema.extend({
     action: z.enum(['type', 'press', 'down', 'up'])
         .describe('Keyboard action type: "type" for typing text into an element, "press/down/up" for key events'),
-    selector: z.string().optional().describe('CSS selector for element to type into (required for "type" action)'),
+    selector: z.string().optional().describe('Element selector for element to type into (required for "type" action): ' +
+        'CSS selector (default), XPath, text content, or ref ID'),
+    strategy: selectorStrategyField,
     text: z.string().optional().describe('Text to type (required for "type" action)'),
     key: z.string().optional().describe('Key to press (required for "press/down/up" actions, e.g., "Enter", "a", "Escape")'),
     modifiers: z.array(z.enum(['Control', 'Alt', 'Shift', 'Meta'])).optional().describe('Modifier keys to hold'),
@@ -50,10 +62,12 @@ export const KeyboardSchema = WindowTargetSchema.extend({
 export const WaitForSchema = WindowTargetSchema.extend({
     type: z.enum(['selector', 'text', 'ipc-event']).describe('What to wait for'),
     value: z.string().describe('Selector, text content, or IPC event name to wait for'),
+    strategy: selectorStrategyField.describe('Selector strategy (applies when type is "selector"): "css" (default), "xpath", or "text".'),
     timeout: z.number().optional().default(5000).describe('Timeout in milliseconds (default: 5000ms)'),
 });
 export const GetStylesSchema = WindowTargetSchema.extend({
-    selector: z.string().describe('CSS selector for element(s) to get styles from'),
+    selector: z.string().describe('Element selector: CSS selector (default), XPath expression, text content, or ref ID'),
+    strategy: selectorStrategyField,
     properties: z.array(z.string()).optional().describe('Specific CSS properties to retrieve. If omitted, returns all computed styles'),
     multiple: z.boolean().optional().default(false)
         .describe('Whether to get styles for all matching elements (true) or just the first (false)'),
@@ -68,8 +82,9 @@ export const FocusElementSchema = WindowTargetSchema.extend({
     selector: z.string().describe('CSS selector for element to focus'),
 });
 export const FindElementSchema = WindowTargetSchema.extend({
-    selector: z.string(),
-    strategy: z.enum(['css', 'xpath', 'text']).default('css'),
+    selector: z.string().describe('The selector to find: CSS selector (default), XPath expression, text content, or ref ID (e.g., "ref=e3"). ' +
+        'Interpretation depends on strategy.'),
+    strategy: selectorStrategyField,
 });
 export const GetConsoleLogsSchema = WindowTargetSchema.extend({
     filter: z.string().optional().describe('Regex or keyword to filter logs'),
@@ -77,13 +92,14 @@ export const GetConsoleLogsSchema = WindowTargetSchema.extend({
 });
 export const DomSnapshotSchema = WindowTargetSchema.extend({
     type: z.enum(['accessibility', 'structure']).describe('Snapshot type'),
-    selector: z.string().optional().describe('CSS selector to scope the snapshot. If omitted, snapshots entire document.'),
+    selector: z.string().optional().describe('Selector to scope the snapshot: CSS selector (default), XPath, text content, or ref ID. If omitted, snapshots entire document.'),
+    strategy: selectorStrategyField,
 });
 // ============================================================================
 // Implementation Functions
 // ============================================================================
 export async function interact(options) {
-    const { action, selector, x, y, duration, scrollX, scrollY, fromX, fromY, toX, toY, windowId, appIdentifier } = options;
+    const { action, selector, strategy, x, y, duration, scrollX, scrollY, fromX, fromY, toX, toY, windowId, appIdentifier } = options;
     // Handle swipe action separately since it has different logic
     if (action === 'swipe') {
         return performSwipe({ fromX, fromY, toX, toY, duration, windowId, appIdentifier });
@@ -93,11 +109,12 @@ export async function interact(options) {
         if (!selector) {
             throw new Error('Focus action requires a selector');
         }
-        return focusElement({ selector, windowId, appIdentifier });
+        return focusElement({ selector, strategy, windowId, appIdentifier });
     }
     const script = buildScript(SCRIPTS.interact, {
         action,
         selector: selector ?? null,
+        strategy: strategy ?? 'css',
         x: x ?? null,
         y: y ?? null,
         duration: duration ?? 500,
@@ -146,7 +163,7 @@ export async function screenshot(options = {}) {
     return result;
 }
 export async function keyboard(options) {
-    const { action, selectorOrKey, textOrModifiers, modifiers, windowId, appIdentifier } = options;
+    const { action, selectorOrKey, strategy, textOrModifiers, modifiers, windowId, appIdentifier } = options;
     // Handle the different parameter combinations based on action
     if (action === 'type') {
         const selector = selectorOrKey;
@@ -154,7 +171,7 @@ export async function keyboard(options) {
         if (!selector || !text) {
             throw new Error('Type action requires both selector and text parameters');
         }
-        const script = buildTypeScript(selector, text);
+        const script = buildTypeScript(selector, text, strategy);
         try {
             return await executeInWebview(script, windowId, appIdentifier);
         }
@@ -179,8 +196,8 @@ export async function keyboard(options) {
     }
 }
 export async function waitFor(options) {
-    const { type, value, timeout = 5000, windowId, appIdentifier } = options;
-    const script = buildScript(SCRIPTS.waitFor, { type, value, timeout });
+    const { type, value, strategy, timeout = 5000, windowId, appIdentifier } = options;
+    const script = buildScript(SCRIPTS.waitFor, { type, value, strategy: strategy ?? 'css', timeout });
     try {
         return await executeInWebview(script, windowId, appIdentifier);
     }
@@ -190,9 +207,10 @@ export async function waitFor(options) {
     }
 }
 export async function getStyles(options) {
-    const { selector, properties, multiple = false, windowId, appIdentifier } = options;
+    const { selector, strategy, properties, multiple = false, windowId, appIdentifier } = options;
     const script = buildScript(SCRIPTS.getStyles, {
         selector,
+        strategy: strategy ?? 'css',
         properties: properties || [],
         multiple,
     });
@@ -232,8 +250,8 @@ export async function executeJavaScript(options) {
     }
 }
 export async function focusElement(options) {
-    const { selector, windowId, appIdentifier } = options;
-    const script = buildScript(SCRIPTS.focus, { selector });
+    const { selector, strategy, windowId, appIdentifier } = options;
+    const script = buildScript(SCRIPTS.focus, { selector, strategy: strategy ?? 'css' });
     try {
         return await executeInWebview(script, windowId, appIdentifier);
     }
@@ -274,13 +292,13 @@ export async function getConsoleLogs(options = {}) {
  * Uses aria-api for comprehensive, spec-compliant accessibility computation.
  */
 export async function domSnapshot(options) {
-    const { type, selector, windowId, appIdentifier } = options;
+    const { type, selector, strategy, windowId, appIdentifier } = options;
     // Only load aria-api for accessibility snapshots
     if (type === 'accessibility') {
         await ensureAriaApiLoaded(windowId);
     }
     // Then execute the snapshot script
-    const script = buildScript(SCRIPTS.domSnapshot, { type, selector: selector ?? null });
+    const script = buildScript(SCRIPTS.domSnapshot, { type, selector: selector ?? null, strategy: strategy ?? 'css' });
     try {
         return await executeInWebview(script, windowId, appIdentifier);
     }

package/dist/tools-registry.js

@@ -48,123 +48,27 @@ First, verify this is a Tauri v2 project:
 Examine these files and report what needs to be added or updated:
 
 ### 1. Rust Plugin Dependency
-
-Check \`src-tauri/Cargo.toml\` for \`tauri-plugin-mcp-bridge\`.
-It should be an **optional** dependency behind a Cargo feature
-so that it is completely excluded from production builds:
-
+Check \`src-tauri/Cargo.toml\` for \`tauri-plugin-mcp-bridge\`. If missing or outdated, note that it needs:
 \`\`\`toml
 [dependencies]
-tauri-plugin-mcp-bridge = { version = "${PLUGIN_VERSION_CARGO}", optional = true }
-\`\`\`
-
-Under \`[features]\`, add a feature that enables it:
-
-\`\`\`toml
-[features]
-mcp-bridge = ["dep:tauri-plugin-mcp-bridge"]
+tauri-plugin-mcp-bridge = "${PLUGIN_VERSION_CARGO}"
 \`\`\`
 
 ### 2. Plugin Registration
-
-Check \`src-tauri/src/lib.rs\` or \`src-tauri/src/main.rs\` for plugin
-registration. It should be gated behind the \`mcp-bridge\` feature flag:
-
+Check \`src-tauri/src/lib.rs\` or \`src-tauri/src/main.rs\` for plugin registration. It should have:
 \`\`\`rust
-#[cfg(all(feature = "mcp-bridge", debug_assertions))]
+#[cfg(debug_assertions)]
 {
     builder = builder.plugin(tauri_plugin_mcp_bridge::init());
 }
 \`\`\`
 
 ### 3. Global Tauri Setting
-
 Check \`src-tauri/tauri.conf.json\` for \`withGlobalTauri: true\` under the \`app\` section.
 **This is required** - without it, the MCP bridge cannot communicate with the webview.
 
-This setting should only be enabled for development. If the project
-uses a \`tauri.dev.conf.json\` overlay (applied only during
-\`cargo tauri dev\`), prefer placing it there:
-
-\`\`\`json
-{
-   "app": {
-      "withGlobalTauri": true
-   }
-}
-\`\`\`
-
-### 4. Plugin Capability (Conditional via build.rs)
-
-The \`mcp-bridge:default\` permission must **not** be added to
-\`src-tauri/capabilities/default.json\`. Instead, it should be
-conditionally generated by the build script so that it only exists
-when the \`mcp-bridge\` feature is active.
-
-Check \`src-tauri/build.rs\` and update it to conditionally write
-(or remove) a separate capability file before
-\`tauri_build::build()\` runs. Tauri auto-discovers all \`.json\`
-files in \`capabilities/\`, so this ensures the permission is only
-present when the feature is enabled:
-
-\`\`\`rust
-fn main() {
-   let mcp_cap_path = std::path::Path::new("capabilities/mcp-bridge.json");
-   #[cfg(all(feature = "mcp-bridge", debug_assertions))]
-   {
-      let cap = r#"{
-   "identifier": "mcp-bridge",
-   "description": "enables MCP bridge for development",
-   "windows": [
-      "main"
-   ],
-   "permissions": [
-      "mcp-bridge:default"
-   ]
-}"#;
-      std::fs::write(mcp_cap_path, cap)
-         .expect("failed to write mcp-bridge capability");
-   }
-   #[cfg(not(all(feature = "mcp-bridge", debug_assertions)))]
-   {
-      let _ = std::fs::remove_file(mcp_cap_path);
-   }
-
-   tauri_build::build()
-}
-\`\`\`
-
-If \`build.rs\` already has other logic, integrate the conditional
-block before the \`tauri_build::build()\` call.
-
-### 5. Gitignore the Generated Capability File
-
-Since \`capabilities/mcp-bridge.json\` is generated at build time, add it to \`src-tauri/.gitignore\`:
-
-\`\`\`gitignore
-/capabilities/mcp-bridge.json
-\`\`\`
-
-### 6. Dev Scripts (package.json)
-
-If the project uses npm scripts to run \`tauri dev\`, add
-\`--features mcp-bridge\` to the dev scripts so the feature is
-automatically enabled. For example:
-
-\`\`\`json
-{
-   "scripts": {
-      "dev": "tauri dev --features mcp-bridge",
-      "dev:ios": "tauri ios dev --features mcp-bridge",
-      "dev:android": "tauri android dev --features mcp-bridge"
-   }
-}
-\`\`\`
-
-Do **not** add \`--features mcp-bridge\` to release-profile dev
-scripts (e.g. those using \`--release\`), as \`debug_assertions\`
-is false in release builds and the guard will exclude the plugin
-anyway.
+### 4. Plugin Permissions
+Check \`src-tauri/capabilities/default.json\` (or similar) for \`"mcp-bridge:default"\` permission.
 
 ## Response Format
 
@@ -179,19 +83,13 @@ Only after the user says yes should you make any modifications.
 ## After Setup
 
 Once changes are approved and made:
-1. Run the Tauri app in development mode — if npm scripts were
-   updated, use \`npm run dev\`. Otherwise use
-   \`cargo tauri dev --features mcp-bridge\` directly.
+1. Run the Tauri app in development mode (\`cargo tauri dev\`)
 2. Use \`driver_session\` with action "start" to connect
 3. Use \`driver_session\` with action "status" to verify
 
 ## Notes
 
-- The plugin is completely excluded from production builds — both
-  \`cfg(feature = "mcp-bridge")\` and \`cfg(debug_assertions)\` must
-  be true, so even if the feature flag is accidentally enabled in a
-  release build, the plugin will not be included
-- The \`mcp-bridge\` Cargo feature must be passed explicitly — either via npm dev scripts or \`cargo tauri dev --features mcp-bridge\`
+- The plugin only runs in debug builds so it won't affect production
 - The WebSocket server binds to \`0.0.0.0:9223\` by default
 - For localhost-only access, use \`Builder::new().bind_address("127.0.0.1").build()\`
 `;
@@ -271,6 +169,8 @@ export const TOOLS = [
     {
         name: 'webview_find_element',
         description: '[Tauri Apps Only] Find DOM elements in a running Tauri app\'s webview. ' +
+            'Supports CSS selectors (default), XPath expressions, and text content matching via the strategy parameter. ' +
+            'Returns the element\'s HTML. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC + ' ' +
             'For browser pages or documentation sites, use Chrome DevTools MCP instead.',
@@ -314,6 +214,7 @@ export const TOOLS = [
         name: 'webview_interact',
         description: '[Tauri Apps Only] Click, scroll, swipe, focus, or perform gestures in a Tauri app webview. ' +
             'Supported actions: click, double-click, long-press, scroll, swipe, focus. ' +
+            'Supports CSS selectors (default), XPath, and text content matching via the strategy parameter. ' +
             'Requires active driver_session. ' +
             'For browser interaction, use Chrome DevTools MCP instead.',
         category: TOOL_CATEGORIES.UI_AUTOMATION,
@@ -364,6 +265,8 @@ export const TOOLS = [
     {
         name: 'webview_keyboard',
         description: '[Tauri Apps Only] Type text or send keyboard events in a Tauri app. ' +
+            'The selector parameter (for "type" action) supports CSS selectors (default), ' +
+            'XPath, and text content matching via the strategy parameter. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC + ' ' +
             'For browser keyboard input, use Chrome DevTools MCP instead.',
@@ -381,6 +284,7 @@ export const TOOLS = [
                 return await keyboard({
                     action: parsed.action,
                     selectorOrKey: parsed.selector,
+                    strategy: parsed.strategy,
                     textOrModifiers: parsed.text,
                     windowId: parsed.windowId,
                     appIdentifier: parsed.appIdentifier,
@@ -398,6 +302,7 @@ export const TOOLS = [
     {
         name: 'webview_wait_for',
         description: '[Tauri Apps Only] Wait for elements, text, or IPC events in a Tauri app. ' +
+            'When type is "selector", supports CSS (default), XPath, and text strategies via the strategy parameter. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC + ' ' +
             'For browser waits, use Chrome DevTools MCP instead.',
@@ -413,6 +318,7 @@ export const TOOLS = [
             return await waitFor({
                 type: parsed.type,
                 value: parsed.value,
+                strategy: parsed.strategy,
                 timeout: parsed.timeout,
                 windowId: parsed.windowId,
                 appIdentifier: parsed.appIdentifier,
@@ -422,6 +328,7 @@ export const TOOLS = [
     {
         name: 'webview_get_styles',
         description: '[Tauri Apps Only] Get computed CSS styles from elements in a Tauri app. ' +
+            'Supports CSS selectors (default), XPath, and text content matching via the strategy parameter. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC + ' ' +
             'For browser style inspection, use Chrome DevTools MCP instead.',
@@ -436,6 +343,7 @@ export const TOOLS = [
             const parsed = GetStylesSchema.parse(args);
             return await getStyles({
                 selector: parsed.selector,
+                strategy: parsed.strategy,
                 properties: parsed.properties,
                 multiple: parsed.multiple,
                 windowId: parsed.windowId,
@@ -480,6 +388,7 @@ export const TOOLS = [
             'with element tag names, IDs, CSS classes, and data-testid attributes (if present). ' +
             'Use this for understanding page layout, debugging CSS selectors, or locating elements by class/ID. ' +
             'Use the optional selector parameter to scope the snapshot to a subtree. ' +
+            'The selector supports CSS (default), XPath, and text content matching via the strategy parameter. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC,
         category: TOOL_CATEGORIES.UI_AUTOMATION,
@@ -494,6 +403,7 @@ export const TOOLS = [
             return await domSnapshot({
                 type: parsed.type,
                 selector: parsed.selector,
+                strategy: parsed.strategy,
                 windowId: parsed.windowId,
                 appIdentifier: parsed.appIdentifier,
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypothesi/tauri-mcp-server",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "mcpName": "io.github.hypothesi/mcp-server-tauri",
   "description": "A Model Context Protocol server for use with Tauri v2 applications",
   "type": "module",