@hypothesi/tauri-mcp-server 0.4.0 → 0.5.0

package/README.md

@@ -67,7 +67,7 @@ Supported clients: `claude-code`, `cursor`, `windsurf`, `vscode`, `cline`, `roo-
 | `tauri_webview_wait_for` | Wait for elements, text, or events |
 | `tauri_webview_get_styles` | Get computed CSS styles |
 | `tauri_webview_execute_js` | Execute JavaScript in webview |
-| `tauri_list_windows` | List all open webview windows |
+| `tauri_manage_window` | List windows, get info, or resize |
 
 ### IPC & Plugin
 

package/dist/driver/plugin-commands.js

@@ -110,6 +110,21 @@ export async function emitTestEvent(eventName, payload) {
         throw new Error(`Failed to emit event: ${message}`);
     }
 }
+export const GetWindowInfoSchema = z.object({});
+export async function getWindowInfo() {
+    try {
+        const result = await executeIPCCommand('plugin:mcp-bridge|get_window_info');
+        const parsed = JSON.parse(result);
+        if (!parsed.success) {
+            throw new Error(parsed.error || 'Unknown error');
+        }
+        return JSON.stringify(parsed.result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get window info: ${message}`);
+    }
+}
 export const GetBackendStateSchema = z.object({});
 export async function getBackendState() {
     try {
@@ -154,3 +169,97 @@ export async function listWindows() {
         throw new Error(`Failed to list windows: ${message}`);
     }
 }
+export const ResizeWindowSchema = z.object({
+    width: z.number().int().positive().describe('Width in pixels'),
+    height: z.number().int().positive().describe('Height in pixels'),
+    windowId: z.string().optional().describe('Window label to resize (defaults to "main")'),
+    logical: z.boolean().optional().default(true)
+        .describe('Use logical pixels (true, default) or physical pixels (false)'),
+});
+/**
+ * Resizes a window to the specified dimensions.
+ *
+ * @param options - Resize options including width, height, and optional windowId
+ * @returns JSON string with the result of the resize operation
+ */
+export async function resizeWindow(options) {
+    try {
+        await connectPlugin();
+        const client = getPluginClient();
+        const response = await client.sendCommand({
+            command: 'resize_window',
+            args: {
+                width: options.width,
+                height: options.height,
+                windowId: options.windowId,
+                logical: options.logical ?? true,
+            },
+        });
+        if (!response.success) {
+            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 resize window: ${message}`);
+    }
+}
+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"'),
+    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"'),
+});
+/**
+ * Unified window management function.
+ *
+ * Actions:
+ * - `list`: List all open webview windows with their labels, titles, URLs, and state
+ * - `info`: Get detailed info for a window (size, position, title, focus, visibility)
+ * - `resize`: Resize a window to specified dimensions
+ *
+ * @param options - Action and parameters
+ * @returns JSON string with the result
+ */
+export async function manageWindow(options) {
+    const { action, windowId, width, height, logical } = options;
+    switch (action) {
+        case 'list': {
+            return listWindows();
+        }
+        case 'info': {
+            try {
+                await connectPlugin();
+                const client = getPluginClient();
+                const response = await client.sendCommand({
+                    command: 'get_window_info',
+                    args: { windowId },
+                });
+                if (!response.success) {
+                    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 get window info: ${message}`);
+            }
+        }
+        case 'resize': {
+            if (width === undefined || height === undefined) {
+                throw new Error('width and height are required for resize action');
+            }
+            return resizeWindow({ width, height, windowId, logical });
+        }
+        default: {
+            throw new Error(`Unknown action: ${action}`);
+        }
+    }
+}

package/dist/driver/session-manager.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { getDefaultHost, getDefaultPort } from '../config.js';
 import { AppDiscovery } from './app-discovery.js';
