shortcut
/
cremote
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
cremote/mcp/LLM_USAGE_GUIDE.md

41 KiB
Raw Blame History

Cremote MCP Tools - LLM Usage Guide

This guide explains how LLMs can use the cremote MCP (Model Context Protocol) tools for web automation tasks.

🎉 Complete Web Automation Platform

The cremote MCP server provides 31 comprehensive web automation tools organized across 6 enhancement phases:

  • Core Tools (10): Essential web automation capabilities
  • Phase 1 (2): Element state checking and conditional logic
  • Phase 2 (4): Enhanced data extraction and batch operations
  • Phase 3 (3): Form analysis and bulk operations
  • Phase 4 (4): Page state and metadata tools
  • Phase 5 (4): Enhanced screenshots and file management
  • Phase 6 (3): Accessibility tree support for semantic understanding

Available Tools (31 Total)

1. web_navigate_cremotemcp

Navigate to URLs and optionally take screenshots.

Parameters:

  • url (required): The URL to navigate to
  • screenshot (optional): Boolean, take a screenshot after navigation
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_navigate_cremotemcp:
  url: "https://example.com"
  screenshot: true

2. web_interact_cremotemcp

Interact with web elements through various actions.

Parameters:

  • action (required): One of "click", "fill", "submit", "upload", "select"
  • selector (required): CSS selector for the target element
  • value (optional): Value for fill/upload/select actions
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_interact_cremotemcp:
  action: "click"
  selector: "button.submit"

web_interact_cremotemcp:
  action: "fill"
  selector: "input[name='email']"
  value: "user@example.com"

web_interact_cremotemcp:
  action: "select"
  selector: "#country"
  value: "United States"

3. web_extract_cremotemcp

Extract data from web pages (HTML source, element content, or JavaScript execution).

Parameters:

  • type (required): One of "source", "element", "javascript"
  • selector (optional): CSS selector (required for "element" type)
  • code (optional): JavaScript code (required for "javascript" type)
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_extract_cremotemcp:
  type: "source"

web_extract_cremotemcp:
  type: "element"
  selector: "div.content"

web_extract_cremotemcp:
  type: "javascript"
  code: "document.title"

4. web_screenshot_cremotemcp

Take screenshots of web pages.

Parameters:

  • output (required): File path where screenshot will be saved
  • full_page (optional): Capture full page (default: false)
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_screenshot_cremotemcp:
  output: "/tmp/page-screenshot.png"
  full_page: true

5. web_manage_tabs_cremotemcp

Manage browser tabs (open, close, list, switch).

Parameters:

  • action (required): One of "open", "close", "list", "switch"
  • tab (optional): Tab ID (required for "close" and "switch" actions)
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_manage_tabs_cremotemcp:
  action: "open"

web_manage_tabs_cremotemcp:
  action: "list"

web_manage_tabs_cremotemcp:
  action: "switch"
  tab: "ABC123"

6. web_iframe_cremotemcp

Switch iframe context for subsequent operations.

Parameters:

  • action (required): One of "enter", "exit"
  • selector (optional): Iframe CSS selector (required for "enter" action)
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_iframe_cremotemcp:
  action: "enter"
  selector: "iframe#payment-form"
  timeout: 10

web_iframe_cremotemcp:
  action: "exit"

Note: The timeout parameter is particularly important for iframe operations as they can hang if the iframe takes time to load or if the selector doesn't match any elements.

7. file_upload_cremotemcp

Upload files from the client to the container for use in form uploads.

Parameters:

  • local_path (required): Path to the file on the client machine
  • container_path (optional): Path where to store the file in the container (defaults to /tmp/filename)

Example Usage:

file_upload_cremotemcp:
  local_path: "/home/user/document.pdf"
  container_path: "/tmp/upload.pdf"

file_upload_cremotemcp:
  local_path: "/home/user/image.jpg"
  # Will default to /tmp/image.jpg in container

8. file_download_cremotemcp

Download files from the container to the client (e.g., downloaded files from browser).

Parameters:

  • container_path (required): Path to the file in the container
  • local_path (required): Path where to save the file on the client machine

Example Usage:

file_download_cremotemcp:
  container_path: "/tmp/downloaded-report.pdf"
  local_path: "/home/user/Downloads/report.pdf"

9. console_logs_cremotemcp

Get console logs from the browser tab for debugging.

Parameters:

  • tab (optional): Specific tab ID to use
  • clear (optional): Clear logs after retrieval (default: false)

Example Usage:

console_logs_cremotemcp:
  clear: true

console_logs_cremotemcp:
  tab: "ABC123"
  clear: false

10. web_element_check_cremotemcp (New in Phase 1)

Check element states without interaction - perfect for conditional logic.

