@hypothesi/tauri-mcp-server 0.4.0 → 0.5.1

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-client.js

@@ -174,14 +174,33 @@ export class PluginClient extends EventEmitter {
 }
 // Singleton instance
 let pluginClient = null;
+/**
+ * Gets the existing singleton PluginClient without creating or modifying it.
+ * Use this for status checks where you don't want to affect the current connection.
+ *
+ * @returns The existing PluginClient or null if none exists
+ */
+export function getExistingPluginClient() {
+    return pluginClient;
+}
 /**
  * Gets or creates a singleton PluginClient.
+ *
+ * If host/port are provided and differ from the existing client's configuration,
+ * the existing client is disconnected and a new one is created. This ensures
+ * that session start with a specific port always uses that port.
+ *
  * @param host Optional host override
  * @param port Optional port override
  */
 export function getPluginClient(host, port) {
     const resolvedHost = host ?? getDefaultHost();
     const resolvedPort = port ?? getDefaultPort();
+    // If singleton exists but host/port don't match, reset it
+    if (pluginClient && (pluginClient.host !== resolvedHost || pluginClient.port !== resolvedPort)) {
+        pluginClient.disconnect();
+        pluginClient = null;
+    }
     if (!pluginClient) {
         pluginClient = new PluginClient(resolvedHost, resolvedPort);
     }
@@ -202,6 +221,25 @@ export async function connectPlugin(host, port) {
         await client.connect();
     }
 }
+/**
+ * Ensures a session is active and connects to the plugin using session config.
+ * This should be used by all tools that require a connected Tauri app.
+ *
+ * @throws Error if no session is active
+ */
+export async function ensureSessionAndConnect() {
+    // Import dynamically to avoid circular dependency
+    const { hasActiveSession, getCurrentSession } = await import('./session-manager.js');
+    if (!hasActiveSession()) {
+        throw new Error('No active session. Call tauri_driver_session with action "start" first to connect to a Tauri app.');
+    }
+    const session = getCurrentSession();
+    if (!session) {
+        throw new Error('Session state is inconsistent. Please restart the session.');
+    }
+    await connectPlugin(session.host, session.port);
+    return getPluginClient(session.host, session.port);
+}
 export async function disconnectPlugin() {
     const client = getPluginClient();
     client.disconnect();

package/dist/driver/plugin-commands.js

@@ -1,14 +1,13 @@
 import { z } from 'zod';
-import { getPluginClient, connectPlugin } from './plugin-client.js';
+import { ensureSessionAndConnect, getExistingPluginClient } from './plugin-client.js';
 export const ExecuteIPCCommandSchema = z.object({
     command: z.string(),
     args: z.unknown().optional(),
 });
 export async function executeIPCCommand(command, args = {}) {
     try {
-        // Ensure we're connected to the plugin
-        await connectPlugin();
-        const client = getPluginClient();
+        // Ensure we have an active session and are connected
+        const client = await ensureSessionAndConnect();
         // Send IPC command via WebSocket to the mcp-bridge plugin
         const response = await client.sendCommand({
             command: 'invoke_tauri',
@@ -110,9 +109,50 @@ 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() {
+/**
+ * Get backend state from the connected Tauri app.
+ *
+ * This function can work in two modes:
+ * 1. Normal mode: Requires an active session (for MCP tool calls)
+ * 2. Setup mode: Uses existing connected client (for session setup)
+ *
+ * @param useExistingClient If true, uses the existing connected client without
+ *        session validation. Used during session setup before currentSession is set.
+ */
+export async function getBackendState(useExistingClient = false) {
     try {
+        if (useExistingClient) {
+            // During session setup, use the already-connected client directly
+            const client = getExistingPluginClient();
+            if (!client || !client.isConnected()) {
+                throw new Error('No connected client available');
+            }
+            const response = await client.sendCommand({
+                command: 'invoke_tauri',
+                args: { command: 'plugin:mcp-bridge|get_backend_state', args: {} },
+            });
+            if (!response.success) {
+                throw new Error(response.error || 'Unknown error');
+            }
+            return JSON.stringify(response.data);
+        }
+        // Normal mode: use executeIPCCommand which validates session
         const result = await executeIPCCommand('plugin:mcp-bridge|get_backend_state');
         const parsed = JSON.parse(result);
         if (!parsed.success) {
@@ -134,8 +174,7 @@ export const ListWindowsSchema = z.object({});
  */
 export async function listWindows() {
     try {
-        await connectPlugin();
-        const client = getPluginClient();
+        const client = await ensureSessionAndConnect();
         const response = await client.sendCommand({
             command: 'list_windows',
         });
@@ -154,3 +193,95 @@ 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 {
+        const client = await ensureSessionAndConnect();
+        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 {
+                const client = await ensureSessionAndConnect();
+                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/script-manager.js

@@ -6,7 +6,7 @@
  *
  * @internal This module is for internal use only and is not exposed as MCP tools.
  */
-import { getPluginClient, connectPlugin } from './plugin-client.js';
+import { ensureSessionAndConnect } from './plugin-client.js';
 /**
  * Registers a script to be injected into the webview.
  *
@@ -20,8 +20,7 @@ import { getPluginClient, connectPlugin } from './plugin-client.js';
  * @returns Promise resolving to registration result
  */
 export async function registerScript(id, type, content, windowLabel) {
-    await connectPlugin();
-    const client = getPluginClient();
+    const client = await ensureSessionAndConnect();
     const response = await client.sendCommand({
         command: 'register_script',
         args: { id, type, content, windowLabel },
@@ -39,8 +38,7 @@ export async function registerScript(id, type, content, windowLabel) {
  * @returns Promise resolving to removal result
  */
 export async function removeScript(id, windowLabel) {
-    await connectPlugin();
-    const client = getPluginClient();
+    const client = await ensureSessionAndConnect();
     const response = await client.sendCommand({
         command: 'remove_script',
         args: { id, windowLabel },
@@ -57,8 +55,7 @@ export async function removeScript(id, windowLabel) {
  * @returns Promise resolving to the number of scripts cleared
  */
 export async function clearScripts(windowLabel) {
-    await connectPlugin();
-    const client = getPluginClient();
+    const client = await ensureSessionAndConnect();
     const response = await client.sendCommand({
         command: 'clear_scripts',
         args: { windowLabel },
@@ -74,8 +71,7 @@ export async function clearScripts(windowLabel) {
  * @returns Promise resolving to the list of registered scripts
  */
 export async function getScripts() {
-    await connectPlugin();
-    const client = getPluginClient();
+    const client = await ensureSessionAndConnect();
     const response = await client.sendCommand({
         command: 'get_scripts',
         args: {},

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, getExistingPluginClient, 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,8 +27,21 @@ 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;
+/**
+ * Check if a session is currently active.
+ * @returns true if a session has been started and not stopped
+ */
+export function hasActiveSession() {
+    return currentSession !== null;
+}
+/**
+ * Get the current session info, or null if no session is active.
+ */
+export function getCurrentSession() {
+    return currentSession;
+}
 function getAppDiscovery(host) {
     if (!appDiscovery || appDiscovery.host !== host) {
         appDiscovery = new AppDiscovery(host);
@@ -51,7 +65,29 @@ 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 {
+        // Use existing client - called during session setup before currentSession is set
+        const stateJson = await getBackendState(true);
+        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,18 +95,26 @@ 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
     if (action === 'status') {
-        const client = getPluginClient();
-        if (client.isConnected() && currentSession) {
+        const client = getExistingPluginClient();
+        if (client?.isConnected() && currentSession) {
             return JSON.stringify({
                 connected: true,
                 app: currentSession.name,
+                identifier: currentSession.identifier,
                 host: currentSession.host,
                 port: currentSession.port,
             });
@@ -78,12 +122,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 +139,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 +153,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 +171,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 +186,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/driver/webview-executor.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { getPluginClient, connectPlugin } from './plugin-client.js';
+import { hasActiveSession, getCurrentSession } from './session-manager.js';
 import { createMcpLogger } from '../logger.js';
 import { buildScreenshotScript, buildScreenshotCaptureScript, getHtml2CanvasSource, HTML2CANVAS_SCRIPT_ID, } from './scripts/html2canvas-loader.js';
 import { registerScript, isScriptRegistered } from './script-manager.js';
@@ -22,17 +23,27 @@ const driverLogger = createMcpLogger('DRIVER');
  * This is called automatically by all tool functions.
  *
  * Initialization includes:
- * - Connecting to the plugin WebSocket
+ * - Verifying an active session exists (via tauri_driver_session)
+ * - Connecting to the plugin WebSocket using session config
  * - Console capture is already initialized by bridge.js in the Tauri app
  *
  * This function is idempotent - calling it multiple times is safe.
+ *
+ * @throws Error if no session is active (tauri_driver_session must be called first)
  */
 export async function ensureReady() {
     if (isInitialized) {
         return;
     }
-    // Connect to the plugin
-    await connectPlugin();
+    // Require an active session to prevent connecting to wrong app
+    if (!hasActiveSession()) {
+        throw new Error('No active session. Call tauri_driver_session with action "start" first to connect to a Tauri app.');
+    }
+    // Get session config and connect with explicit host/port
+    const session = getCurrentSession();
+    if (session) {
+        await connectPlugin(session.host, session.port);
+    }
     isInitialized = true;
 }
 /**
@@ -63,7 +74,12 @@ export async function executeInWebviewWithContext(script, windowId) {
     try {
         // Ensure we're fully initialized
         await ensureReady();
-        const client = getPluginClient();
+        // Get session config to use correct host/port
+        const session = getCurrentSession();
+        if (!session) {
+            throw new Error('No active session');
+        }
+        const client = getPluginClient(session.host, session.port);
         // Send script directly - Rust handles wrapping and IPC callbacks.
         // Use 7s timeout (longer than Rust's 5s) so errors return before Node times out.
         const response = await client.sendCommand({

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.1",
   "description": "A Model Context Protocol server for Tauri v2 development",
   "type": "module",
   "bin": {