send_command_to_electron

Instructions

Implementation Reference

• src/handlers.ts:111-153 (handler)

  MCP tool handler for send_command_to_electron: validates input schema, performs security checks via securityManager, and calls the sendCommandToElectron utility if approved.

  case ToolName.SEND_COMMAND_TO_ELECTRON: {
    const { command, args: commandArgs } = SendCommandToElectronSchema.parse(args);
  
    // Execute command through security manager
    const securityResult = await securityManager.executeSecurely({
      command,
      args: commandArgs,
      sourceIP,
      userAgent,
      operationType: 'command',
    });
  
    if (securityResult.blocked) {
      return {
        content: [
          {
            type: 'text',
            text: `Command blocked: ${securityResult.error}\nRisk Level: ${securityResult.riskLevel}`,
          },
        ],
        isError: true,
      };
    }
  
    if (!securityResult.success) {
      return {
        content: [
          {
            type: 'text',
            text: `Command failed: ${securityResult.error}`,
          },
        ],
        isError: true,
      };
    }
  
    // Execute the actual command if security checks pass
    const result = await sendCommandToElectron(command, commandArgs);
    return {
      content: [{ type: 'text', text: result }],
      isError: false,
    };
  }

• src/schemas.ts:34-39 (schema)

  Zod input schema defining 'command' (string) and optional 'args' (CommandArgsSchema) for the tool.

  export const SendCommandToElectronSchema = z.object({
    command: z.string().describe('Command to send to the Electron process'),
    args: CommandArgsSchema.optional().describe(
      'Arguments for the command - must be an object with appropriate properties based on the command type',
    ),
  });

• src/tools.ts:32-62 (registration)

  Tool registration object defining name, detailed description of commands, and input schema conversion for MCP tools array.

    {
      name: ToolName.SEND_COMMAND_TO_ELECTRON,
      description: `Send JavaScript commands to any running Electron application via Chrome DevTools Protocol. 
  
  Enhanced UI interaction commands:
  - 'find_elements': Analyze all interactive elements (buttons, inputs, selects) with their properties
  - 'click_by_text': Click elements by their visible text, aria-label, or title
  - 'click_by_selector': Securely click elements by CSS selector
  - 'fill_input': Fill input fields by selector, placeholder text, or associated label
  - 'select_option': Select dropdown options by value or text
  - 'send_keyboard_shortcut': Send keyboard shortcuts like 'Ctrl+N', 'Meta+N', 'Enter', 'Escape'
  - 'navigate_to_hash': Safely navigate to hash routes (e.g., '#create', '#settings')
  - 'get_page_structure': Get organized overview of page elements (buttons, inputs, selects, links)
  - 'debug_elements': Get debugging info about buttons and form elements on the page
  - 'verify_form_state': Check current form state and validation status
  - 'get_title', 'get_url', 'get_body_text': Basic page information
  - 'eval': Execute custom JavaScript code with enhanced error reporting
  
  IMPORTANT: Arguments must be passed as an object with the correct properties:
  
  Examples:
  - click_by_selector: {"selector": "button.submit-btn"}
  - click_by_text: {"text": "Submit"}
  - fill_input: {"placeholder": "Enter name", "value": "John Doe"}
  - fill_input: {"selector": "#email", "value": "user@example.com"}
  - send_keyboard_shortcut: {"text": "Enter"}
  - eval: {"code": "document.title"}
  
  Use 'get_page_structure' or 'debug_elements' first to understand available elements, then use specific interaction commands.`,
      inputSchema: zodToJsonSchema(SendCommandToElectronSchema) as ToolInput,
    },

