@hypothesi/tauri-mcp-server 0.8.0 → 0.8.2

package/dist/driver/plugin-client.js

@@ -127,43 +127,58 @@ export class PluginClient extends EventEmitter {
         }
     }
     /**
-     * Send a command to the plugin and wait for response
+     * Send a command to the plugin and wait for response.
+     *
+     * Automatically retries on transient "not found" errors (e.g. window not
+     * yet registered after WebSocket connect) with exponential backoff.
      */
     async sendCommand(command, timeoutMs = 5000) {
-        // If not connected, try to reconnect first
-        if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
-            try {
-                await this.connect();
+        const maxRetries = 3;
+        const baseDelayMs = 100;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            // If not connected, try to reconnect first
+            if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+                try {
+                    await this.connect();
+                }
+                catch {
+                    throw new Error('Not connected to plugin and reconnection failed');
+                }
             }
-            catch {
-                throw new Error('Not connected to plugin and reconnection failed');
+            // Double-check connection after reconnect attempt
+            if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+                throw new Error('Not connected to plugin');
             }
-        }
-        // Double-check connection after reconnect attempt
-        if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
-            throw new Error('Not connected to plugin');
-        }
-        // Generate unique ID for this request
-        const id = `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-        const commandWithId = { ...command, id };
-        return new Promise((resolve, reject) => {
-            // Set up timeout
-            const timeout = setTimeout(() => {
-                this._pendingRequests.delete(id);
-                reject(new Error(`Request timeout after ${timeoutMs}ms`));
-            }, timeoutMs);
-            // Store pending request
-            this._pendingRequests.set(id, { resolve, reject, timeout });
-            // Send command
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            this._ws.send(JSON.stringify(commandWithId), (error) => {
-                if (error) {
-                    clearTimeout(timeout);
+            // Generate unique ID for this request
+            const id = `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            const commandWithId = { ...command, id };
+            const response = await new Promise((resolve, reject) => {
+                // Set up timeout
+                const timeout = setTimeout(() => {
                     this._pendingRequests.delete(id);
-                    reject(error);
-                }
+                    reject(new Error(`Request timeout after ${timeoutMs}ms`));
+                }, timeoutMs);
+                // Store pending request
+                this._pendingRequests.set(id, { resolve, reject, timeout });
+                // Send command
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                this._ws.send(JSON.stringify(commandWithId), (error) => {
+                    if (error) {
+                        clearTimeout(timeout);
+                        this._pendingRequests.delete(id);
+                        reject(error);
+                    }
+                });
             });
-        });
+            // Retry on "not found" errors (window not yet registered)
+            if (!response.success && response.error?.includes('not found') && attempt < maxRetries) {
+                await new Promise((r) => { setTimeout(r, baseDelayMs * Math.pow(2, attempt)); });
+                continue;
+            }
+            return response;
+        }
+        // Unreachable — loop always returns or throws — but satisfies TypeScript
+        throw new Error('Retry attempts exhausted');
     }
     /**
      * Check if connected

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

@@ -56,8 +56,9 @@
       return refMap.get(element);
    }
 
-   window.__MCP_ARIA_REFS__ = refMap;
-   window.__MCP_ARIA_REFS_REVERSE__ = reverseRefMap;
+   window.__MCP__ = window.__MCP__ || {};
+   window.__MCP__.refs = refMap;
+   window.__MCP__.reverseRefs = reverseRefMap;
 
    // ========================================================================
    // Visibility (using aria-api for correct aria-hidden inheritance)

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

@@ -10,13 +10,8 @@
    let element;
 
    // Check if it's a ref ID first (works with any strategy)
-   const refMatch = selector.match(/^(?:ref=)?(e\d+)$/);
-   if (refMatch) {
-      const refId = refMatch[1],
-            refMap = window.__MCP_ARIA_REFS_REVERSE__;
-      if (refMap) {
-         element = refMap.get(refId);
-      }
+   if (/^\[?(?:ref=)?(e\d+)\]?$/.test(selector)) {
+      element = window.__MCP__.resolveRef(selector);
    } else if (strategy === 'text') {
       // Find element containing text
       const xpath = "//*[contains(text(), '" + selector + "')]";
@@ -40,7 +35,7 @@
       element = result.singleNodeValue;
    } else {
       // CSS selector (default)
-      element = document.querySelector(selector);
+      element = window.__MCP__.resolveRef(selector);
    }
 
    if (element) {

package/dist/driver/scripts/focus.js

@@ -7,19 +7,9 @@
 (function(params) {
    const { selector } = params;
 
-   // Resolve element from CSS selector or ref ID (e.g., "ref=e3" or "e3")
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var refMatch = selectorOrRef.match(/^(?:ref=)?(e\d+)$/);
-      if (refMatch) {
-         var refId = refMatch[1],
-             refMap = window.__MCP_ARIA_REFS_REVERSE__;
-         if (!refMap) throw new Error('Ref "' + refId + '" not found. Run webview_dom_snapshot first to index elements.');
-         var el = refMap.get(refId);
-         if (!el) throw new Error('Ref "' + refId + '" not found. The DOM may have changed since the snapshot.');
-         return el;
-      }
-      var el = document.querySelector(selectorOrRef);
+      var el = window.__MCP__.resolveRef(selectorOrRef);
       if (!el) throw new Error('Element not found: ' + selectorOrRef);
       return el;
    }

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

@@ -9,25 +9,15 @@
 (function(params) {
    const { selector, properties, multiple } = params;
 
-   // Resolve element from CSS selector or ref ID (e.g., "ref=e3" or "e3")
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var refMatch = selectorOrRef.match(/^(?:ref=)?(e\d+)$/);
-      if (refMatch) {
-         var refId = refMatch[1],
-             refMap = window.__MCP_ARIA_REFS_REVERSE__;
-         if (!refMap) throw new Error('Ref "' + refId + '" not found. Run webview_dom_snapshot first to index elements.');
-         var el = refMap.get(refId);
-         if (!el) throw new Error('Ref "' + refId + '" not found. The DOM may have changed since the snapshot.');
-         return el;
-      }
-      var el = document.querySelector(selectorOrRef);
+      var el = window.__MCP__.resolveRef(selectorOrRef);
       if (!el) throw new Error('Element not found: ' + selectorOrRef);
       return el;
    }
 
    // Check if selector is a ref ID - if so, multiple doesn't apply
-   const isRef = /^(?:ref=)?(e\d+)$/.test(selector);
+   const isRef = /^\[?(?:ref=)?(e\d+)\]?$/.test(selector);
    const elements = isRef
       ? [resolveElement(selector)]
       : (multiple ? Array.from(document.querySelectorAll(selector)) : [document.querySelector(selector)]);

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

@@ -1,27 +1,30 @@
 /**
- * html2canvas library loader
+ * html2canvas-pro library loader
  *
- * Loads the html2canvas library from node_modules and provides it as a string
- * that can be injected into the webview.
+ * Loads the html2canvas-pro library from node_modules and provides it as a string
+ * that can be injected into the webview. html2canvas-pro is a fork of html2canvas
+ * that adds support for modern CSS color functions like oklch(), oklab(), lab(),
+ * lch(), and color().
  */
 import { readFileSync } from 'fs';
 import { createRequire } from 'module';
