cremote/mcp/LLM_USAGE_GUIDE.md

# 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 **27 comprehensive web automation tools** organized across 5 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

## Available Tools (27 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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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"
```

## 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

## 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
```yaml
# 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
```yaml
# 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
```

## 🎯 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

## 🎉 Production Ready

This comprehensive web automation platform provides **27 tools** across 5 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 27 tools, designed for maximum efficiency and reliability in LLM-driven workflows.