Parameters:

  • selector (required): CSS selector for the element(s)
  • check_type (optional): Type of check - "exists", "visible", "enabled", "focused", "selected", "all" (default: "exists")
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_element_check_cremotemcp:
  selector: "#submit-button"
  check_type: "enabled"

web_element_check_cremotemcp:
  selector: ".error-message"
  check_type: "visible"

web_element_check_cremotemcp:
  selector: "input[type='checkbox']"
  check_type: "all"

Response Format: The tool returns a JSON object with boolean values for each check:

{
  "exists": true,
  "visible": true,
  "enabled": false,
  "focused": false,
  "selected": true,
  "count": 1
}

Use Cases:

  • Check if a form is ready for submission
  • Verify if error messages are displayed
  • Confirm element visibility before interaction
  • Count matching elements
  • Implement conditional workflows

11. web_element_attributes_cremotemcp (New in Phase 1)

Get detailed element information including attributes, properties, and computed styles.

Parameters:

  • selector (required): CSS selector for the element
  • attributes (optional): Attributes to retrieve - "all" or comma-separated list (default: "all")
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Attribute Prefixes:

  • No prefix: HTML attributes (e.g., "id", "class", "href")
  • style_: Computed CSS styles (e.g., "style_display", "style_color")
  • prop_: JavaScript properties (e.g., "prop_textContent", "prop_value")

Example Usage:

web_element_attributes_cremotemcp:
  selector: "#user-profile"
  attributes: "all"

web_element_attributes_cremotemcp:
  selector: "input[name='email']"
  attributes: "value,placeholder,type"

web_element_attributes_cremotemcp:
  selector: ".status-indicator"
  attributes: "class,style_color,style_display,prop_textContent"

Response Format: Returns a JSON object with requested attributes:

{
  "id": "user-profile",
  "class": "profile-card active",
  "data-user-id": "12345",
  "style_display": "block",
  "style_color": "rgb(0, 0, 0)",
  "prop_textContent": "John Doe"
}

Use Cases:

  • Extract form field values
  • Get element styling information
  • Retrieve data attributes
  • Analyze element properties for debugging

12. console_command_cremotemcp

Execute JavaScript commands in the browser console.

Parameters:

  • command (required): JavaScript command to execute
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

console_command_cremotemcp:
  command: "console.log('Hello from MCP!')"

console_command_cremotemcp:
  command: "document.querySelector('h1').textContent"
  timeout: 10

13. web_extract_multiple_cremotemcp (New in Phase 2)

Extract data from multiple selectors in a single call, reducing round trips and improving efficiency.

Parameters:

  • selectors (required): Object with keys as labels and values as CSS selectors
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_extract_multiple_cremotemcp:
  selectors:
    title: "h1"
    price: ".price"
    description: ".product-description"
    availability: ".stock-status"

Response Format: Returns structured results with both successful extractions and any errors:

{
  "results": {
    "title": "Product Name",
    "price": "$29.99",
    "description": "Product description text",
    "availability": "In Stock"
  },
  "errors": {}
}

Use Cases:

  • Extract multiple data points from product pages
  • Gather form field values efficiently
  • Collect page metadata in one call
  • Reduce API calls for complex data extraction

14. web_extract_links_cremotemcp (New in Phase 2)

Extract all links from a page with powerful filtering options.

Parameters:

  • container_selector (optional): CSS selector to limit search to a container
  • href_pattern (optional): Regex pattern to filter links by href
  • text_pattern (optional): Regex pattern to filter links by text content
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

# Extract all links
web_extract_links_cremotemcp: {}

# Extract only HTTPS links from navigation
web_extract_links_cremotemcp:
  container_selector: "nav"
  href_pattern: "https://.*"

# Extract download links
web_extract_links_cremotemcp:
  text_pattern: ".*[Dd]ownload.*"

Response Format: Returns detailed link information:

{
  "links": [
    {
      "href": "https://example.com/page1",
      "text": "Page 1",
      "title": "Go to Page 1",
      "target": "_blank"
    }
  ],
  "count": 1
}

Use Cases:

  • Discover all navigation links
  • Find download or external links
  • Extract social media links
  • Analyze site structure

15. web_extract_table_cremotemcp (New in Phase 2)

Extract table data as structured JSON with optional header processing.

Parameters:

  • selector (required): CSS selector for the table element
  • include_headers (optional): Whether to extract headers for structured data (default: true)
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_extract_table_cremotemcp:
  selector: "#data-table"
  include_headers: true

Response Format: Returns both raw rows and structured data when headers are included:

{
  "headers": ["Name", "Age", "City"],
  "rows": [
    ["John", "25", "New York"],
    ["Jane", "30", "London"]
  ],
  "data": [
    {"Name": "John", "Age": "25", "City": "New York"},
    {"Name": "Jane", "Age": "30", "City": "London"}
  ],
  "count": 2
}

Use Cases:

  • Extract pricing tables
  • Process data tables for analysis
  • Convert HTML tables to structured data
  • Export table data for processing