• src/utils/electron-enhanced-commands.ts:21-481 (helper)

  Core implementation utility: maps command strings to generated JavaScript code, executes via Chrome DevTools Protocol on Electron target, handles numerous enhanced UI commands with security measures, and processes/returns results.

  export async function sendCommandToElectron(command: string, args?: CommandArgs): Promise<string> {
    try {
      const target = await findElectronTarget();
      let javascriptCode: string;
  
      switch (command.toLowerCase()) {
        case 'get_title':
          javascriptCode = 'document.title';
          break;
  
        case 'get_url':
          javascriptCode = 'window.location.href';
          break;
  
        case 'get_body_text':
          javascriptCode = 'document.body.innerText.substring(0, 500)';
          break;
  
        case 'click_button':
          // Validate and escape selector input
          const selector = args?.selector || 'button';
          if (selector.includes('javascript:') || selector.includes('<script')) {
            return 'Invalid selector: contains dangerous content';
          }
          const escapedSelector = JSON.stringify(selector);
  
          javascriptCode = `
            const button = document.querySelector(${escapedSelector});
            if (button && !button.disabled) {
              // Enhanced duplicate prevention
              const buttonId = button.id || button.className || 'button';
              const clickKey = 'mcp_click_' + btoa(buttonId).slice(0, 10);
              
              // Check if this button was recently clicked
              if (window[clickKey] && Date.now() - window[clickKey] < 2000) {
                return 'Button click prevented - too soon after previous click';
              }
              
              // Mark this button as clicked
              window[clickKey] = Date.now();
              
              // Prevent multiple rapid events
              button.style.pointerEvents = 'none';
              
              // Trigger React events properly
              button.focus();
              
              // Use both React synthetic events and native events
              const clickEvent = new MouseEvent('click', {
                bubbles: true,
                cancelable: true,
                view: window
              });
              
              button.dispatchEvent(clickEvent);
              
              // Re-enable after delay
              setTimeout(() => {
                button.style.pointerEvents = '';
              }, 1000);
              
              return 'Button clicked with enhanced protection';
            }
            return 'Button not found or disabled';
          `;
          break;
  
        case 'find_elements':
          javascriptCode = generateFindElementsCommand();
          break;
  
        case 'click_by_text':
          const clickText = args?.text || '';
          if (!clickText) {
            return 'ERROR: Missing text. Use: {"text": "button text"}. See MCP_USAGE_GUIDE.md for examples.';
          }
          javascriptCode = generateClickByTextCommand(clickText);
          break;
  
        case 'click_by_selector':
          // Secure selector-based clicking
          const clickSelector = args?.selector || '';
  
          // Better error message for common mistake
          if (!clickSelector) {
            return 'ERROR: Missing selector. Use: {"selector": "your-css-selector"}. See MCP_USAGE_GUIDE.md for examples.';
          }
  
          if (clickSelector.includes('javascript:') || clickSelector.includes('<script')) {
            return 'Invalid selector: contains dangerous content';
          }
          const escapedClickSelector = JSON.stringify(clickSelector);
  
          javascriptCode = `
            (function() {
              try {
                const element = document.querySelector(${escapedClickSelector});
                if (element) {
                  // Check if element is clickable
                  const rect = element.getBoundingClientRect();
                  if (rect.width === 0 || rect.height === 0) {
                    return 'Element not visible';
                  }
                  
                  // Prevent rapid clicks
                  const clickKey = 'mcp_selector_click_' + btoa(${escapedClickSelector}).slice(0, 10);
                  if (window[clickKey] && Date.now() - window[clickKey] < 1000) {
                    return 'Click prevented - too soon after previous click';
                  }
                  window[clickKey] = Date.now();
                  
                  // Focus and click
                  element.focus();
                  const event = new MouseEvent('click', {
                    bubbles: true,
                    cancelable: true,
                    view: window
                  });
                  element.dispatchEvent(event);
                  
                  return 'Successfully clicked element: ' + element.tagName + 
                         (element.textContent ? ' - "' + element.textContent.substring(0, 50) + '"' : '');
                }
                return 'Element not found: ' + ${escapedClickSelector};
              } catch (e) {
                return 'Error clicking element: ' + e.message;
              }
            })();
          `;
          break;
  
        case 'send_keyboard_shortcut':
          // Secure keyboard shortcut sending
          const key = args?.text || '';
          const validKeys = [
            'Enter',
            'Escape',
            'Tab',
            'Space',
            'ArrowUp',
            'ArrowDown',
            'ArrowLeft',
            'ArrowRight',
          ];
  
          // Parse shortcut like "Ctrl+N" or "Meta+N"
          const parts = key.split('+').map((p) => p.trim());
          const keyPart = parts[parts.length - 1];
          const modifiers = parts.slice(0, -1);
  
          // Helper function to get proper KeyboardEvent.code value
          function getKeyCode(key: string): string {
            // Special keys mapping
            const specialKeys: Record<string, string> = {
              Enter: 'Enter',
              Escape: 'Escape',
              Tab: 'Tab',
              Space: 'Space',
              ArrowUp: 'ArrowUp',
              ArrowDown: 'ArrowDown',
              ArrowLeft: 'ArrowLeft',
              ArrowRight: 'ArrowRight',
              Backspace: 'Backspace',
              Delete: 'Delete',
              Home: 'Home',
              End: 'End',
              PageUp: 'PageUp',
              PageDown: 'PageDown',
            };
  
            if (specialKeys[key]) {
              return specialKeys[key];
            }
  
            // Single character keys
            if (key.length === 1) {
              const upperKey = key.toUpperCase();
              if (upperKey >= 'A' && upperKey <= 'Z') {
                return `Key${upperKey}`;
              }
              if (upperKey >= '0' && upperKey <= '9') {
                return `Digit${upperKey}`;
              }
            }
  
            return `Key${key.toUpperCase()}`;
          }
  
          if (keyPart.length === 1 || validKeys.includes(keyPart)) {
            const modifierProps = modifiers
              .map((mod) => {
                switch (mod.toLowerCase()) {
                  case 'ctrl':
                    return 'ctrlKey: true';
                  case 'shift':
                    return 'shiftKey: true';
                  case 'alt':
                    return 'altKey: true';
                  case 'meta':
                  case 'cmd':
                    return 'metaKey: true';
                  default:
                    return '';
                }
              })
              .filter(Boolean)
              .join(', ');
  
            javascriptCode = `
              (function() {
                try {
                  const event = new KeyboardEvent('keydown', {
                    key: '${keyPart}',
                    code: '${getKeyCode(keyPart)}',
                    ${modifierProps},
                    bubbles: true,
                    cancelable: true
                  });
                  document.dispatchEvent(event);
                  return 'Keyboard shortcut sent: ${key}';
                } catch (e) {
                  return 'Error sending shortcut: ' + e.message;
                }
              })();
            `;
          } else {
            return `Invalid keyboard shortcut: ${key}`;
          }
          break;
  
        case 'navigate_to_hash':
          // Secure hash navigation
          const hash = args?.text || '';
          if (hash.includes('javascript:') || hash.includes('<script') || hash.includes('://')) {
            return 'Invalid hash: contains dangerous content';
          }
          const cleanHash = hash.startsWith('#') ? hash : '#' + hash;
  
          javascriptCode = `
            (function() {
              try {
                // Use pushState for safer navigation
                if (window.history && window.history.pushState) {
                  const newUrl = window.location.pathname + window.location.search + '${cleanHash}';
                  window.history.pushState({}, '', newUrl);
                  
                  // Trigger hashchange event for React Router
                  window.dispatchEvent(new HashChangeEvent('hashchange', {
                    newURL: window.location.href,
                    oldURL: window.location.href.replace('${cleanHash}', '')
                  }));
                  
                  return 'Navigated to hash: ${cleanHash}';
                } else {
                  // Fallback to direct assignment
                  window.location.hash = '${cleanHash}';
                  return 'Navigated to hash (fallback): ${cleanHash}';
                }
              } catch (e) {
                return 'Error navigating: ' + e.message;
              }
            })();
          `;
          break;
  
        case 'fill_input':
          const inputValue = args?.value || args?.text || '';
          if (!inputValue) {
            return 'ERROR: Missing value. Use: {"value": "text", "selector": "..."} or {"value": "text", "placeholder": "..."}. See MCP_USAGE_GUIDE.md for examples.';
          }
          javascriptCode = generateFillInputCommand(
            args?.selector || '',
            inputValue,
            args?.text || args?.placeholder || '',
          );
          break;
  
        case 'select_option':
          javascriptCode = generateSelectOptionCommand(
            args?.selector || '',
            args?.value || '',
            args?.text || '',
          );
          break;
  
        case 'get_page_structure':
          javascriptCode = generatePageStructureCommand();
          break;
  
        case 'debug_elements':
          javascriptCode = `
            (function() {
              const buttons = Array.from(document.querySelectorAll('button')).map(btn => ({
                text: btn.textContent?.trim(),
                id: btn.id,
                className: btn.className,
                disabled: btn.disabled,
                visible: btn.getBoundingClientRect().width > 0,
                type: btn.type || 'button'
              }));
              
              const inputs = Array.from(document.querySelectorAll('input, textarea, select')).map(inp => ({
                name: inp.name,
                placeholder: inp.placeholder,
                type: inp.type,
                id: inp.id,
                value: inp.value,
                visible: inp.getBoundingClientRect().width > 0,
                enabled: !inp.disabled
              }));
              
              return JSON.stringify({
                buttons: buttons.filter(b => b.visible).slice(0, 10),
                inputs: inputs.filter(i => i.visible).slice(0, 10),
                url: window.location.href,
                title: document.title
              }, null, 2);
            })()
          `;
          break;
  
        case 'verify_form_state':
          javascriptCode = `
            (function() {
              const forms = Array.from(document.querySelectorAll('form')).map(form => {
                const inputs = Array.from(form.querySelectorAll('input, textarea, select')).map(inp => ({
                  name: inp.name,
                  type: inp.type,
                  value: inp.value,
                  placeholder: inp.placeholder,
                  required: inp.required,
                  valid: inp.validity?.valid
                }));
                
                return {
                  id: form.id,
                  action: form.action,
                  method: form.method,
                  inputs: inputs,
                  isValid: form.checkValidity?.() || 'unknown'
                };
              });
              
              return JSON.stringify({ forms, formCount: forms.length }, null, 2);
            })()
          `;
          break;
  
        case 'console_log':
          javascriptCode = `console.log('MCP Command:', '${
            args?.message || 'Hello from MCP!'
          }'); 'Console message sent'`;
          break;
  
        case 'eval':
          const rawCode = typeof args === 'string' ? args : args?.code || command;
          // Enhanced eval with better error handling and result reporting
          const codeHash = Buffer.from(rawCode).toString('base64').slice(0, 10);
          const isStateTest =
            rawCode.includes('window.testState') ||
            rawCode.includes('persistent-test-value') ||
            rawCode.includes('window.testValue');
  
          javascriptCode = `
            (function() {
              try {
                // Prevent rapid execution of the same code unless it's a state test
                const codeHash = '${codeHash}';
                const isStateTest = ${isStateTest};
                const rawCode = ${JSON.stringify(rawCode)};
                
                if (!isStateTest && window._mcpExecuting && window._mcpExecuting[codeHash]) {
                  return { success: false, error: 'Code already executing', result: null };
                }
                
                window._mcpExecuting = window._mcpExecuting || {};
                if (!isStateTest) {
                  window._mcpExecuting[codeHash] = true;
                }
                
                let result;
                ${
                  rawCode.trim().startsWith('() =>') || rawCode.trim().startsWith('function')
                    ? `result = (${rawCode})();`
                    : rawCode.includes('return')
                      ? `result = (function() { ${rawCode} })();`
                      : rawCode.includes(';')
                        ? `result = (function() { ${rawCode}; return "executed"; })();`
                        : `result = (function() { return (${rawCode}); })();`
                }
                
                setTimeout(() => {
                  if (!isStateTest && window._mcpExecuting) {
                    delete window._mcpExecuting[codeHash];
                  }
                }, 1000);
                
                // Enhanced result reporting
                // For simple expressions, undefined might be a valid result for some cases
                if (result === undefined && !rawCode.includes('window.') && !rawCode.includes('document.') && !rawCode.includes('||')) {
                  return { success: false, error: 'Command returned undefined - element may not exist or action failed', result: null };
                }
                if (result === null) {
                  return { success: false, error: 'Command returned null - element may not exist', result: null };
                }
                if (result === false && rawCode.includes('click') || rawCode.includes('querySelector')) {
                  return { success: false, error: 'Command returned false - action likely failed', result: false };
                }
                
                return { success: true, error: null, result: result };
              } catch (error) {
                return { 
                  success: false, 
                  error: 'JavaScript error: ' + error.message,
                  stack: error.stack,
                  result: null 
                };
              }
            })()
          `;
          break;
  
        default:
          javascriptCode = command;
      }
  
      const rawResult = await executeInElectron(javascriptCode, target);
  
      // Try to parse structured response from enhanced eval
      if (command.toLowerCase() === 'eval') {
        try {
          const parsedResult = JSON.parse(rawResult);
          if (parsedResult && typeof parsedResult === 'object' && 'success' in parsedResult) {
            if (!parsedResult.success) {
              return `❌ Command failed: ${parsedResult.error}${
                parsedResult.stack ? '\nStack: ' + parsedResult.stack : ''
              }`;
            }
            return `✅ Command successful${
              parsedResult.result !== null ? ': ' + JSON.stringify(parsedResult.result) : ''
            }`;
          }
        } catch {
          // If it's not JSON, treat as regular result
        }
      }
  
      // Handle regular results
      if (rawResult === 'undefined' || rawResult === 'null' || rawResult === '') {
        return `⚠️ Command executed but returned ${
          rawResult || 'empty'
        } - this may indicate the element wasn't found or the action failed`;
      }
  
      return `✅ Result: ${rawResult}`;
    } catch (error) {
      throw new Error(
        `Failed to send command: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }