MCP_USAGE_GUIDE.md

MCP Usage Examples for Electron MCP Server

This document provides comprehensive examples of how to properly use the Electron MCP Server tools.

🎯 Common Patterns

Getting Started - Page Inspection

Always start by understanding the page structure:

{
  "command": "get_page_structure"
}

This returns all interactive elements with their properties, helping you choose the right targeting method.

Button Interactions

Method 1: Click by Visible Text (Recommended)

{
  "command": "click_by_text",
  "args": {
    "text": "Create New Encyclopedia"
  }
}

Method 2: Click by CSS Selector

{
  "command": "click_by_selector",
  "args": {
    "selector": "button[class*='bg-blue-500']"
  }
}

Form Interactions

Fill Input by Placeholder

{
  "command": "fill_input",
  "args": {
    "placeholder": "Enter encyclopedia name",
    "value": "AI and Machine Learning"
  }
}

Fill Input by CSS Selector

{
  "command": "fill_input",
  "args": {
    "selector": "#email",
    "value": "user@example.com"
  }
}

Keyboard Shortcuts

{
  "command": "send_keyboard_shortcut",
  "args": {
    "text": "Ctrl+N"
  }
}

Custom JavaScript

{
  "command": "eval",
  "args": {
    "code": "document.querySelectorAll('button').length"
  }
}

🚨 Common Mistakes and Fixes

❌ Mistake 1: Wrong Argument Structure

// WRONG - causes "selector is empty" error
{
  "command": "click_by_selector",
  "args": "button.submit"
}

// CORRECT
{
  "command": "click_by_selector",
  "args": {
    "selector": "button.submit"
  }
}

❌ Mistake 2: Using Complex Selectors Incorrectly

// WRONG - invalid CSS syntax
{
  "command": "click_by_selector",
  "args": {
    "selector": "button:has-text('Create')"
  }
}

// CORRECT - use click_by_text instead
{
  "command": "click_by_text",
  "args": {
    "text": "Create"
  }
}

❌ Mistake 3: Not Handling React/Dynamic Content

// BETTER - wait and retry pattern
{
  "command": "get_page_structure"
}
// Check if elements loaded, then:
{
  "command": "click_by_selector",
  "args": {
    "selector": "button[data-testid='submit']"
  }
}

🔄 Complete Workflow Examples

Example 1: Creating a New Item in an App

// 1. Take a screenshot to see current state
{
  "tool": "take_screenshot"
}

// 2. Understand the page structure
{
  "tool": "send_command_to_electron",
  "args": {
    "command": "get_page_structure"
  }
}

// 3. Click the "Create" button
{
  "tool": "send_command_to_electron",
  "args": {
    "command": "click_by_text",
    "args": {
      "text": "Create New"
    }
  }
}

// 4. Fill in the form
{
  "tool": "send_command_to_electron",
  "args": {
    "command": "fill_input",
    "args": {
      "placeholder": "Enter name",
      "value": "My New Item"
    }
  }
}

// 5. Submit the form
{
  "tool": "send_command_to_electron",
  "args": {
    "command": "click_by_selector",
    "args": {
      "selector": "button[type='submit']"
    }
  }
}

// 6. Verify success
{
  "tool": "take_screenshot"
}

Example 2: Debugging Element Issues

// 1. Get all button information
{
  "tool": "send_command_to_electron",
  "args": {
    "command": "debug_elements"
  }
}

// 2. Check specific element properties
{
  "tool": "send_command_to_electron",
  "args": {
    "command": "eval",
    "args": {
      "code": "Array.from(document.querySelectorAll('button')).map(btn => ({text: btn.textContent, classes: btn.className, visible: btn.offsetParent !== null}))"
    }
  }
}

// 3. Try alternative targeting method
{
  "tool": "send_command_to_electron",
  "args": {
    "command": "click_by_text",
    "args": {
      "text": "Submit"
    }
  }
}

💡 Best Practices

1. Always Verify Element Existence

{
  "command": "eval",
  "args": {
    "code": "document.querySelector('button.submit') ? 'Element exists' : 'Element not found'"
  }
}

2. Use Text-Based Targeting When Possible

Text-based targeting is more resilient to UI changes:

{
  "command": "click_by_text",
  "args": {
    "text": "Save"
  }
}

3. Fallback Strategies

// Try text first
{
  "command": "click_by_text",
  "args": {
    "text": "Submit"
  }
}

// If that fails, try selector
{
  "command": "click_by_selector",
  "args": {
    "selector": "button[type='submit']"
  }
}

4. Handle Dynamic Content

// Check if content is loaded
{
  "command": "eval",
  "args": {
    "code": "document.querySelector('.loading') ? 'Still loading' : 'Ready'"
  }
}

🛠️ Security Considerations

Safe JavaScript Execution

// SAFE - simple property access
{
  "command": "eval",
  "args": {
    "code": "document.title"
  }
}

// AVOID - complex operations that might be blocked
{
  "command": "eval",
  "args": {
    "code": "fetch('/api/data').then(r => r.json())"
  }
}

Use Built-in Commands

Prefer built-in commands over eval when possible:

// BETTER
{
  "command": "get_title"
}

// INSTEAD OF
{
  "command": "eval",
  "args": {
    "code": "document.title"
  }
}

📝 Tool Reference Summary

Tool	Purpose	Key Arguments
get_electron_window_info	Get app info	includeChildren: boolean
take_screenshot	Capture screen	windowTitle?: string, outputPath?: string
send_command_to_electron	UI interaction	command: string, args: object
read_electron_logs	View logs	logType?: string, lines?: number

Remember: Always structure arguments as objects with the appropriate properties for each command!