16. web_extract_text_cremotemcp (New in Phase 2)

Extract text content with optional pattern matching and different extraction types.

Parameters:

  • selector (required): CSS selector for elements to extract text from
  • pattern (optional): Regex pattern to match within the extracted text
  • extract_type (optional): Type of text extraction - "text", "innerText", "textContent" (default: "textContent")
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

# Extract all text content
web_extract_text_cremotemcp:
  selector: ".content"

# Extract phone numbers using regex
web_extract_text_cremotemcp:
  selector: ".contact-info"
  pattern: "\\d{3}-\\d{3}-\\d{4}"

# Extract visible text only
web_extract_text_cremotemcp:
  selector: ".description"
  extract_type: "innerText"

Response Format: Returns text content and pattern matches:

{
  "text": "Contact us at 555-123-4567 or 555-987-6543",
  "matches": ["555-123-4567", "555-987-6543"],
  "count": 1
}

Use Cases:

  • Extract contact information
  • Find specific data patterns (emails, phones, dates)
  • Get clean text content
  • Process text for analysis

17. web_form_analyze_cremotemcp (New in Phase 3)

Analyze forms completely to understand their structure, fields, and submission requirements.

Parameters:

  • selector (required): CSS selector for the form element
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

# Analyze a registration form
web_form_analyze_cremotemcp:
  selector: "#registration-form"

# Analyze any form on the page
web_form_analyze_cremotemcp:
  selector: "form"

Response Format: Returns comprehensive form analysis:

{
  "action": "/submit-registration",
  "method": "POST",
  "fields": [
    {
      "name": "username",
      "type": "text",
      "value": "",
      "placeholder": "Enter username",
      "required": true,
      "disabled": false,
      "readonly": false,
      "selector": "[name='username']",
      "label": "Username"
    }
  ],
  "field_count": 5,
  "can_submit": true,
  "submit_text": "Register"
}

Use Cases:

  • Understand form structure before filling
  • Identify required fields and validation rules
  • Generate appropriate field selectors
  • Plan form completion workflows

18. web_interact_multiple_cremotemcp (New in Phase 3)

Perform multiple interactions in a single call for efficient batch operations.

Parameters:

  • interactions (required): Array of interaction objects
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Each interaction object contains:

  • selector (required): CSS selector for the element
  • action (required): One of "click", "fill", "select", "check", "uncheck"
  • value (optional): Value for fill/select actions

Example Usage:

# Complete a login form in one call
web_interact_multiple_cremotemcp:
  interactions:
    - selector: "#username"
      action: "fill"
      value: "testuser"
    - selector: "#password"
      action: "fill"
      value: "testpass"
    - selector: "#remember-me"
      action: "check"
    - selector: "#login-btn"
      action: "click"

Response Format: Returns results for each interaction:

{
  "results": [
    {
      "selector": "#username",
      "action": "fill",
      "success": true
    },
    {
      "selector": "#password",
      "action": "fill",
      "success": true
    }
  ],
  "success_count": 4,
  "error_count": 0,
  "total_count": 4
}

Use Cases:

  • Complete forms efficiently
  • Perform multiple clicks/selections
  • Batch checkbox/radio button operations
  • Reduce round trips for complex interactions

19. web_form_fill_bulk_cremotemcp (New in Phase 3)

Fill entire forms with key-value pairs in a single operation.

Parameters:

  • fields (required): Object mapping field names/selectors to values
  • form_selector (optional): CSS selector for the form element
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

# Fill a contact form
web_form_fill_bulk_cremotemcp:
  form_selector: "#contact-form"
  fields:
    name: "John Doe"
    email: "john@example.com"
    message: "Hello, this is a test message."

# Fill fields across the entire page
web_form_fill_bulk_cremotemcp:
  fields:
    username: "testuser"
    password: "testpass"
    email: "test@example.com"

Response Format: Returns results for each field:

{
  "filled_fields": [
    {
      "selector": "[name='name']",
      "action": "fill",
      "success": true
    },
    {
      "selector": "[name='email']",
      "action": "fill",
      "success": true
    }
  ],
  "success_count": 3,
  "error_count": 0,
  "total_count": 3
}

Use Cases:

  • Quick form completion
  • Bulk data entry
  • Form testing with multiple datasets
  • Automated registration workflows

20. web_page_info_cremotemcp (New in Phase 4)

Get comprehensive page metadata and state information.

Parameters:

  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_page_info_cremotemcp:
  tab: "tab-123"

Response Format: Returns detailed page information:

{
  "title": "Example Page",
  "url": "https://example.com",
  "loading_state": "complete",
  "ready_state": "complete",
  "domain": "example.com",
  "protocol": "https:",
  "charset": "UTF-8",
  "cookie_enabled": true,
  "online_status": true
}

