webview_execute_js

Instructions

Implementation Reference

• packages/mcp-server/src/tools-registry.ts:385-412 (registration)

  Registration of the 'webview_execute_js' MCP tool. Defines its name, description, category (UI_AUTOMATION), schema (ExecuteJavaScriptSchema), and inline handler that delegates to executeJavaScript().

  {
     name: 'webview_execute_js',
     description:
        '[Tauri Apps Only] Execute JavaScript in a Tauri app\'s webview context. ' +
        'Requires active driver_session. Has access to window.__TAURI__. ' +
        'If you need a return value, it must be JSON-serializable. ' +
        'For functions that return values, use an IIFE: "(() => { return 5; })()" not "() => { return 5; }". ' +
        MULTI_APP_DESC + ' ' +
        'For browser JS execution, use Chrome DevTools MCP instead.',
     category: TOOL_CATEGORIES.UI_AUTOMATION,
     schema: ExecuteJavaScriptSchema,
     annotations: {
        title: 'Execute JS in Tauri Webview',
        readOnlyHint: false,
        destructiveHint: false,
        openWorldHint: false,
     },
     handler: async (args) => {
        const parsed = ExecuteJavaScriptSchema.parse(args);
  
        return await executeJavaScript({
           script: parsed.script,
           args: parsed.args,
           windowId: parsed.windowId,
           appIdentifier: parsed.appIdentifier,
        });
     },
  },

• packages/mcp-server/src/driver/webview-interactions.ts:105-112 (schema)

  ExecuteJavaScriptSchema: Zod schema for the webview_execute_js tool. Extends WindowTargetSchema with 'script' (required string) and 'args' (optional array of unknown values).

  export const ExecuteJavaScriptSchema = WindowTargetSchema.extend({
     script: z.string().describe(
        'JavaScript code to execute in the webview context. ' +
        'If returning a value, it must be JSON-serializable. ' +
        'For functions that return values, use IIFE syntax: "(() => { return value; })()" not "() => { return value; }"'
     ),
     args: z.array(z.unknown()).optional().describe('Arguments to pass to the script'),
  });

• packages/mcp-server/src/driver/webview-interactions.ts:366-405 (handler)

  executeJavaScript() function: The core handler implementation. Wraps the script with args injection if args are provided, calls executeInWebviewWithContext(), and returns the result with window context info.

  export interface ExecuteJavaScriptOptions {
     script: string;
     args?: unknown[];
     windowId?: string;
     appIdentifier?: string | number;
  }
  
  export async function executeJavaScript(options: ExecuteJavaScriptOptions): Promise<string> {
     const { script, args, windowId, appIdentifier } = options;
  
     // If args are provided, we need to inject them into the script context
     const wrappedScript = args && args.length > 0
        ? `
           (function() {
              const args = ${JSON.stringify(args)};
              return (${script}).apply(null, args);
           })();
        `
        : script;
  
     try {
        const { result, windowLabel, warning } = await executeInWebviewWithContext(wrappedScript, windowId, appIdentifier);
  
        // Build response with window context
        let response = result;
  
        if (warning) {
           response = `⚠️ ${warning}\n\n${response}`;
        }
  
        // Add window info footer for clarity
        response += `\n\n[Executed in window: ${windowLabel}]`;
  
        return response;
     } catch(error: unknown) {
        const message = error instanceof Error ? error.message : String(error);
  
        throw new Error(`JavaScript execution failed: ${message}`);
     }
  }

• packages/mcp-server/src/driver/webview-executor.ts:140-191 (helper)

  executeInWebviewWithContext(): Helper that performs the actual IPC execution. Sends the 'execute_js' command via WebSocket to the Tauri plugin bridge, parses the response, and returns the result with window label and optional warning.

  export async function executeInWebviewWithContext(
     script: string,
     windowId?: string,
     appIdentifier?: string | number
  ): Promise<ExecuteInWebviewResult> {
     try {
        // Ensure we're fully initialized
        await ensureReady(windowId, appIdentifier);
  
        // Resolve target session
        const session = resolveTargetApp(appIdentifier);
  
        const client = session.client;
  
        // 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({
           command: 'execute_js',
           args: { script, windowLabel: windowId },
        }, 7000);
  
        if (!response.success) {
           throw new Error(response.error || 'Unknown execution error');
        }
  
        // Extract window context from response
        const windowContext = response.windowContext;
  
        // Parse and return the result
        const data = response.data;
  
        let result: string;
  
        if (data === null || data === undefined) {
           result = 'null';
        } else if (typeof data === 'string') {
           result = data;
        } else {
           result = JSON.stringify(data);
        }
  
        return {
           result,
           windowLabel: windowContext?.windowLabel || 'main',
           warning: windowContext?.warning,
        };
     } catch(error: unknown) {
        const message = error instanceof Error ? error.message : String(error);
  
        throw new Error(`WebView execution failed: ${message}`);
     }
  }

• packages/mcp-server/src/driver/webview-executor.ts:126-130 (helper)

  executeInWebview(): Simpler wrapper over executeInWebviewWithContext() that returns only the result string.

  export async function executeInWebview(script: string, windowId?: string, appIdentifier?: string | number): Promise<string> {
     const { result } = await executeInWebviewWithContext(script, windowId, appIdentifier);
  
     return result;
  }