@hypothesi/tauri-mcp-server 0.12.0 → 0.13.0

package/dist/driver/scripts/focus.js

@@ -4,15 +4,42 @@
  * @param {Object} params
  * @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'
+ * @param {number|null} params.nth - Zero-based index to pick one of several matching elements
  */
 (function(params) {
-   const { selector, strategy } = params;
+   const { selector, strategy, nth } = params;
 
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var el = window.__MCP__.resolveRef(selectorOrRef, strategy);
-      if (!el) throw new Error('Element not found: ' + selectorOrRef);
-      return el;
+      var matches = window.__MCP__.resolveAll(selectorOrRef, strategy);
+
+      if (matches.length === 0) throw new Error('Element not found: ' + selectorOrRef);
+      if (typeof nth === 'number') {
+         if (!matches[nth]) {
+            throw new Error('nth=' + nth + ' is out of range, ' + matches.length + ' matches for ' + selectorOrRef);
+         }
+         return matches[nth];
+      }
+      if (matches.length > 1 && strategy === 'text') {
+         throw new Error(describeAmbiguity(selectorOrRef, matches));
+      }
+      return matches[0];
+   }
+
+   function describeAmbiguity(selectorOrRef, matches) {
+      var lines = ['Ambiguous text selector "' + selectorOrRef + '" matched ' + matches.length + ' visible elements. Pass nth, or use a CSS selector or ref.'];
+      for (var i = 0; i < Math.min(matches.length, 5); i++) {
+         var el = matches[i];
+         var rect = el.getBoundingClientRect();
+         var text = (el.textContent || '').trim().substring(0, 50);
+         var tag = el.tagName.toLowerCase();
+         var className = el.className || '';
+         lines.push('  nth=' + i + '  ' + tag + (className ? '.' + className.split(' ')[0] : '') + '  "' + text + '"  rect ' + Math.round(rect.left) + ',' + Math.round(rect.top) + ' ' + Math.round(rect.width) + 'x' + Math.round(rect.height));
+      }
+      if (matches.length > 5) {
+         lines.push('  ... and ' + (matches.length - 5) + ' more');
+      }
+      return lines.join('\n');
    }
 
    const element = resolveElement(selector);

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

@@ -58,14 +58,32 @@ export function buildScreenshotCaptureScript(format, quality) {
     return `
       ${HTML2CANVAS_RESOLVER_SCRIPT}
 
-      // Capture the entire document
+      // Render the document, but crop the output to the visible viewport. Without
+      // explicit bounds html2canvas allocates a canvas for the full scrollable
+      // document, which is both inconsistent with the native implementations and
+      // can time out on long pages.
       const element = document.documentElement;
       if (!element) {
          throw new Error('document.documentElement is null');
       }
 
+      const viewportWidth = Math.max(element.clientWidth, window.innerWidth || 0);
+      const viewportHeight = Math.max(element.clientHeight, window.innerHeight || 0);
+      const viewportX = window.scrollX || window.pageXOffset || 0;
+      const viewportY = window.scrollY || window.pageYOffset || 0;
+
       // Capture the webview
-      const canvas = await html2canvasFn(element, ${HTML2CANVAS_OPTIONS_SCRIPT});
+      const canvas = await html2canvasFn(element, {
+         ...${HTML2CANVAS_OPTIONS_SCRIPT},
+         x: viewportX,
+         y: viewportY,
+         width: viewportWidth,
+         height: viewportHeight,
+         windowWidth: viewportWidth,
+         windowHeight: viewportHeight,
+         scrollX: viewportX,
+         scrollY: viewportY,
+      });
       if (!canvas) {
          throw new Error('html2canvas returned null canvas');
       }

package/dist/driver/scripts/index.d.ts

@@ -8,9 +8,7 @@ export declare const SCRIPTS: {
     readonly resolveRef: string;
     readonly interact: string;
     readonly swipe: string;
-    readonly keyboard: string;
     readonly waitFor: string;
-    readonly getStyles: string;
     readonly focus: string;
     readonly findElement: string;
     readonly domSnapshot: string;
@@ -28,9 +26,9 @@ export declare function getResolveRefSource(): string;
  */
 export declare function buildScript(script: string, params: Record<string, unknown>): string;
 /**
- * Build a script for typing text (uses the keyboard script's typeText function)
+ * Build a script for typing text
  */
-export declare function buildTypeScript(selector: string, text: string, strategy?: string): string;
+export declare function buildTypeScript(selector: string, text: string, strategy?: string, nth?: number | null): string;
 /**
  * Build a script for key events (press, down, up)
  */

package/dist/driver/scripts/index.js

@@ -16,9 +16,7 @@ export const SCRIPTS = {
     resolveRef: loadScript('resolve-ref'),
     interact: loadScript('interact'),
     swipe: loadScript('swipe'),
-    keyboard: loadScript('keyboard'),
     waitFor: loadScript('wait-for'),
-    getStyles: loadScript('get-styles'),
     focus: loadScript('focus'),
     findElement: loadScript('find-element'),
     domSnapshot: loadScript('dom-snapshot'),
@@ -40,21 +38,52 @@ export function buildScript(script, params) {
     return `(${script})(${JSON.stringify(params)})`;
 }
 /**
- * Build a script for typing text (uses the keyboard script's typeText function)
+ * Build a script for typing text
  */
-export function buildTypeScript(selector, text, strategy) {
-    const escapedText = text.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
-    const escapedSelector = selector.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+export function buildTypeScript(selector, text, strategy, nth) {
     const strat = strategy || 'css';
+    const nthValue = nth ?? null;
     return `
       (function() {
-         const selector = '${escapedSelector}';
-         const strategy = '${strat}';
-         const text = '${escapedText}';
+         const selector = ${JSON.stringify(selector)};
+         const strategy = ${JSON.stringify(strat)};
+         const text = ${JSON.stringify(text)};
+         const nth = ${JSON.stringify(nthValue)};
 
-         var element = window.__MCP__.resolveRef(selector, strategy);
-         if (!element) throw new Error('Element not found: ' + selector);
+         function resolveElement(selectorOrRef) {
+            if (!selectorOrRef) return null;
+            var matches = window.__MCP__.resolveAll(selectorOrRef, strategy);
 
+            if (matches.length === 0) throw new Error('Element not found: ' + selectorOrRef);
+            if (typeof nth === 'number') {
+               if (!matches[nth]) {
+                  throw new Error('nth=' + nth + ' is out of range, ' + matches.length + ' matches for ' + selectorOrRef);
+               }
+               return matches[nth];
+            }
+            if (matches.length > 1 && strategy === 'text') {
+               throw new Error(describeAmbiguity(selectorOrRef, matches));
+            }
+            return matches[0];
+         }
+
+         function describeAmbiguity(selectorOrRef, matches) {
+            var lines = ['Ambiguous text selector "' + selectorOrRef + '" matched ' + matches.length + ' visible elements. Pass nth, or use a CSS selector or ref.'];
+            for (var i = 0; i < Math.min(matches.length, 5); i++) {
+               var el = matches[i];
+               var rect = el.getBoundingClientRect();
+               var text = (el.textContent || '').trim().substring(0, 50);
+               var tag = el.tagName.toLowerCase();
+               var className = el.className || '';
+               lines.push('  nth=' + i + '  ' + tag + (className ? '.' + className.split(' ')[0] : '') + '  "' + text + '"  rect ' + Math.round(rect.left) + ',' + Math.round(rect.top) + ' ' + Math.round(rect.width) + 'x' + Math.round(rect.height));
+            }
+            if (matches.length > 5) {
+               lines.push('  ... and ' + (matches.length - 5) + ' more');
+            }
+            return lines.join('\\n');
+         }
+
+         var element = resolveElement(selector);
          element.focus();
 
          // Use native prototype setter to bypass React's value tracker

package/dist/driver/scripts/interact.js

@@ -1,11 +1,12 @@
 /**
- * Webview interaction script - handles click, double-click, long-press, and scroll actions
+ * Webview interaction script - handles click, double-click, long-press, scroll, swipe, hover, and right-click actions
  * This script is injected into the webview and executed with parameters.
  *
  * @param {Object} params
  * @param {string} params.action - The action to perform
  * @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.nth - Zero-based index to pick one of several matching elements
  * @param {number|null} params.x - X coordinate
  * @param {number|null} params.y - Y coordinate
  * @param {number} params.duration - Duration for long-press
@@ -13,13 +14,39 @@
  * @param {number} params.scrollY - Vertical scroll amount
  */
 (function(params) {
-   const { action, selector, strategy, x, y, duration, scrollX, scrollY } = params;
+   const { action, selector, strategy, nth, x, y, duration, scrollX, scrollY } = params;
 
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var el = window.__MCP__.resolveRef(selectorOrRef, strategy);
-      if (!el) throw new Error('Element not found: ' + selectorOrRef);
-      return el;
+      var matches = window.__MCP__.resolveAll(selectorOrRef, strategy);
+
+      if (matches.length === 0) throw new Error('Element not found: ' + selectorOrRef);
+      if (typeof nth === 'number') {
+         if (!matches[nth]) {
+            throw new Error('nth=' + nth + ' is out of range, ' + matches.length + ' matches for ' + selectorOrRef);
+         }
+         return matches[nth];
+      }
+      if (matches.length > 1 && strategy === 'text') {
+         throw new Error(describeAmbiguity(selectorOrRef, matches));
+      }
+      return matches[0];
+   }
+
+   function describeAmbiguity(selectorOrRef, matches) {
+      var lines = ['Ambiguous text selector "' + selectorOrRef + '" matched ' + matches.length + ' visible elements. Pass nth, or use a CSS selector or ref.'];
+      for (var i = 0; i < Math.min(matches.length, 5); i++) {
+         var el = matches[i];
+         var rect = el.getBoundingClientRect();
+         var text = (el.textContent || '').trim().substring(0, 50);
+         var tag = el.tagName.toLowerCase();
+         var className = el.className || '';
+         lines.push('  nth=' + i + '  ' + tag + (className ? '.' + className.split(' ')[0] : '') + '  "' + text + '"  rect ' + Math.round(rect.left) + ',' + Math.round(rect.top) + ' ' + Math.round(rect.width) + 'x' + Math.round(rect.height));
+      }
+      if (matches.length > 5) {
+         lines.push('  ... and ' + (matches.length - 5) + ' more');
+      }
+      return lines.join('\n');
    }
 
    function matchHint() {
@@ -62,6 +89,19 @@
       clientY: targetY,
    };
 
+   const pointerOptions = {
+      ...eventOptions,
+      pointerId: 1,
+      pointerType: 'mouse',
+      isPrimary: true,
+   };
+
+   const rightButtonOptions = {
+      ...eventOptions,
+      button: 2,
+      buttons: 2,
+   };
+
    if (action === 'click') {
       if (element) {
          element.dispatchEvent(new MouseEvent('mousedown', eventOptions));
@@ -94,6 +134,27 @@
       return `Long-pressed at (${targetX}, ${targetY}) for ${duration}ms` + matchHint();
    }
 
+   if (action === 'hover') {
+      if (element) {
+         element.dispatchEvent(new PointerEvent('pointerover', pointerOptions));
+         element.dispatchEvent(new PointerEvent('pointerenter', pointerOptions));
+         element.dispatchEvent(new MouseEvent('mouseover', eventOptions));
+         element.dispatchEvent(new MouseEvent('mouseenter', eventOptions));
+         element.dispatchEvent(new PointerEvent('pointermove', pointerOptions));
+         element.dispatchEvent(new MouseEvent('mousemove', eventOptions));
+      }
+      return `Hovered at (${targetX}, ${targetY})` + matchHint();
+   }
+
+   if (action === 'right-click') {
+      if (element) {
+         element.dispatchEvent(new MouseEvent('mousedown', rightButtonOptions));
+         element.dispatchEvent(new MouseEvent('mouseup', rightButtonOptions));
+         element.dispatchEvent(new MouseEvent('contextmenu', rightButtonOptions));
+      }
+      return `Right-clicked at (${targetX}, ${targetY})` + matchHint();
+   }
+
    if (action === 'scroll') {
       const scrollTarget = element || window;
       if (scrollX !== 0 || scrollY !== 0) {

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

@@ -15,6 +15,84 @@
 
    var REF_PATTERN = /^\[?(?:ref=)?(e\d+)\]?$/;
 
+   var NON_RENDERED_TAGS = {
+      SCRIPT: 1, STYLE: 1, TITLE: 1, HEAD: 1, META: 1,
+      LINK: 1, TEMPLATE: 1, NOSCRIPT: 1, BASE: 1,
+   };
+
+   var INTERACTIVE_SELECTOR = 'a,button,input,select,textarea,summary,' +
+      '[role=button],[role=link],[role=tab],[role=menuitem],[role=option],[tabindex]';
+
+   function isRendered(element) {
+      if (!element || element.nodeType !== 1) return false;
+      if (NON_RENDERED_TAGS[element.tagName]) return false;
+      if (element.hidden) return false;
+      if (element.getClientRects().length === 0) return false;
+      try {
+         var style = window.getComputedStyle(element);
+         if (style.display === 'none') return false;
+         if (style.visibility === 'hidden' || style.visibility === 'collapse') return false;
+      } catch (e) {
+         return false;
+      }
+      return true;
+   }
+
+   function hasMatchingDescendant(element, needle) {
+      var descendants = element.querySelectorAll('*');
+      for (var i = 0; i < descendants.length; i++) {
+         var el = descendants[i];
+         if (!isRendered(el)) continue;
+         var content = (el.textContent || '').trim();
+         if (content.indexOf(needle) !== -1) return true;
+      }
+      return false;
+   }
+
+   function preferInteractive(el) {
+      if (el.matches(INTERACTIVE_SELECTOR)) return el;
+      var host = el.closest(INTERACTIVE_SELECTOR);
+      return host && isRendered(host) ? host : el;
+   }
+
+   function dedupe(arr) {
+      var seen = new Set();
+      var result = [];
+      for (var i = 0; i < arr.length; i++) {
+         var el = arr[i];
+         if (!seen.has(el)) {
+            seen.add(el);
+            result.push(el);
+         }
+      }
+      return result;
+   }
+
+   function textCandidates(needle) {
+      var all = document.body ? document.body.querySelectorAll('*') : [],
+          exact = [], partial = [];
+
+      for (var i = 0; i < all.length; i++) {
+         var el = all[i],
+             content = (el.textContent || '').trim(),
+             attributeText = [
+                el.getAttribute('placeholder'),
+                el.getAttribute('aria-label'),
+                el.getAttribute('title'),
+             ].filter(Boolean),
+             exactAttribute = attributeText.indexOf(needle) !== -1,
+             partialAttribute = attributeText.some(function(value) { return value.indexOf(needle) !== -1; }),
+             textMatch = content.indexOf(needle) !== -1;
+
+         if (!textMatch && !partialAttribute) continue;
+         if (!isRendered(el)) continue;
+         if (textMatch && el.querySelector('*') && hasMatchingDescendant(el, needle)) continue;
+         (content === needle || exactAttribute ? exact : partial).push(preferInteractive(el));
+      }
+
+      return dedupe(exact.length > 0 ? exact : partial);
+   }
+
    function xpathForText(text) {
       // Escape single quotes for XPath by splitting on ' and using concat()
       if (text.indexOf("'") === -1) {
@@ -47,39 +125,26 @@
       }
 
       if (strategy === 'text') {
-         // First try: match element text content
-         var xpath = xpathForText(selectorOrRef);
-         var result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
-         if (result.singleNodeValue) return result.singleNodeValue;
-
-         // Fallback: search placeholder, aria-label, and title attributes
-         var attrSelectors = [
-            '[placeholder*="' + selectorOrRef.replace(/"/g, '\\"') + '"]',
-            '[aria-label*="' + selectorOrRef.replace(/"/g, '\\"') + '"]',
-            '[title*="' + selectorOrRef.replace(/"/g, '\\"') + '"]',
-         ];
-         for (var i = 0; i < attrSelectors.length; i++) {
-            var el = document.querySelector(attrSelectors[i]);
-            if (el) return el;
-         }
-         return null;
+         var candidates = textCandidates(selectorOrRef);
+         return candidates[0] || null;
       }
 
       if (strategy === 'xpath') {
          var result = document.evaluate(selectorOrRef, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
-         return result.singleNodeValue;
+         var node = result.singleNodeValue;
+         return (node && isRendered(node)) ? node : null;
       }
 
       // 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[]}
-    */
+/**
+     * 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 [];
 
@@ -91,33 +156,15 @@
       }
 
       if (strategy === 'text') {
-         // First try: match element text content
-         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));
-         }
-         if (results.length > 0) return results;
-
-         // Fallback: search placeholder, aria-label, and title attributes
-         var attrSelectors = [
-            '[placeholder*="' + selector.replace(/"/g, '\\"') + '"]',
-            '[aria-label*="' + selector.replace(/"/g, '\\"') + '"]',
-            '[title*="' + selector.replace(/"/g, '\\"') + '"]',
-         ];
-         for (var i = 0; i < attrSelectors.length; i++) {
-            var found = Array.from(document.querySelectorAll(attrSelectors[i]));
-            if (found.length > 0) return results.concat(found);
-         }
-         return results;
+         return textCandidates(selector);
       }
 
       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));
+            var node = snapshot.snapshotItem(i);
+            if (node && isRendered(node)) results.push(node);
          }
          return results;
       }
@@ -126,13 +173,17 @@
       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}
-    */
+/**
+     * 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;
    };
+
+   // Export for reuse by other scripts
+   window.__MCP__.isRendered = isRendered;
+   window.__MCP__.INTERACTIVE_SELECTOR = INTERACTIVE_SELECTOR;
 })();

package/dist/driver/session-manager.d.ts

@@ -41,6 +41,7 @@ export interface SessionInfo {
     port: number;
     client: PluginClient;
     connected: boolean;
+    pluginVersion: string | null;
 }
 /**
  * Check if any session is currently active.

package/dist/driver/session-manager.js

@@ -4,6 +4,7 @@ import { AppDiscovery } from './app-discovery.js';
 import { PluginClient } from './plugin-client.js';
 import { resetInitialization } from './webview-executor.js';
 import { createMcpLogger } from '../logger.js';
+import { PLUGIN_VERSION_FULL, describeVersionSkew } from '../version.js';
 const sessionLogger = createMcpLogger('SESSION');
 /**
  * Session Manager - Native IPC-based session management
@@ -211,6 +212,30 @@ function promoteNextDefault() {
         defaultPort = null;
     }
 }
+/**
+ * Return whether a cached session is responsive, removing it when stale.
+ */
+async function keepResponsiveSession(port) {
+    const session = activeSessions.get(port);
+    if (!session) {
+        return false;
+    }
+    try {
+        if (await session.client.checkConnection()) {
+            return true;
+        }
+    }
+    catch {
+        // Treat probe errors like missed pongs and replace the stale client below.
+    }
+    session.client.disconnect();
+    activeSessions.delete(port);
+    if (port === defaultPort) {
+        promoteNextDefault();
+    }
+    sessionLogger.info(`Removed stale session: ${session.name} (${session.host}:${session.port})`);
+    return false;
+}
 async function handleStatusAction() {
     if (activeSessions.size === 0) {
         return JSON.stringify({
@@ -219,6 +244,9 @@ async function handleStatusAction() {
             identifier: null,
             host: null,
             port: null,
+            pluginVersion: null,
+            serverVersion: PLUGIN_VERSION_FULL,
+            versionWarning: describeVersionSkew(null),
         });
     }
     if (activeSessions.size === 1) {
@@ -230,8 +258,12 @@ async function handleStatusAction() {
                 identifier: null,
                 host: null,
                 port: null,
+                pluginVersion: null,
+                serverVersion: PLUGIN_VERSION_FULL,
+                versionWarning: describeVersionSkew(null),
             });
         }
+        const versionWarning = describeVersionSkew(session.pluginVersion);
         return JSON.stringify({
             connected: true,
             app: session.name,
@@ -239,15 +271,22 @@ async function handleStatusAction() {
             cwd: session.cwd,
             host: session.host,
             port: session.port,
+            pluginVersion: session.pluginVersion,
+            serverVersion: PLUGIN_VERSION_FULL,
+            versionWarning,
         });
     }
     const apps = Array.from(activeSessions.values()).map((session) => {
+        const versionWarning = describeVersionSkew(session.pluginVersion);
         return {
             name: session.name,
             identifier: session.identifier,
             cwd: session.cwd,
             host: session.host,
             port: session.port,
+            pluginVersion: session.pluginVersion,
+            serverVersion: PLUGIN_VERSION_FULL,
+            versionWarning,
             isDefault: session.port === defaultPort,
         };
     });
@@ -256,12 +295,13 @@ async function handleStatusAction() {
         apps,
         totalCount: apps.length,
         defaultPort,
+        serverVersion: PLUGIN_VERSION_FULL,
     });
 }
 async function handleStartAction(host, port) {
     const configuredHost = host ?? getDefaultHost();
     const configuredPort = port ?? getDefaultPort();
-    if (activeSessions.has(configuredPort)) {
+    if (await keepResponsiveSession(configuredPort)) {
         return `Already connected to app on port ${configuredPort}`;
     }
     let connectedSession = null;
@@ -296,12 +336,12 @@ async function handleStartAction(host, port) {
     if (!connectedSession) {
         return `Session start failed - no Tauri app found at localhost or ${configuredHost}:${configuredPort}`;
     }
-    if (activeSessions.has(connectedSession.port)) {
+    if (await keepResponsiveSession(connectedSession.port)) {
         return `Already connected to app on port ${connectedSession.port}`;
     }
     const client = new PluginClient(connectedSession.host, connectedSession.port);
     await client.connect();
-    const { identifier, cwd } = await fetchAppMetadata(client);
+    const { identifier, cwd, pluginVersion } = await fetchAppMetadata(client);
     const sessionInfo = {
         name: connectedSession.name,
         identifier,
@@ -310,11 +350,17 @@ async function handleStartAction(host, port) {
         port: connectedSession.port,
         client,
         connected: true,
+        pluginVersion,
     };
     activeSessions.set(connectedSession.port, sessionInfo);
     defaultPort = connectedSession.port;
     sessionLogger.info(`Session started: ${sessionInfo.name} (${sessionInfo.host}:${sessionInfo.port}) [DEFAULT]`);
-    return `Session started with app: ${sessionInfo.name} (${sessionInfo.host}:${sessionInfo.port}) [DEFAULT]`;
+    let result = `Session started with app: ${sessionInfo.name} (${sessionInfo.host}:${sessionInfo.port}) [DEFAULT]`;
+    const versionWarning = describeVersionSkew(sessionInfo.pluginVersion);
+    if (versionWarning) {
+        result = `${versionWarning}\n\n${result}`;
+    }
+    return result;
 }
 async function handleStopAction(appIdentifier) {
     if (appIdentifier !== undefined) {
@@ -376,16 +422,17 @@ async function fetchAppMetadata(client) {
             args: { command: 'plugin:mcp-bridge|get_backend_state', args: {} },
         });
         if (!response.success || !response.data) {
-            return { identifier: null, cwd: null };
+            return { identifier: null, cwd: null, pluginVersion: null };
         }
         const state = response.data;
         return {
             identifier: state.app?.identifier ?? null,
             cwd: typeof state.cwd === 'string' && state.cwd.length > 0 ? state.cwd : null,
+            pluginVersion: state.bridge?.pluginVersion ?? null,
         };
     }
     catch {
-        return { identifier: null, cwd: null };
+        return { identifier: null, cwd: null, pluginVersion: null };
     }
 }
 /**