21. web_viewport_info_cremotemcp (New in Phase 4)

Get viewport and scroll information.

Parameters:

  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_viewport_info_cremotemcp:
  tab: "tab-123"

Response Format: Returns viewport dimensions and scroll data:

{
  "width": 1920,
  "height": 1080,
  "scroll_x": 0,
  "scroll_y": 150,
  "scroll_width": 1920,
  "scroll_height": 2400,
  "device_pixel_ratio": 1.0,
  "orientation": "landscape-primary"
}

22. web_performance_metrics_cremotemcp (New in Phase 4)

Get page performance metrics.

Parameters:

  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

web_performance_metrics_cremotemcp:
  tab: "tab-123"

Response Format: Returns performance data:

{
  "navigation_start": 1692123456789,
  "load_event_end": 1692123457234,
  "load_time": 445,
  "dom_load_time": 234,
  "resource_count": 15,
  "js_heap_size_used": 2048576
}

23. web_content_check_cremotemcp (New in Phase 4)

Check for specific content types and loading states.

Parameters:

  • type (required): Content type to check ("images", "scripts", "styles", "forms", "links", "iframes", "errors")
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

# Check image loading status
web_content_check_cremotemcp:
  type: "images"

# Check for errors
web_content_check_cremotemcp:
  type: "errors"

Response Format: Returns content verification results:

{
  "type": "images",
  "images_loaded": 8,
  "images_total": 10
}

24. web_screenshot_element_cremotemcp (New in Phase 5)

Take a screenshot of a specific element on the page.

Parameters:

  • selector (required): CSS selector for the element to screenshot
  • output (required): Path where to save the screenshot
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

# Screenshot a specific element
web_screenshot_element_cremotemcp:
  selector: "#main-content"
  output: "/tmp/element-screenshot.png"

# Screenshot a form
web_screenshot_element_cremotemcp:
  selector: "form.login-form"
  output: "/tmp/login-form.png"

Key Features:

  • Automatically scrolls element into view
  • Captures only the specified element
  • Handles element positioning and sizing

25. web_screenshot_enhanced_cremotemcp (New in Phase 5)

Take an enhanced screenshot with metadata.

Parameters:

  • output (required): Path where to save the screenshot
  • full_page (optional): Capture full page (default: false)
  • tab (optional): Specific tab ID to use
  • timeout (optional): Timeout in seconds (default: 5)

Example Usage:

# Enhanced screenshot with metadata
web_screenshot_enhanced_cremotemcp:
  output: "/tmp/enhanced-screenshot.png"
  full_page: true

# Viewport screenshot with metadata
web_screenshot_enhanced_cremotemcp:
  output: "/tmp/viewport-screenshot.png"
  full_page: false

Response Format: Returns screenshot metadata:

{
  "timestamp": "2025-08-16T10:30:00Z",
  "url": "https://example.com",
  "title": "Example Page",
  "viewport_size": {
    "width": 1920,
    "height": 1080
  },
  "full_page": true,
  "file_path": "/tmp/enhanced-screenshot.png",
  "file_size": 245760,
  "resolution": {
    "width": 1920,
    "height": 1080
  }
}

26. file_operations_bulk_cremotemcp (New in Phase 5)

Perform bulk file operations (upload/download multiple files).

Parameters:

  • operation (required): Operation type ("upload" or "download")
  • files (required): Array of file operations
  • timeout (optional): Timeout in seconds (default: 30)

File Operation Object:

  • local_path (required): Path on client machine
  • container_path (required): Path in container
  • operation (optional): Override operation type for this file

Example Usage:

# Bulk upload files
file_operations_bulk_cremotemcp:
  operation: "upload"
  files:
    - local_path: "/local/file1.txt"
      container_path: "/tmp/file1.txt"
    - local_path: "/local/file2.txt"
      container_path: "/tmp/file2.txt"
  timeout: 30

# Bulk download files
file_operations_bulk_cremotemcp:
  operation: "download"
  files:
    - local_path: "/local/downloaded1.txt"
      container_path: "/tmp/file1.txt"
    - local_path: "/local/downloaded2.txt"
      container_path: "/tmp/file2.txt"

Response Format: Returns detailed operation results:

{
  "successful": [
    {
      "local_path": "/local/file1.txt",
      "container_path": "/tmp/file1.txt",
      "operation": "upload",
      "size": 1024
    }
  ],
  "failed": [
    {
      "local_path": "/local/file2.txt",
      "container_path": "/tmp/file2.txt",
      "operation": "upload",
      "error": "file not found"
    }
  ],
  "summary": {
    "total": 2,
    "successful": 1,
    "failed": 1
  }
}

27. file_management_cremotemcp (New in Phase 5)

Manage files (cleanup, list, get info).