-// Use createRequire to resolve the path to html2canvas in node_modules
+// Use createRequire to resolve the path to html2canvas-pro in node_modules
 const require = createRequire(import.meta.url);
-let html2canvasSource = null;
+let html2canvasProSource = null;
 /** Script ID used for the html2canvas library in the script registry. */
 export const HTML2CANVAS_SCRIPT_ID = '__mcp_html2canvas__';
 /**
- * Get the html2canvas library source code.
+ * Get the html2canvas-pro library source code.
  * Loaded lazily and cached.
  */
 export function getHtml2CanvasSource() {
-    if (html2canvasSource === null) {
-        // Resolve the path to html2canvas.min.js
-        const html2canvasPath = require.resolve('html2canvas/dist/html2canvas.min.js');
-        html2canvasSource = readFileSync(html2canvasPath, 'utf-8');
+    if (html2canvasProSource === null) {
+        // 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');
     }
-    return html2canvasSource;
+    return html2canvasProSource;
 }
 /**
  * Build a script that captures a screenshot using html2canvas.

package/dist/driver/scripts/index.js

@@ -13,6 +13,7 @@ function loadScript(name) {
 }
 // Load scripts once at module initialization
 export const SCRIPTS = {
+    resolveRef: loadScript('resolve-ref'),
     interact: loadScript('interact'),
     swipe: loadScript('swipe'),
     keyboard: loadScript('keyboard'),
@@ -22,6 +23,14 @@ export const SCRIPTS = {
     findElement: loadScript('find-element'),
     domSnapshot: loadScript('dom-snapshot'),
 };
+/** Script ID used for resolve-ref in the script registry. */
+export const RESOLVE_REF_SCRIPT_ID = '__mcp_resolve_ref__';
+/**
+ * Get the resolve-ref script source code.
+ */
+export function getResolveRefSource() {
+    return SCRIPTS.resolveRef;
+}
 /**
  * Build a script invocation with parameters
  * The script should be an IIFE that accepts a params object
@@ -39,10 +48,8 @@ export function buildTypeScript(selector, text) {
          const selector = '${selector}';
          const text = '${escapedText}';
 
-         const element = document.querySelector(selector);
-         if (!element) {
-            throw new Error('Element not found: ' + selector);
-         }
+         var element = window.__MCP__.resolveRef(selector);
+         if (!element) throw new Error('Element not found: ' + selector);
 
          element.focus();
          element.value = text;

package/dist/driver/scripts/interact.js

@@ -14,19 +14,9 @@
 (function(params) {
    const { action, selector, x, y, duration, scrollX, scrollY } = params;
 
-   // Resolve element from CSS selector or ref ID (e.g., "ref=e3" or "e3")
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var refMatch = selectorOrRef.match(/^(?:ref=)?(e\d+)$/);
-      if (refMatch) {
-         var refId = refMatch[1],
-             refMap = window.__MCP_ARIA_REFS_REVERSE__;
-         if (!refMap) throw new Error('Ref "' + refId + '" not found. Run webview_dom_snapshot first to index elements.');
-         var el = refMap.get(refId);
-         if (!el) throw new Error('Ref "' + refId + '" not found. The DOM may have changed since the snapshot.');
-         return el;
-      }
-      var el = document.querySelector(selectorOrRef);
+      var el = window.__MCP__.resolveRef(selectorOrRef);
       if (!el) throw new Error('Element not found: ' + selectorOrRef);
       return el;
    }

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

@@ -0,0 +1,23 @@
+/**
+ * Shared ref resolver - always available via window.__MCP__.resolveRef.
+ * Accepts a ref ID ("e3", "ref=e3", "[ref=e3]") or CSS selector.
+ * 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.
+ */
+(function() {
+   window.__MCP__ = window.__MCP__ || {};
+   window.__MCP__.resolveRef = function(selectorOrRef) {
+      if (!selectorOrRef) return null;
+      var refMatch = selectorOrRef.match(/^\[?(?:ref=)?(e\d+)\]?$/);
+      if (refMatch) {
+         var reverseRefs = window.__MCP__.reverseRefs;
+         if (!reverseRefs) {
+            throw new Error('Ref IDs require a snapshot. Run webview_dom_snapshot first to index elements.');
+         }
+         return reverseRefs.get(refMatch[1]) || null;
+      }
+      return document.querySelector(selectorOrRef);
+   };
+})();

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

@@ -10,17 +10,9 @@
    const { type, value, timeout } = params;
    const startTime = Date.now();
 
-   // Resolve element from CSS selector or ref ID (e.g., "ref=e3" or "e3")
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var refMatch = selectorOrRef.match(/^(?:ref=)?(e\d+)$/);
-      if (refMatch) {
-         var refId = refMatch[1],
-             refMap = window.__MCP_ARIA_REFS_REVERSE__;
-         if (!refMap) return null; // For wait-for, return null instead of throwing
-         return refMap.get(refId) || null;
-      }
-      return document.querySelector(selectorOrRef);
+      return window.__MCP__.resolveRef(selectorOrRef);
    }
 
    return new Promise((resolve, reject) => {

package/dist/driver/webview-executor.js

@@ -4,6 +4,7 @@ import { hasActiveSession, getDefaultSession, resolveTargetApp } from './session
 import { createMcpLogger } from '../logger.js';
 import { buildScreenshotScript, buildScreenshotCaptureScript, getHtml2CanvasSource, HTML2CANVAS_SCRIPT_ID, } from './scripts/html2canvas-loader.js';
 import { registerScript, isScriptRegistered } from './script-manager.js';
+import { getResolveRefSource, RESOLVE_REF_SCRIPT_ID } from './scripts/index.js';
 /**
  * WebView Executor - Native IPC-based JavaScript execution
  *
@@ -44,6 +45,8 @@ export async function ensureReady() {
     if (session) {
         await connectPlugin(session.host, session.port);
     }
+    // Register the resolve-ref helper so ref-based selectors work in all tools
+    await registerScript(RESOLVE_REF_SCRIPT_ID, 'inline', getResolveRefSource());
     isInitialized = true;
 }
 /**

package/dist/tools-registry.js

@@ -48,27 +48,123 @@ 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\`. If missing or outdated, note that it needs:
+
+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:
+
 \`\`\`toml
 [dependencies]
-tauri-plugin-mcp-bridge = "${PLUGIN_VERSION_CARGO}"
+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"]
 \`\`\`
 
 ### 2. Plugin Registration
-Check \`src-tauri/src/lib.rs\` or \`src-tauri/src/main.rs\` for plugin registration. It should have:
+
+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:
+
 \`\`\`rust
-#[cfg(debug_assertions)]
+#[cfg(all(feature = "mcp-bridge", 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.
 
-### 4. Plugin Permissions
-Check \`src-tauri/capabilities/default.json\` (or similar) for \`"mcp-bridge:default"\` permission.
+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.
 
 ## Response Format
 
@@ -83,13 +179,19 @@ 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 (\`cargo tauri dev\`)
+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.
 2. Use \`driver_session\` with action "start" to connect
 3. Use \`driver_session\` with action "status" to verify
 
 ## Notes
 
-- The plugin only runs in debug builds so it won't affect production
+- 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 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()\`
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypothesi/tauri-mcp-server",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "mcpName": "io.github.hypothesi/mcp-server-tauri",
   "description": "A Model Context Protocol server for use with Tauri v2 applications",
   "type": "module",
@@ -49,13 +49,12 @@
     "@modelcontextprotocol/sdk": "0.6.1",
     "aria-api": "0.8.0",
     "execa": "9.6.0",
-    "html2canvas": "1.4.1",
+    "html2canvas-pro": "1.6.6",
     "ws": "8.18.3",
     "zod": "3.25.76",
     "zod-to-json-schema": "3.25.0"
   },
   "devDependencies": {
-    "@types/html2canvas": "0.5.35",
     "@types/node": "22.19.1",
     "@types/ws": "8.18.1",
     "esbuild": "0.25.12",