-import { resetPluginClient, getPluginClient } from './plugin-client.js';
+import { resetPluginClient, getPluginClient, connectPlugin } from './plugin-client.js';
+import { getBackendState } from './plugin-commands.js';
 import { resetInitialization } from './webview-executor.js';
 /**
  * Session Manager - Native IPC-based session management
@@ -26,7 +27,7 @@ export const ManageDriverSessionSchema = z.object({
 // Module State
 // ============================================================================
 // AppDiscovery instance - recreated when host changes
-// Track current session info
+// Track current session info including app identifier for session reuse
 let appDiscovery = null, currentSession = null;
 function getAppDiscovery(host) {
     if (!appDiscovery || appDiscovery.host !== host) {
@@ -51,7 +52,28 @@ async function tryConnect(host, port) {
     };
 }
 /**
- * Manage session lifecycle (start or stop).
+ * Fetch the app identifier from the backend state.
+ * Must be called after the singleton pluginClient is connected.
+ *
+ * @returns The app identifier (bundle ID) or null if not available. Returns null when:
+ *          - The plugin doesn't support the identifier field (older versions)
+ *          - The backend state request fails
+ *          - The identifier field is missing from the response
+ */
+async function fetchAppIdentifier() {
+    try {
+        const stateJson = await getBackendState();
+        const state = JSON.parse(stateJson);
+        // Return null if identifier is not present (backward compat with older plugins)
+        return state.app?.identifier ?? null;
+    }
+    catch {
+        // Return null on any error (e.g., older plugin version that doesn't support this)
+        return null;
+    }
+}
+/**
+ * Manage session lifecycle (start, stop, or status).
  *
  * Connection strategy for 'start':
  * 1. Try localhost:{port} first (most reliable for simulators/emulators/desktop)
@@ -59,9 +81,16 @@ async function tryConnect(host, port) {
  * 3. If both fail, try auto-discovery on localhost
  * 4. Return error if all attempts fail
  *
- * @param action - 'start' or 'stop'
+ * @param action - 'start', 'stop', or 'status'
  * @param host - Optional host address (defaults to env var or localhost)
  * @param port - Optional port number (defaults to 9223)
+ * @returns For 'start'/'stop': A message string describing the result.
+ *          For 'status': A JSON string with connection details including:
+ *          - `connected`: boolean indicating if connected
+ *          - `app`: app name (or null if not connected)
+ *          - `identifier`: app bundle ID (e.g., "com.example.app"), or null
+ *          - `host`: connected host (or null)
+ *          - `port`: connected port (or null)
  */
 export async function manageDriverSession(action, host, port) {
     // Handle status action
@@ -71,6 +100,7 @@ export async function manageDriverSession(action, host, port) {
             return JSON.stringify({
                 connected: true,
                 app: currentSession.name,
+                identifier: currentSession.identifier,
                 host: currentSession.host,
                 port: currentSession.port,
             });
@@ -78,12 +108,16 @@ export async function manageDriverSession(action, host, port) {
         return JSON.stringify({
             connected: false,
             app: null,
+            identifier: null,
             host: null,
             port: null,
         });
     }
     if (action === 'start') {
-        // Reset any existing plugin client to ensure fresh connection
+        // Reset any existing connections to ensure fresh connection
+        if (appDiscovery) {
+            await appDiscovery.disconnectAll();
+        }
         resetPluginClient();
         const configuredHost = host ?? getDefaultHost();
         const configuredPort = port ?? getDefaultPort();
@@ -91,7 +125,11 @@ export async function manageDriverSession(action, host, port) {
         if (configuredHost !== 'localhost' && configuredHost !== '127.0.0.1') {
             try {
                 const session = await tryConnect('localhost', configuredPort);
-                currentSession = session;
+                // Connect the singleton pluginClient so status checks work
+                await connectPlugin(session.host, session.port);
+                // Fetch app identifier after singleton is connected
+                const identifier = await fetchAppIdentifier();
+                currentSession = { ...session, identifier };
                 return `Session started with app: ${session.name} (localhost:${session.port})`;
             }
             catch {
@@ -101,7 +139,11 @@ export async function manageDriverSession(action, host, port) {
         // Strategy 2: Try the configured/provided host
         try {
             const session = await tryConnect(configuredHost, configuredPort);
-            currentSession = session;
+            // Connect the singleton pluginClient so status checks work
+            await connectPlugin(session.host, session.port);
+            // Fetch app identifier after singleton is connected
+            const identifier = await fetchAppIdentifier();
+            currentSession = { ...session, identifier };
             return `Session started with app: ${session.name} (${session.host}:${session.port})`;
         }
         catch {
@@ -115,7 +157,11 @@ export async function manageDriverSession(action, host, port) {
                 // Reset client again to connect to discovered port
                 resetPluginClient();
                 const session = await tryConnect('localhost', firstApp.port);
-                currentSession = session;
+                // Connect the singleton pluginClient so status checks work
+                await connectPlugin(session.host, session.port);
+                // Fetch app identifier after singleton is connected
+                const identifier = await fetchAppIdentifier();
+                currentSession = { ...session, identifier };
                 return `Session started with app: ${session.name} (localhost:${session.port})`;
             }
             catch {
@@ -126,7 +172,11 @@ export async function manageDriverSession(action, host, port) {
         try {
             resetPluginClient();
             const session = await tryConnect(configuredHost, configuredPort);
-            currentSession = session;
+            // Connect the singleton pluginClient so status checks work
+            await connectPlugin(session.host, session.port);
+            // Fetch app identifier after singleton is connected
+            const identifier = await fetchAppIdentifier();
+            currentSession = { ...session, identifier };
             return `Session started with app: ${session.name} (${session.host}:${session.port})`;
         }
         catch {

package/dist/prompts-registry.js

@@ -24,96 +24,72 @@ Please follow these steps:
 If no errors are found, let me know the app is running cleanly.
 
 If the session fails to start, help me troubleshoot the connection (is the app running? is the MCP bridge plugin installed?).`;
-const SETUP_PROMPT = `Help me set up the MCP Bridge plugin in my Tauri project so I can use these AI development tools.
+const SETUP_PROMPT = `Help me set up or update the MCP Bridge plugin in my Tauri project.
 
-## Prerequisites
+## IMPORTANT: Do Not Act Without Permission
 
-- This is a **Tauri v2** project (check for \`src-tauri/\` directory and \`tauri.conf.json\`)
-- If this is NOT a Tauri project, stop and let the user know this setup only applies to Tauri apps
+**You must NOT make any changes to files without my explicit approval.**
 
-## Setup Steps
+1. First, examine my project to understand its current state
+2. Then, present a clear summary of what changes are needed
+3. Wait for my approval before making ANY modifications
+4. Only proceed with changes after I confirm
 
-### Step 1: Add the Rust Plugin
+## Prerequisites Check
 
-Add the plugin to \`src-tauri/Cargo.toml\` dependencies:
+First, verify this is a Tauri v2 project:
+- Look for \`src-tauri/\` directory and \`tauri.conf.json\`
+- If this is NOT a Tauri project, stop and let me know this setup only applies to Tauri apps
 
+## What to Check
+
+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:
 \`\`\`toml
 [dependencies]
-tauri-plugin-mcp-bridge = "0.2"
+tauri-plugin-mcp-bridge = "0.4"
 \`\`\`
 
-Or run from the \`src-tauri\` directory:
-\`\`\`bash
-cargo add tauri-plugin-mcp-bridge
-\`\`\`
-
-### Step 2: Register the Plugin
-
-In the Tauri app's entry point (usually \`src-tauri/src/lib.rs\` or \`src-tauri/src/main.rs\`), register the plugin.
-
-Find the \`tauri::Builder\` and add the plugin (only in debug builds):
-
+### 2. Plugin Registration
+Check \`src-tauri/src/lib.rs\` or \`src-tauri/src/main.rs\` for plugin registration. It should have:
 \`\`\`rust
-let mut builder = tauri::Builder::default();
-// ... existing plugins ...
-
 #[cfg(debug_assertions)]
 {
     builder = builder.plugin(tauri_plugin_mcp_bridge::init());
 }
-
-builder
-    .run(tauri::generate_context!())
-    .expect("error while running tauri application");
-\`\`\`
-
-### Step 3: Enable Global Tauri (REQUIRED)
-
-In \`src-tauri/tauri.conf.json\`, ensure \`withGlobalTauri\` is enabled:
-
-\`\`\`json
-{
-  "app": {
-    "withGlobalTauri": true
-  }
-}
 \`\`\`
 
+### 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.
 
-### Step 4: Add Plugin Permissions
+### 4. Plugin Permissions
+Check \`src-tauri/capabilities/default.json\` (or similar) for \`"mcp-bridge:default"\` permission.
 
-Add the plugin permission to \`src-tauri/capabilities/default.json\` (create the file if it doesn't exist):
+## Your Response Format
 
-\`\`\`json
-{
-  "$schema": "../gen/schemas/desktop-schema.json",
-  "identifier": "default",
-  "description": "Default capabilities",
-  "windows": ["main"],
-  "permissions": [
-    "mcp-bridge:default"
-  ]
-}
-\`\`\`
+After examining the project, respond with:
 
-If the file already exists, just add \`"mcp-bridge:default"\` to the existing permissions array.
+1. **Current State**: What's already configured correctly
+2. **Changes Needed**: A numbered list of specific changes required
+3. **Ask for Permission**: "May I proceed with these changes?"
 
-## Verification
+Only after I say yes should you make any modifications.
 
-After setup:
-1. Run the Tauri app in development mode (\`cargo tauri dev\` or \`npm run tauri dev\`)
-2. The MCP bridge will start a WebSocket server on port 9223
-3. Use \`tauri_driver_session\` with action "start" to connect
-4. Use \`tauri_driver_session\` with action "status" to verify the connection
+## After Setup
 
-## Notes
+Once changes are approved and made:
+1. Run the Tauri app in development mode (\`cargo tauri dev\`)
+2. Use \`tauri_driver_session\` with action "start" to connect
+3. Use \`tauri_driver_session\` with action "status" to verify
 
-- The plugin only runs in debug builds (\`#[cfg(debug_assertions)]\`) so it won't affect production
-- The WebSocket server binds to \`0.0.0.0\` by default to support mobile device testing
-- For localhost-only access, use \`Builder::new().bind_address("127.0.0.1").build()\` instead of \`init()\`
+## Notes
 
-Please examine the project structure and make the necessary changes to set up the MCP bridge plugin.`;
+- 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()\``;
 /**
  * Complete registry of all available prompts
  */
@@ -139,9 +115,9 @@ export const PROMPTS = [
     },
     {
         name: 'setup',
-        description: 'Set up the MCP Bridge plugin in a Tauri project. ' +
-            'Guides through adding the Rust crate, registering the plugin, enabling withGlobalTauri, ' +
-            'and adding permissions. Use this when starting with a new Tauri project.',
+        description: 'Set up or update the MCP Bridge plugin in a Tauri project. ' +
+            'Examines the project, reports what changes are needed, and asks for permission before ' +
+            'making any modifications. Use for initial setup or to update to the latest version.',
         arguments: [],
         handler: () => {
             return [

package/dist/tools-registry.js

@@ -2,24 +2,118 @@
  * Single source of truth for all MCP tool definitions
  * This file defines all available tools and their metadata
  */
+import { z } from 'zod';
 import { listDevices, ListDevicesSchema } from './manager/mobile.js';
 import { manageDriverSession, ManageDriverSessionSchema, } from './driver/session-manager.js';
 import { readLogs, ReadLogsSchema } from './monitor/logs.js';
-import { executeIPCCommand, manageIPCMonitoring, getIPCEvents, emitTestEvent, getBackendState, listWindows, ExecuteIPCCommandSchema, ManageIPCMonitoringSchema, GetIPCEventsSchema, EmitTestEventSchema, GetBackendStateSchema, ListWindowsSchema, } from './driver/plugin-commands.js';
+import { executeIPCCommand, manageIPCMonitoring, getIPCEvents, emitTestEvent, getBackendState, manageWindow, ExecuteIPCCommandSchema, ManageIPCMonitoringSchema, GetIPCEventsSchema, EmitTestEventSchema, GetBackendStateSchema, ManageWindowSchema, } from './driver/plugin-commands.js';
 import { interact, screenshot, keyboard, waitFor, getStyles, executeJavaScript, findElement, InteractSchema, ScreenshotSchema, KeyboardSchema, WaitForSchema, GetStylesSchema, ExecuteJavaScriptSchema, FindElementSchema, } from './driver/webview-interactions.js';
 /**
  * Tool categories for organization
  */
 export const TOOL_CATEGORIES = {
+    SETUP: 'Setup & Configuration',
     MOBILE_DEVELOPMENT: 'Mobile Development',
     UI_AUTOMATION: 'UI Automation & WebView Interaction',
     IPC_PLUGIN: 'IPC & Plugin Tools (via MCP Bridge)',
 };
+// Setup instructions for the MCP Bridge plugin
+const SETUP_INSTRUCTIONS = `# MCP Bridge Plugin Setup Instructions
+
+Use these instructions to set up or update the MCP Bridge plugin in a Tauri v2 project.
+
+## IMPORTANT: Do Not Act Without Permission
+
+**You must NOT make any changes to files without the user's explicit approval.**
+
+1. First, examine the project to understand its current state
+2. Then, present a clear summary of what changes are needed
+3. Wait for user approval before making ANY modifications
+4. Only proceed with changes after they confirm
+
+## Prerequisites Check
+
+First, verify this is a Tauri v2 project:
+- Look for \`src-tauri/\` directory and \`tauri.conf.json\`
+- If this is NOT a Tauri project, stop and let the user know this setup only applies to Tauri apps
+
+## What to Check
+
+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:
+\`\`\`toml
+[dependencies]
+tauri-plugin-mcp-bridge = "0.4"
+\`\`\`
+
+### 2. Plugin Registration
+Check \`src-tauri/src/lib.rs\` or \`src-tauri/src/main.rs\` for plugin registration. It should have:
+\`\`\`rust
+#[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.
+
+### 4. Plugin Permissions
+Check \`src-tauri/capabilities/default.json\` (or similar) for \`"mcp-bridge:default"\` permission.
+
+## Response Format
+
+After examining the project, respond with:
+
+1. **Current State**: What's already configured correctly
+2. **Changes Needed**: A numbered list of specific changes required
+3. **Ask for Permission**: "May I proceed with these changes?"
+
+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\`)
+2. Use \`tauri_driver_session\` with action "start" to connect
+3. Use \`tauri_driver_session\` with action "status" to verify
+
+## Notes
+
+- 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()\`
+`;
 /**
  * Complete registry of all available tools
  * This is the single source of truth for tool definitions
  */
 export const TOOLS = [
+    // Setup & Configuration Tools
+    {
+        name: 'tauri_get_setup_instructions',
+        description: 'Get instructions for setting up or updating the MCP Bridge plugin in a Tauri project. ' +
+            'Call this tool when: (1) tauri_driver_session fails to connect, (2) you detect the plugin ' +
+            'is not installed or outdated, or (3) the user asks about setup. ' +
+            'Returns step-by-step guidance that you should follow to help the user configure their project. ' +
+            'IMPORTANT: The instructions require you to examine the project first and ask for permission ' +
+            'before making any changes.',
+        category: TOOL_CATEGORIES.SETUP,
+        schema: z.object({}),
+        annotations: {
+            title: 'Get Setup Instructions',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: async () => {
+            return SETUP_INSTRUCTIONS;
+        },
+    },
     // Mobile Development Tools
     {
         name: 'tauri_list_devices',
@@ -42,7 +136,11 @@ export const TOOLS = [
     {
         name: 'tauri_driver_session',
         description: '[Tauri Apps Only] Start/stop automation session to connect to a RUNNING Tauri app. ' +
-            'Use action "status" to check current connection state. ' +
+            'Use action "status" to check current connection state and get the app identifier. ' +
+            'The status response includes an "identifier" field (e.g., "com.example.myapp") that uniquely identifies the connected app. ' +
+            'The identifier may be null if the Tauri app uses an older plugin version that does not provide it. ' +
+            'Before starting a new session, check status first - if already connected to the correct app (matching identifier), ' +
+            'reuse the existing session. If identifier is null, you cannot verify the app identity. ' +
             'REQUIRED before using other tauri_webview_* or tauri_plugin_* tools. ' +
             'Connects via WebSocket to the MCP Bridge plugin in the Tauri app. ' +
             'For browser automation, use Chrome DevTools MCP instead. ' +
@@ -339,20 +437,25 @@ export const TOOLS = [
     },
     // Window Management Tools
     {
-        name: 'tauri_list_windows',
-        description: '[Tauri Apps Only] List all Tauri webview windows with details including ' +
-            'labels, titles, URLs, and state (focused, visible, isMain). ' +
-            'Requires active tauri_driver_session. Use to discover windows before targeting them. ' +
-            'For browser tabs/windows, use Chrome DevTools MCP instead.',
+        name: 'tauri_manage_window',
+        description: '[Tauri Apps Only] Manage Tauri windows. Actions: ' +
+            '"list" - List all windows with labels, titles, URLs, and state. ' +
+            '"info" - Get detailed info for a window (size, position, title, focus, visibility). ' +
+            '"resize" - Resize a window (requires width/height, uses logical pixels by default). ' +
+            'Requires active tauri_driver_session. ' +
+            'For browser windows, use Chrome DevTools MCP instead.',
         category: TOOL_CATEGORIES.UI_AUTOMATION,
-        schema: ListWindowsSchema,
+        schema: ManageWindowSchema,
         annotations: {
-            title: 'List Tauri Windows',
-            readOnlyHint: true,
+            title: 'Manage Tauri Window',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
             openWorldHint: false,
         },
-        handler: async () => {
-            return await listWindows();
+        handler: async (args) => {
+            const parsed = ManageWindowSchema.parse(args);
+            return await manageWindow(parsed);
         },
     },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypothesi/tauri-mcp-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A Model Context Protocol server for Tauri v2 development",
   "type": "module",
   "bin": {