Parameters:

  • operation (required): Management operation ("cleanup", "list", "info")
  • pattern (optional): File pattern for cleanup/list, or file path for info
  • max_age (optional): Max age in hours for cleanup (default: 24)

Example Usage:

# Cleanup old temporary files
file_management_cremotemcp:
  operation: "cleanup"
  pattern: "/tmp/cremote-*"
  max_age: "24"

# List files in directory
file_management_cremotemcp:
  operation: "list"
  pattern: "/tmp/*"

# Get info about specific file
file_management_cremotemcp:
  operation: "info"
  pattern: "/tmp/specific-file.txt"

Response Format: Returns file management results:

{
  "operation": "cleanup",
  "cleaned": [
    "/tmp/cremote-old-file1.txt",
    "/tmp/cremote-old-file2.txt"
  ],
  "summary": {
    "files_cleaned": 2,
    "total_size_freed": 2048,
    "cutoff_time": "2025-08-15T10:30:00Z"
  }
}

Common Usage Patterns

1. Basic Web Navigation

# Navigate to a website
web_navigate_cremotemcp:
  url: "https://example.com"
  screenshot: true

2. Form Interaction Sequence

# 1. Navigate to the page
web_navigate_cremotemcp:
  url: "https://example.com/login"

# 2. Fill username field
web_interact_cremotemcp:
  action: "fill"
  selector: "input[name='username']"
  value: "myusername"

# 3. Fill password field
web_interact_cremotemcp:
  action: "fill"
  selector: "input[name='password']"
  value: "mypassword"

# 4. Submit the form
web_interact_cremotemcp:
  action: "submit"
  selector: "form"

3. Clicking Elements

# Click a button
web_interact_cremotemcp:
  action: "click"
  selector: "button#submit-btn"

# Click a link
web_interact_cremotemcp:
  action: "click"
  selector: "a[href='/dashboard']"

4. Smart Form Handling (Phase 3 Pattern)

# 1. Analyze the form first
web_form_analyze_cremotemcp:
  selector: "#registration-form"

# 2. Fill the form efficiently
web_form_fill_bulk_cremotemcp:
  form_selector: "#registration-form"
  fields:
    username: "newuser123"
    email: "user@example.com"
    password: "securepass"
    confirm_password: "securepass"

# 3. Submit the form
web_interact_cremotemcp:
  action: "click"
  selector: "button[type='submit']"

5. Batch Operations (Phase 3 Pattern)

# Complete multiple actions efficiently
web_interact_multiple_cremotemcp:
  interactions:
    - selector: "#agree-terms"
      action: "check"
    - selector: "#newsletter"
      action: "uncheck"
    - selector: "#country"
      action: "select"
      value: "United States"
    - selector: "#submit-btn"
      action: "click"

6. Complex Form Workflows (Phase 3 Pattern)

# 1. Navigate to registration page
web_navigate_cremotemcp:
  url: "https://example.com/register"

# 2. Analyze the form structure
web_form_analyze_cremotemcp:
  selector: "form"

# 3. Fill all fields at once
web_form_fill_bulk_cremotemcp:
  fields:
    first_name: "John"
    last_name: "Doe"
    email: "john.doe@example.com"
    phone: "555-123-4567"
    company: "Acme Corp"

# 4. Handle checkboxes and selections
web_interact_multiple_cremotemcp:
  interactions:
    - selector: "#terms-agreement"
      action: "check"
    - selector: "#marketing-emails"
      action: "uncheck"
    - selector: "#account-type"
      action: "select"
      value: "business"

# 5. Submit and verify
web_interact_cremotemcp:
  action: "click"
  selector: "button[type='submit']"

7. Page State Monitoring (Phase 4 Pattern)

# 1. Navigate to a page
web_navigate_cremotemcp:
  url: "https://example.com/dashboard"

# 2. Get comprehensive page information
web_page_info_cremotemcp:
  timeout: 5

# 3. Check viewport and scroll position
web_viewport_info_cremotemcp:
  timeout: 5

# 4. Verify content is loaded
web_content_check_cremotemcp:
  type: "images"

# 5. Check for any errors
web_content_check_cremotemcp:
  type: "errors"

# 6. Get performance metrics
web_performance_metrics_cremotemcp:
  timeout: 5

Best Practices for LLMs

1. Always Start with Navigation

Before interacting with elements, navigate to the target page:

web_navigate_cremotemcp:
  url: "https://target-website.com"

2. Use Specific CSS Selectors

Be as specific as possible with selectors to avoid ambiguity:

  • Good: input[name='email'], button.primary-submit
  • Avoid: input, button

3. Take Screenshots for Debugging

When troubleshooting or documenting, use screenshots:

web_navigate_cremotemcp:
  url: "https://example.com"
  screenshot: true

4. Handle Timeouts Appropriately

For slow-loading pages, increase timeout:

web_navigate_cremotemcp:
  url: "https://slow-website.com"
  timeout: 10

