@hypothesi/tauri-mcp-server 0.12.0 → 0.13.0

package/dist/driver/app-discovery.d.ts

@@ -17,6 +17,8 @@ export interface SessionInfo {
     port: number;
     client?: PluginClient;
     connected: boolean;
+    cwd: string | null;
+    pluginVersion: string | null;
 }
 /**
  * Manages discovery and connection to multiple Tauri app instances
@@ -40,8 +42,8 @@ export declare class AppDiscovery {
      */
     discoverApps(): Promise<AppInstance[]>;
     /**
-     * Connects to a specific app on a host and port
-     */
+      * Connects to a specific app on a host and port
+      */
     connectToPort(port: number, appName?: string, host?: string): Promise<SessionInfo>;
     /**
      * Gets the first available app

package/dist/driver/app-discovery.js

@@ -45,8 +45,8 @@ export class AppDiscovery {
         return apps;
     }
     /**
-     * Connects to a specific app on a host and port
-     */
+      * Connects to a specific app on a host and port
+      */
     async connectToPort(port, appName, host) {
         const targetHost = host ?? this._host;
         const sessionId = `${targetHost}_${port}`;
@@ -58,13 +58,33 @@ export class AppDiscovery {
         const client = new PluginClient(targetHost, port);
         try {
             await client.connect();
+            // Get backend state to retrieve app info and plugin version
+            const backendState = await client.sendCommand({
+                command: 'get_backend_state',
+                args: {},
+            });
+            let name = appName || `Tauri App (${targetHost}:${port})`, cwd = null, pluginVersion = null;
+            if (backendState.success && backendState.data) {
+                const data = backendState.data;
+                if (data.app?.name) {
+                    name = data.app.name;
+                }
+                if (data.app?.identifier) {
+                    // Use identifier if name not available
+                    name = data.app.name || data.app.identifier;
+                }
+                cwd = data.cwd ?? null;
+                pluginVersion = data.bridge?.pluginVersion ?? null;
+            }
             const session = {
                 appId: sessionId,
-                name: appName || `Tauri App (${targetHost}:${port})`,
+                name,
                 host: targetHost,
                 port,
                 client,
                 connected: true,
+                cwd,
+                pluginVersion,
             };
             this._activeSessions.set(sessionId, session);
             return session;

package/dist/driver/plugin-client.d.ts

@@ -15,6 +15,12 @@ export interface PluginResponse {
         warning?: string;
     };
 }
+export interface PluginClientOptions {
+    /** How often to ping an idle bridge connection. */
+    readonly heartbeatIntervalMs?: number;
+    /** How long to wait for a heartbeat pong before terminating the socket. */
+    readonly heartbeatTimeoutMs?: number;
+}
 /**
  * Client to communicate with the MCP Bridge plugin's WebSocket server
  */
@@ -26,13 +32,19 @@ export declare class PluginClient extends EventEmitter {
     private _reconnectAttempts;
     private _shouldReconnect;
     private _reconnectDelay;
+    private _reconnectTimer;
+    private _heartbeatTimer;
+    private _heartbeatTimeout;
+    private readonly _heartbeatIntervalMs;
+    private readonly _heartbeatTimeoutMs;
     private _pendingRequests;
     /**
      * Constructor for PluginClient
      * @param host Host address of the WebSocket server
      * @param port Port number of the WebSocket server
+     * @param options Optional connection liveness settings
      */
-    constructor(host: string, port: number);
+    constructor(host: string, port: number, options?: PluginClientOptions);
     /**
      * Creates a PluginClient with default configuration from environment.
      */
@@ -53,6 +65,13 @@ export declare class PluginClient extends EventEmitter {
      * Disconnect from the plugin
      */
     disconnect(): void;
+    /**
+     * Probe the current WebSocket with a ping/pong exchange.
+     *
+     * `readyState === OPEN` is insufficient for half-open TCP connections, so
+     * session reuse calls this before trusting a cached client.
+     */
+    checkConnection(timeoutMs?: number): Promise<boolean>;
     /**
      * Send a command to the plugin and wait for response.
      *
@@ -64,6 +83,9 @@ export declare class PluginClient extends EventEmitter {
      * Check if connected
      */
     isConnected(): boolean;
+    private _clearHeartbeatTimeout;
+    private _stopHeartbeat;
+    private _startHeartbeat;
 }
 /**
  * Gets the existing singleton PluginClient without creating or modifying it.

package/dist/driver/plugin-client.js

@@ -1,6 +1,7 @@
 import WebSocket from 'ws';
 import { EventEmitter } from 'events';
 import { buildWebSocketURL, getDefaultHost, getDefaultPort } from '../config.js';
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000, DEFAULT_HEARTBEAT_TIMEOUT_MS = 10000, DEFAULT_CONNECTION_CHECK_TIMEOUT_MS = 1000;
 /**
  * Client to communicate with the MCP Bridge plugin's WebSocket server
  */
@@ -13,17 +14,25 @@ export class PluginClient extends EventEmitter {
     _reconnectAttempts = 0;
     _shouldReconnect = true; // Keep trying forever until explicitly disconnected
     _reconnectDelay = 1000; // Start with 1s, max 30s
+    _reconnectTimer = null;
+    _heartbeatTimer = null;
+    _heartbeatTimeout = null;
+    _heartbeatIntervalMs;
+    _heartbeatTimeoutMs;
     _pendingRequests = new Map();
     /**
      * Constructor for PluginClient
      * @param host Host address of the WebSocket server
      * @param port Port number of the WebSocket server
+     * @param options Optional connection liveness settings
      */
-    constructor(host, port) {
+    constructor(host, port, options = {}) {
         super();
         this._host = host;
         this._port = port;
         this._url = buildWebSocketURL(host, port);
+        this._heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this._heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
         // CRITICAL: Attach a default error handler to prevent crashes.
         // In Node.js, if an EventEmitter emits 'error' with no listeners, it throws
         // an uncaught exception that crashes the process. This is especially important
@@ -63,9 +72,13 @@ export class PluginClient extends EventEmitter {
             this._ws.on('open', () => {
                 // Connected to MCP Bridge plugin
                 this._reconnectAttempts = 0;
+                this._startHeartbeat();
                 this.emit('connected');
                 resolve();
             });
+            this._ws.on('pong', () => {
+                this._clearHeartbeatTimeout();
+            });
             this._ws.on('message', (data) => {
                 try {
                     const message = JSON.parse(data.toString());
@@ -95,6 +108,7 @@ export class PluginClient extends EventEmitter {
             });
             this._ws.on('close', () => {
                 // Disconnected from MCP Bridge plugin
+                this._stopHeartbeat();
                 this.emit('disconnected');
                 this._ws = null;
                 // Reject all pending requests since the connection is gone
@@ -107,11 +121,16 @@ export class PluginClient extends EventEmitter {
                 if (this._shouldReconnect) {
                     this._reconnectAttempts++;
                     const delay = Math.min(this._reconnectDelay * this._reconnectAttempts, 30000);
-                    setTimeout(() => {
+                    this._reconnectTimer = setTimeout(() => {
+                        this._reconnectTimer = null;
+                        if (!this._shouldReconnect) {
+                            return;
+                        }
                         this.connect().catch(() => {
                             // Reconnection failed - will retry on next close event
                         });
                     }, delay);
+                    this._reconnectTimer.unref();
                 }
             });
         });
@@ -121,11 +140,68 @@ export class PluginClient extends EventEmitter {
      */
     disconnect() {
         this._shouldReconnect = false; // Prevent auto-reconnect
+        this._stopHeartbeat();
+        if (this._reconnectTimer) {
+            clearTimeout(this._reconnectTimer);
+            this._reconnectTimer = null;
+        }
         if (this._ws) {
             this._ws.close();
             this._ws = null;
         }
     }
+    /**
+     * Probe the current WebSocket with a ping/pong exchange.
+     *
+     * `readyState === OPEN` is insufficient for half-open TCP connections, so
+     * session reuse calls this before trusting a cached client.
+     */
+    async checkConnection(timeoutMs = DEFAULT_CONNECTION_CHECK_TIMEOUT_MS) {
+        const socket = this._ws;
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+            return false;
+        }
+        const openSocket = socket;
+        return new Promise((resolve) => {
+            const probeState = {
+                settled: false,
+                timeout: null,
+            };
+            function finish(isAlive) {
+                if (probeState.settled) {
+                    return;
+                }
+                probeState.settled = true;
+                if (probeState.timeout) {
+                    clearTimeout(probeState.timeout);
+                }
+                openSocket.off('pong', handlePong);
+                openSocket.off('close', handleDisconnect);
+                openSocket.off('error', handleDisconnect);
+                resolve(isAlive);
+            }
+            function handlePong() {
+                finish(true);
+            }
+            function handleDisconnect() {
+                finish(false);
+            }
+            probeState.timeout = setTimeout(() => { finish(false); }, timeoutMs);
+            openSocket.once('pong', handlePong);
+            openSocket.once('close', handleDisconnect);
+            openSocket.once('error', handleDisconnect);
+            try {
+                openSocket.ping(undefined, undefined, (error) => {
+                    if (error) {
+                        finish(false);
+                    }
+                });
+            }
+            catch {
+                finish(false);
+            }
+        });
+    }
     /**
      * Send a command to the plugin and wait for response.
      *
@@ -186,6 +262,55 @@ export class PluginClient extends EventEmitter {
     isConnected() {
         return this._ws?.readyState === WebSocket.OPEN;
     }
+    _clearHeartbeatTimeout() {
+        if (this._heartbeatTimeout) {
+            clearTimeout(this._heartbeatTimeout);
+            this._heartbeatTimeout = null;
+        }
+    }
+    _stopHeartbeat() {
+        if (this._heartbeatTimer) {
+            clearInterval(this._heartbeatTimer);
+            this._heartbeatTimer = null;
+        }
+        this._clearHeartbeatTimeout();
+    }
+    _startHeartbeat() {
+        this._stopHeartbeat();
+        this._heartbeatTimer = setInterval(() => {
+            const socket = this._ws;
+            if (!socket || socket.readyState !== WebSocket.OPEN) {
+                return;
+            }
+            // A previous ping is still unanswered. Terminate instead of letting an
+            // OPEN-but-half-dead socket stay in the session cache indefinitely.
+            if (this._heartbeatTimeout) {
+                socket.terminate();
+                return;
+            }
+            this._heartbeatTimeout = setTimeout(() => {
+                this._heartbeatTimeout = null;
+                if (this._ws === socket && socket.readyState === WebSocket.OPEN) {
+                    socket.terminate();
+                }
+            }, this._heartbeatTimeoutMs);
+            this._heartbeatTimeout.unref();
+            try {
+                socket.ping(undefined, undefined, (error) => {
+                    if (error && this._ws === socket && socket.readyState === WebSocket.OPEN) {
+                        socket.terminate();
+                    }
+                });
+            }
+            catch {
+                this._clearHeartbeatTimeout();
+                if (this._ws === socket && socket.readyState === WebSocket.OPEN) {
+                    socket.terminate();
+                }
+            }
+        }, this._heartbeatIntervalMs);
+        this._heartbeatTimer.unref();
+    }
 }
 // Singleton instance
 let pluginClient = null;

package/dist/driver/plugin-commands.d.ts

@@ -2,19 +2,23 @@ import { z } from 'zod';
 export declare const ExecuteIPCCommandSchema: z.ZodObject<{
     command: z.ZodString;
     args: z.ZodOptional<z.ZodUnknown>;
+    windowId: z.ZodOptional<z.ZodString>;
     appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
 }, "strip", z.ZodTypeAny, {
     command: string;
+    windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     args?: unknown;
 }, {
     command: string;
+    windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     args?: unknown;
 }>;
 export declare function executeIPCCommand(options: {
     command: string;
     args?: unknown;
+    windowId?: string;
     appIdentifier?: string | number;
 }): Promise<string>;
 export declare const ManageIPCMonitoringSchema: z.ZodObject<{
@@ -121,21 +125,21 @@ export declare function resizeWindow(options: {
     appIdentifier?: string | number;
 }): Promise<string>;
 export declare const ManageWindowSchema: z.ZodObject<{
-    action: z.ZodEnum<["list", "info", "resize"]>;
+    action: z.ZodEnum<["list", "info", "resize", "focus", "minimize", "maximize"]>;
     windowId: z.ZodOptional<z.ZodString>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
     logical: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
 }, "strip", z.ZodTypeAny, {
-    action: "list" | "info" | "resize";
+    action: "list" | "focus" | "info" | "resize" | "minimize" | "maximize";
     logical: boolean;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     width?: number | undefined;
     height?: number | undefined;
 }, {
-    action: "list" | "info" | "resize";
+    action: "list" | "focus" | "info" | "resize" | "minimize" | "maximize";
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     width?: number | undefined;
@@ -154,7 +158,7 @@ export declare const ManageWindowSchema: z.ZodObject<{
  * @returns JSON string with the result
  */
 export declare function manageWindow(options: {
-    action: 'list' | 'info' | 'resize';
+    action: 'list' | 'info' | 'resize' | 'focus' | 'minimize' | 'maximize';
     windowId?: string;
     width?: number;
     height?: number;

package/dist/driver/plugin-commands.js

@@ -1,24 +1,54 @@
 import { z } from 'zod';
 import { ensureSessionAndConnect, getExistingPluginClient } from './plugin-client.js';
+import { executeInWebview } from './webview-executor.js';
+const BRIDGE_COMMAND_PREFIX = 'plugin:mcp-bridge|';
 export const ExecuteIPCCommandSchema = z.object({
     command: z.string(),
     args: z.unknown().optional(),
+    windowId: z.string().optional().describe('Window label to target (defaults to "main") for app commands'),
     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.'),
 });
+async function invokeBridgeCommand(command, args, appIdentifier) {
+    const client = await ensureSessionAndConnect(appIdentifier);
+    // Send IPC command via WebSocket to the mcp-bridge plugin
+    const response = await client.sendCommand({
+        command: 'invoke_tauri',
+        args: { command, args },
+    });
+    if (!response.success) {
+        return JSON.stringify({ success: false, error: response.error || 'Unknown error' });
+    }
+    return JSON.stringify({ success: true, result: response.data });
+}
+async function invokeAppCommand(command, args, windowId, appIdentifier) {
+    const script = `
+      return (async () => {
+         const internals = window.__TAURI_INTERNALS__;
+
+         if (!internals || typeof internals.invoke !== 'function') {
+            throw new Error('Tauri IPC is not available in this webview');
+         }
+         return await internals.invoke(${JSON.stringify(command)}, ${JSON.stringify(args ?? {})});
+      })();
+   `;
+    const result = await executeInWebview(script, windowId, appIdentifier);
+    const safeParse = (str) => {
+        try {
+            return JSON.parse(str);
+        }
+        catch {
+            return str;
+        }
+    };
+    return JSON.stringify({ success: true, result: safeParse(result) });
+}
 export async function executeIPCCommand(options) {
+    const { command, args = {}, windowId, appIdentifier } = options;
     try {
-        const { command, args = {}, appIdentifier } = options;
-        // Ensure we have an active session and are connected
-        const client = await ensureSessionAndConnect(appIdentifier);
-        // Send IPC command via WebSocket to the mcp-bridge plugin
-        const response = await client.sendCommand({
-            command: 'invoke_tauri',
-            args: { command, args },
-        });
-        if (!response.success) {
-            return JSON.stringify({ success: false, error: response.error || 'Unknown error' });
+        if (command.startsWith(BRIDGE_COMMAND_PREFIX)) {
+            return await invokeBridgeCommand(command, args, appIdentifier);
         }
-        return JSON.stringify({ success: true, result: response.data });
+        return await invokeAppCommand(command, args, windowId, appIdentifier);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -271,17 +301,18 @@ export async function resizeWindow(options) {
     }
 }
 export const ManageWindowSchema = z.object({
-    action: z.enum(['list', 'info', 'resize'])
-        .describe('Action: "list" all windows, get "info" for one window, or "resize" a window'),
-    windowId: z.string().optional()
-        .describe('Window label to target (defaults to "main"). Required for "info", optional for "resize"'),
+    action: z.enum(['list', 'info', 'resize', 'focus', 'minimize', 'maximize']).describe('Action: "list" all windows, get "info" for one window, "resize" a window, ' +
+        '"focus" a window, "minimize" a window, or "maximize" a window'),
+    windowId: z.string().optional().describe('Window label to target (defaults to "main"). Required for "info", ' +
+        'optional for "resize", "focus", "minimize", "maximize"'),
     width: z.number().int().positive().optional()
         .describe('Width in pixels (required for "resize" action)'),
     height: z.number().int().positive().optional()
         .describe('Height in pixels (required for "resize" action)'),
     logical: z.boolean().optional().default(true)
         .describe('Use logical pixels (true, default) or physical pixels (false). Only for "resize"'),
-    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.'),
+    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.'),
 });
 /**
  * Unified window management function.
@@ -323,6 +354,30 @@ export async function manageWindow(options) {
             }
             return resizeWindow({ width, height, windowId, logical, appIdentifier });
         }
+        case 'focus':
+        case 'minimize':
+        case 'maximize': {
+            try {
+                const client = await ensureSessionAndConnect(appIdentifier);
+                const response = await client.sendCommand({
+                    command: 'set_window_state',
+                    args: { action, windowId: windowId ?? 'main' },
+                });
+                if (!response.success) {
+                    // Translate unknown command error to version mismatch message
+                    if (response.error && response.error.includes('Unknown command')) {
+                        throw new Error(`manage_window action "${action}" needs tauri-plugin-mcp-bridge 0.13.0 or newer. ` +
+                            'The connected app is running an older plugin. Update the plugin in Cargo.toml and rebuild the app.');
+                    }
+                    throw new Error(response.error || 'Unknown error');
+                }
+                return JSON.stringify(response.data);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Failed to ${action} window: ${message}`);
+            }
+        }
         default: {
             throw new Error(`Unknown action: ${action}`);
         }

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

@@ -1,26 +1,139 @@
 /**
- * Find an element using various selector strategies
+ * Find elements using various selector strategies and return structured data
  *
  * @param {Object} params
  * @param {string} params.selector - Element selector, ref ID (e.g., "ref=e3"), or text
  * @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} params.limit - Maximum number of matches to return
+ * @param {string[]} params.properties - Computed CSS properties to include
+ * @param {boolean} params.visibleOnly - Return only rendered elements
+ * @param {boolean} params.includeHtml - Include outerHTML for each match
  */
 (function(params) {
-   const { selector, strategy } = params;
-
-   var element = window.__MCP__.resolveRef(selector, strategy);
-
-   if (element) {
-      const outerHTML = element.outerHTML;
-      // Truncate very long HTML to avoid overwhelming output
-      const truncated = outerHTML.length > 5000
-         ? outerHTML.substring(0, 5000) + '...'
-         : outerHTML;
-      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;
+   const { selector, strategy, nth, limit, properties, visibleOnly, includeHtml } = params;
+
+   function getAccessibleName(element) {
+      try {
+         if (window.ariaApi && typeof window.ariaApi.getName === 'function') {
+            return window.ariaApi.getName(element) || null;
+         }
+      } catch (e) {
+         // Ignore aria-api errors
+      }
+      return null;
+   }
+
+   function getAttributes(element) {
+      const attrs = {
+         id: element.id || null,
+         class: element.className || null,
+         role: element.getAttribute('role') || null,
+         'aria-label': element.getAttribute('aria-label') || null,
+         'data-testid': element.getAttribute('data-testid') || null,
+         href: element.getAttribute('href') || null,
+         type: element.getAttribute('type') || null,
+         disabled: element.hasAttribute('disabled') ? '' : null,
+      };
+      // Remove null values
+      const result = {};
+      for (const key in attrs) {
+         if (attrs[key] !== null) {
+            result[key] = attrs[key];
+         }
+      }
+      return result;
+   }
+
+   function getStyles(element) {
+      if (!properties || properties.length === 0) return null;
+      const computed = window.getComputedStyle(element);
+      const result = {};
+      for (let i = 0; i < properties.length; i++) {
+         const prop = properties[i];
+         result[prop] = computed.getPropertyValue(prop);
+      }
+      return result;
+   }
+
+   function isInteractive(element) {
+      return element.matches && element.matches(window.__MCP__.INTERACTIVE_SELECTOR);
+   }
+
+   // Get all candidates first
+   var allMatches = window.__MCP__.resolveAll(selector, strategy);
+
+   // Filter by visibility if requested
+   var matches = visibleOnly
+      ? allMatches.filter(function(el) { return window.__MCP__.isRendered(el); })
+      : allMatches;
+
+   const totalMatches = matches.length;
+
+   // Apply nth if specified
+   if (typeof nth === 'number') {
+      if (!matches[nth]) {
+         return JSON.stringify({
+            selector: selector,
+            strategy: strategy,
+            totalMatches: totalMatches,
+            returned: 0,
+            truncated: false,
+            matches: [],
+            error: 'nth=' + nth + ' is out of range, ' + totalMatches + ' matches for ' + selector
+         });
+      }
+      matches = [matches[nth]];
    }
 
-   return 'Element not found';
+   // Apply limit
+   const truncated = matches.length > limit;
+   if (truncated) {
+      matches = matches.slice(0, limit);
+   }
+
+   const returned = matches.length;
+
+   const results = matches.map(function(element, index) {
+      const rect = element.getBoundingClientRect();
+      const ref = window.__MCP__.reverseRefs && window.__MCP__.reverseRefs.has(element)
+         ? Array.from(window.__MCP__.reverseRefs.entries()).find(([k, v]) => v === element)[0]
+         : null;
+
+      const match = {
+         nth: typeof nth === 'number' ? nth : (index + (typeof nth !== 'number' ? 0 : 0)),
+         ref: ref,
+         tag: element.tagName.toLowerCase(),
+         text: (element.textContent || '').trim(),
+         accessibleName: getAccessibleName(element),
+         attributes: getAttributes(element),
+         rect: {
+            x: Math.round(rect.left),
+            y: Math.round(rect.top),
+            width: Math.round(rect.width),
+            height: Math.round(rect.height),
+         },
+         visible: window.__MCP__.isRendered(element),
+         interactive: isInteractive(element),
+      };
+
+      const styles = getStyles(element);
+      if (styles) match.styles = styles;
+
+      if (includeHtml) {
+         const html = element.outerHTML;
+         match.html = html.length > 2000 ? html.substring(0, 2000) + '…' : html;
+      }
+
+      return match;
+   });
+
+   return JSON.stringify({
+      selector: selector,
+      strategy: strategy,
+      totalMatches: totalMatches,
+      returned: returned,
+      truncated: truncated,
+      matches: results,
+   });
 })