5. Sequential Operations

Perform operations in logical sequence:

  1. Navigate to page
  2. Fill required fields
  3. Submit forms
  4. Navigate to next page if needed

Error Handling

Common Error Scenarios:

  1. Element not found: Selector doesn't match any elements
  2. Timeout: Page takes too long to load or element to appear
  3. Navigation failed: URL is invalid or unreachable

Troubleshooting Tips:

  1. Verify the URL is correct and accessible
  2. Check CSS selectors using browser developer tools
  3. Increase timeout for slow-loading content
  4. Take screenshots to see current page state

Tab Management

The tools automatically manage browser tabs:

  • If no tab is specified, a new tab is created automatically
  • Tab IDs are returned in responses for reference
  • Multiple tabs can be managed by specifying tab IDs

Security Considerations

Safe Practices:

  • Only navigate to trusted websites
  • Be cautious with form submissions
  • Avoid entering sensitive information in examples
  • Use screenshots sparingly to avoid exposing sensitive data

Limitations:

  • Cannot bypass CAPTCHA or other anti-automation measures
  • Subject to same-origin policy restrictions
  • May not work with heavily JavaScript-dependent sites

Example: Complete Web Automation Task

Here's a complete example of automating a web form:

# Step 1: Navigate to the form page
web_navigate_cremotemcp:
  url: "https://example.com/contact"
  screenshot: true

# Step 2: Fill out the contact form
web_interact_cremotemcp:
  action: "fill"
  selector: "input[name='name']"
  value: "John Doe"

web_interact_cremotemcp:
  action: "fill"
  selector: "input[name='email']"
  value: "john@example.com"

web_interact_cremotemcp:
  action: "fill"
  selector: "textarea[name='message']"
  value: "Hello, this is a test message."

# Step 3: Submit the form
web_interact_cremotemcp:
  action: "submit"
  selector: "form#contact-form"

# Step 4: Take a screenshot of the result
web_navigate_cremotemcp:
  url: "current"  # Stay on current page
  screenshot: true

Example: File Upload Workflow

Here's how to upload a file and use it in a web form:

# Step 1: Upload a file from client to container
file_upload_cremotemcp:
  local_path: "/home/user/resume.pdf"
  container_path: "/tmp/resume.pdf"

# Step 2: Navigate to upload form
web_navigate_cremotemcp:
  url: "https://jobsite.com/apply"

# Step 3: Fill out application form
web_interact_cremotemcp:
  action: "fill"
  selector: "input[name='name']"
  value: "Jane Smith"

# Step 4: Upload the file using the container path
web_interact_cremotemcp:
  action: "upload"
  selector: "input[type='file']"
  value: "/tmp/resume.pdf"

# Step 5: Submit the application
web_interact_cremotemcp:
  action: "submit"
  selector: "form.application"

Example: Download Files from Browser

Here's how to download files that the browser saves:

# Step 1: Navigate to download page
web_navigate_cremotemcp:
  url: "https://example.com/reports"

# Step 2: Click download link
web_interact_cremotemcp:
  action: "click"
  selector: "a.download-report"

# Step 3: Wait a moment for download to complete
# (In practice, you might need to check for file existence)

# Step 4: Download the file from container to client
file_download_cremotemcp:
  container_path: "/tmp/downloads/report.pdf"
  local_path: "/home/user/Downloads/report.pdf"

Example: Console Debugging Workflow

Here's how to use console tools for debugging web automation:

# Step 1: Navigate to a page
web_navigate_cremotemcp:
  url: "https://example.com/form"

# Step 2: Check what's in the console initially
console_logs_cremotemcp:
  clear: false

# Step 3: Execute some debugging commands
console_command_cremotemcp:
  command: "console.log('Starting form automation')"

console_command_cremotemcp:
  command: "document.querySelectorAll('input').length"

# Step 4: Try to interact with form
web_interact_cremotemcp:
  action: "fill"
  selector: "input[name='email']"
  value: "test@example.com"

# Step 5: Check for any console errors after interaction
console_logs_cremotemcp:
  clear: false

# Step 6: Debug element selection
console_command_cremotemcp:
  command: "document.querySelector('input[name=\"email\"]') ? 'Found' : 'Not found'"

# Step 7: Check element properties
console_command_cremotemcp:
  command: "document.querySelector('input[name=\"email\"]').value"

Example: Phase 2 Enhanced Data Extraction

Here's how to use the new Phase 2 tools for efficient data extraction:

# Step 1: Navigate to a product page
web_navigate_cremotemcp:
  url: "https://ecommerce.com/product/123"

# Step 2: Extract multiple data points in one call
web_extract_multiple_cremotemcp:
  selectors:
    title: "h1.product-title"
    price: ".price-current"
    description: ".product-description"
    rating: ".rating-score"
    availability: ".stock-status"

# Step 3: Extract all product images and links
web_extract_links_cremotemcp:
  container_selector: ".product-gallery"
  href_pattern: ".*\\.(jpg|png|gif).*"

# Step 4: Extract reviews table if present
web_extract_table_cremotemcp:
  selector: "#reviews-table"
  include_headers: true

# Step 5: Extract specific text patterns (like model numbers)
web_extract_text_cremotemcp:
  selector: ".product-specs"
  pattern: "Model: ([A-Z0-9-]+)"

Example: Comprehensive Site Analysis

Here's how to analyze a website's structure using Phase 2 tools:

# Step 1: Navigate to the homepage
web_navigate_cremotemcp:
  url: "https://example.com"

# Step 2: Extract all navigation links
web_extract_links_cremotemcp:
  container_selector: "nav"

# Step 3: Extract social media links
web_extract_links_cremotemcp:
  href_pattern: ".*(facebook|twitter|linkedin|instagram).*"

# Step 4: Extract contact information
web_extract_text_cremotemcp:
  selector: ".contact-info"
  pattern: "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b"

# Step 5: Extract phone numbers
web_extract_text_cremotemcp:
  selector: "body"
  pattern: "\\(?\\d{3}\\)?[-. ]?\\d{3}[-. ]?\\d{4}"

# Step 6: Extract key page elements in one call
web_extract_multiple_cremotemcp:
  selectors:
    title: "title"
    heading: "h1"
    meta_description: "meta[name='description']"
    footer_text: "footer"

Phase 6: Accessibility Tree Support (3 Tools)

get_accessibility_tree_cremotemcp

Get the full accessibility tree for a page or with limited depth for semantic understanding.

Parameters:

  • tab (optional): Tab ID, uses current tab if not specified
  • depth (optional): Maximum depth to retrieve, omit for full tree
  • timeout (optional): Timeout in seconds, default 5

Use Cases:

  • Accessibility testing and compliance verification
  • Understanding page structure for screen readers
  • Semantic element discovery and analysis

Example:

get_accessibility_tree_cremotemcp:
  depth: 3
  timeout: 10

get_partial_accessibility_tree_cremotemcp

Get accessibility tree for a specific element and its relatives (ancestors, siblings, children).

Parameters:

  • selector: CSS selector for the target element (required)
  • tab (optional): Tab ID, uses current tab if not specified
  • fetch_relatives (optional): Include relatives, default true
  • timeout (optional): Timeout in seconds, default 5

Use Cases:

  • Focused accessibility analysis of specific components
  • Form accessibility structure analysis
  • Widget accessibility verification

Example:

get_partial_accessibility_tree_cremotemcp:
  selector: "form.login-form"
  fetch_relatives: true
  timeout: 10

query_accessibility_tree_cremotemcp

Query accessibility tree for nodes matching specific criteria (accessible name, role, or scope).

Parameters:

  • tab (optional): Tab ID, uses current tab if not specified
  • selector (optional): CSS selector to limit search scope
  • accessible_name (optional): Accessible name to match
  • role (optional): ARIA role to match (e.g., "button", "textbox", "link")
  • timeout (optional): Timeout in seconds, default 5

Use Cases:

  • Find elements by their accessible names (what screen readers announce)
  • Locate elements by ARIA roles for semantic interaction
  • Accessibility-aware element discovery and testing

Examples:

# Find all buttons on the page
query_accessibility_tree_cremotemcp:
  role: "button"

# Find submit button by accessible name
query_accessibility_tree_cremotemcp:
  accessible_name: "Submit"
  role: "button"

# Find form controls within a specific form
query_accessibility_tree_cremotemcp:
  selector: "form.checkout"
  role: "textbox"

Integration Notes

  • Tools use the _cremotemcp suffix to avoid naming conflicts
  • Responses include success status and descriptive messages
  • Screenshots are saved to /tmp/ directory with timestamps
  • The underlying cremote daemon handles browser management
  • Accessibility tree tools provide semantic understanding of page structure

Advanced Usage Examples

Testing Web Applications

# Navigate to application
web_navigate_cremotemcp:
  url: "https://myapp.com/login"
  screenshot: true

# Test login functionality
web_interact_cremotemcp:
  action: "fill"
  selector: "#username"
  value: "testuser"

web_interact_cremotemcp:
  action: "fill"
  selector: "#password"
  value: "testpass"

web_interact_cremotemcp:
  action: "click"
  selector: "button[type='submit']"

# Verify successful login
web_navigate_cremotemcp:
  url: "current"
  screenshot: true

Data Extraction Workflows

# Navigate to data source
web_navigate_cremotemcp:
  url: "https://data-site.com/table"

# Click through pagination or filters
web_interact_cremotemcp:
  action: "click"
  selector: ".filter-button"

# Take screenshot to document current state
web_navigate_cremotemcp:
  url: "current"
  screenshot: true

File Upload Testing

# Navigate to upload form
web_navigate_cremotemcp:
  url: "https://example.com/upload"

# Upload a file
web_interact_cremotemcp:
  action: "upload"
  selector: "input[type='file']"
  value: "/path/to/test-file.pdf"

# Submit the upload form
web_interact_cremotemcp:
  action: "click"
  selector: "button.upload-submit"

Tool Response Format

Both tools return structured responses:

Success Response:

"Successfully navigated to https://example.com in tab ABC123 (screenshot saved to /tmp/navigate-1234567890.png)"

Error Response:

"failed to load URL: context deadline exceeded"

CSS Selector Best Practices

Recommended Selector Types:

  1. ID selectors: #unique-id (most reliable)
  2. Name attributes: input[name='fieldname']
  3. Class combinations: .primary.button
  4. Attribute selectors: button[data-action='submit']

Avoid These Selectors:

  1. Generic tags: div, span, input (too broad)
  2. Position-based: :nth-child() (fragile)
  3. Text-based: :contains() (not standard CSS)

🚀 Advanced Workflow Examples

Efficient Form Completion Workflow

# 1. Check if form exists
web_element_check_cremotemcp:
  selector: "#registration-form"
  check_type: "exists"

# 2. Analyze form structure
web_form_analyze_cremotemcp:
  selector: "#registration-form"

# 3. Fill entire form in one call
web_form_fill_bulk_cremotemcp:
  form_selector: "#registration-form"
  fields:
    name: "John Doe"
    email: "john@example.com"
    password: "securepass123"
    confirm_password: "securepass123"

Comprehensive Data Extraction Workflow

# 1. Get page performance metrics
web_performance_metrics_cremotemcp: {}

# 2. Extract multiple data points at once
web_extract_multiple_cremotemcp:
  selectors:
    title: "h1"
    price: ".price"
    description: ".product-description"
    availability: ".stock-status"

# 3. Extract all product links
web_extract_links_cremotemcp:
  container_selector: ".product-grid"
  href_pattern: ".*/product/.*"

# 4. Take enhanced screenshot with metadata
web_screenshot_enhanced_cremotemcp:
  output: "/tmp/product-page.png"
  full_page: true

Accessibility Testing and Semantic Automation

# Navigate to page for accessibility testing
web_navigate_cremotemcp:
  url: "https://myapp.com/form"
  screenshot: true

# Get full accessibility tree to analyze structure
get_accessibility_tree_cremotemcp:
  depth: 3
  timeout: 10

# Find form elements by accessible names (more robust than CSS selectors)
query_accessibility_tree_cremotemcp:
  accessible_name: "Email Address"
  role: "textbox"

# Fill form using accessibility-aware approach
web_interact_cremotemcp:
  action: "fill"
  selector: "[aria-label='Email Address']"
  value: "user@example.com"

# Find and click submit button by accessible name
query_accessibility_tree_cremotemcp:
  accessible_name: "Submit Form"
  role: "button"

# Verify form accessibility structure
get_partial_accessibility_tree_cremotemcp:
  selector: "form"
  fetch_relatives: true

🎯 Best Practices for LLM Agents

1. Use Batch Operations

  • Prefer web_extract_multiple_cremotemcp over multiple web_extract_cremotemcp calls
  • Use web_form_fill_bulk_cremotemcp instead of individual field interactions
  • Leverage web_interact_multiple_cremotemcp for complex interaction sequences

2. Check Before Acting

  • Always use web_element_check_cremotemcp before interacting with elements
  • Verify page state with web_page_info_cremotemcp when needed
  • Check content loading with web_content_check_cremotemcp

3. Optimize for Efficiency

  • 10x Form Efficiency: Complete forms in 1-2 calls instead of 10+
  • Batch Data Extraction: Extract multiple data points in single calls
  • Smart Element Checking: Prevent errors with conditional logic

4. Enhanced Debugging

  • Use web_screenshot_element_cremotemcp for targeted debugging
  • Leverage console_logs_cremotemcp for JavaScript error detection
  • Take web_screenshot_enhanced_cremotemcp with metadata for comprehensive documentation

5. Accessibility-Aware Automation

  • Use query_accessibility_tree_cremotemcp to find elements by accessible names instead of fragile selectors
  • Verify accessibility compliance with get_accessibility_tree_cremotemcp
  • Test screen reader compatibility by analyzing semantic structure
  • Build more robust automation using ARIA roles and accessible names

🎉 Production Ready

This comprehensive web automation platform provides 31 tools across 6 enhancement phases, optimized specifically for LLM agents and production workflows. All tools include proper error handling, timeout management, and structured responses for reliable automation.

Ready for Production: Complete web automation platform with 31 tools, designed for maximum efficiency and reliability in LLM-driven workflows.