cremote/mcp/QUICK_REFERENCE.md

# Cremote MCP Tools - Quick Reference

## 🎉 Complete Web Automation Platform (27 Tools)

### Tool Names by Category
#### Core Web Automation (10 tools)
- `web_navigate_cremotemcp` - Navigate to URLs
- `web_interact_cremotemcp` - Interact with elements
- `web_extract_cremotemcp` - Extract page data
- `web_screenshot_cremotemcp` - Take screenshots
- `web_manage_tabs_cremotemcp` - Manage browser tabs
- `web_iframe_cremotemcp` - Switch iframe context
- `file_upload_cremotemcp` - Upload files to container
- `file_download_cremotemcp` - Download files from container
- `console_logs_cremotemcp` - Get browser console logs
- `console_command_cremotemcp` - Execute console commands

#### Phase 1: Element Intelligence (2 tools)
- `web_element_check_cremotemcp` - Check element states
- `web_element_attributes_cremotemcp` - Get element attributes

#### Phase 2: Enhanced Data Extraction (4 tools)
- `web_extract_multiple_cremotemcp` - Extract from multiple selectors
- `web_extract_links_cremotemcp` - Extract all links with filtering
- `web_extract_table_cremotemcp` - Extract table data as structured JSON
- `web_extract_text_cremotemcp` - Extract text with pattern matching

#### Phase 3: Form Automation (3 tools)
- `web_form_analyze_cremotemcp` - Analyze forms completely
- `web_interact_multiple_cremotemcp` - Batch interactions
- `web_form_fill_bulk_cremotemcp` - Fill entire forms with key-value pairs

#### Phase 4: Page Intelligence (4 tools)
- `web_page_info_cremotemcp` - Get page metadata and state
- `web_viewport_info_cremotemcp` - Get viewport and scroll info
- `web_performance_metrics_cremotemcp` - Get performance metrics
- `web_content_check_cremotemcp` - Check content types and loading

#### Phase 5: Enhanced Capabilities (4 tools)
- `web_screenshot_element_cremotemcp` - Screenshot specific elements
- `web_screenshot_enhanced_cremotemcp` - Enhanced screenshots with metadata
- `file_operations_bulk_cremotemcp` - Bulk file operations
- `file_management_cremotemcp` - File management operations

## Essential Parameters

### web_navigate_cremotemcp
```yaml
url: "https://example.com"        # Required
screenshot: true                  # Optional, default false
timeout: 10                      # Optional, default 5 seconds
```

### web_interact_cremotemcp
```yaml
action: "click"                  # Required: click|fill|submit|upload|select
selector: "button.submit"        # Required: CSS selector
value: "text to fill"           # Required for fill/upload/select actions
timeout: 10                     # Optional, default 5 seconds
```

### web_element_check_cremotemcp *(New)*
```yaml
selector: "#submit-button"       # Required: CSS selector
check_type: "enabled"           # Optional: exists|visible|enabled|focused|selected|all
timeout: 5                      # Optional, default 5 seconds
```

### web_element_attributes_cremotemcp *(New)*
```yaml
selector: "#user-profile"       # Required: CSS selector
attributes: "all"               # Optional: "all" or "id,class,href" or "style_color,prop_value"
timeout: 5                      # Optional, default 5 seconds
```

### web_form_analyze_cremotemcp *(Phase 3)*
```yaml
selector: "#registration-form"  # Required: CSS selector for form
timeout: 10                     # Optional, default 5 seconds
```

### web_interact_multiple_cremotemcp *(Phase 3)*
```yaml
interactions:                   # Required: Array of interaction objects
  - selector: "#username"       # Required: CSS selector
    action: "fill"              # Required: click|fill|select|check|uncheck
    value: "testuser"           # Optional: value for fill/select actions
  - selector: "#submit-btn"
    action: "click"
timeout: 10                     # Optional, default 5 seconds
```

### web_form_fill_bulk_cremotemcp *(Phase 3)*
```yaml
fields:                         # Required: Object mapping field names to values
  username: "testuser"
  email: "test@example.com"
  password: "testpass"
form_selector: "#contact-form"  # Optional: CSS selector for form
timeout: 10                     # Optional, default 5 seconds
```

### web_page_info_cremotemcp *(Phase 4)*
```yaml
tab: "tab-123"                  # Optional: Specific tab ID
timeout: 5                      # Optional, default 5 seconds
```

### web_viewport_info_cremotemcp *(Phase 4)*
```yaml
tab: "tab-123"                  # Optional: Specific tab ID
timeout: 5                      # Optional, default 5 seconds
```

### web_performance_metrics_cremotemcp *(Phase 4)*
```yaml
tab: "tab-123"                  # Optional: Specific tab ID
timeout: 5                      # Optional, default 5 seconds
```

### web_content_check_cremotemcp *(Phase 4)*
```yaml
type: "images"                  # Required: images|scripts|styles|forms|links|iframes|errors
tab: "tab-123"                  # Optional: Specific tab ID
timeout: 5                      # Optional, default 5 seconds
```

## Common Patterns

### Navigate + Screenshot
```yaml
web_navigate_cremotemcp:
  url: "https://example.com"
  screenshot: true
```

### Fill Form Field
```yaml
web_interact_cremotemcp:
  action: "fill"
  selector: "input[name='email']"
  value: "user@example.com"
```

### Select Dropdown Option
```yaml
web_interact_cremotemcp:
  action: "select"
  selector: "#country"
  value: "United States"  # Can use option text or value
```

### Click Button
```yaml
web_interact_cremotemcp:
  action: "click"
  selector: "button#submit"
```

### Submit Form
```yaml
web_interact_cremotemcp:
  action: "submit"
  selector: "form"
```

### Upload File
```yaml
web_interact_cremotemcp:
  action: "upload"
  selector: "input[type='file']"
  value: "/path/to/file.pdf"
```

### Upload File to Container
```yaml
file_upload_cremotemcp:
  local_path: "/home/user/document.pdf"
  container_path: "/tmp/upload.pdf"
```

### Download File from Container
```yaml
file_download_cremotemcp:
  container_path: "/tmp/downloaded.pdf"
  local_path: "/home/user/Downloads/file.pdf"
```

### Get Console Logs
```yaml
console_logs_cremotemcp:
  clear: true
```

### Execute Console Command
```yaml
console_command_cremotemcp:
  command: "document.title"
  timeout: 10
```

## Best CSS Selectors

✅ **Good:**
- `#unique-id`
- `input[name='fieldname']`
- `button.primary-submit`
- `form#login-form`

❌ **Avoid:**
- `div` (too generic)
- `input` (too broad)
- `:nth-child(3)` (fragile)

### Check Element Before Interaction *(New Pattern)*
```yaml
web_element_check_cremotemcp:
  selector: "#submit-button"
  check_type: "enabled"
```

### Get Form Field Values *(New Pattern)*
```yaml
web_element_attributes_cremotemcp:
  selector: "input[name='email']"
  attributes: "value,placeholder"
```

### Conditional Logic *(New Pattern)*
```yaml
# Check if error message is visible
web_element_check_cremotemcp:
  selector: ".error-message"
  check_type: "visible"

# Get all element information
web_element_attributes_cremotemcp:
  selector: "#status-indicator"
  attributes: "all"
```

### Smart Form Handling *(Phase 3 Pattern)*
```yaml
# 1. Analyze form structure
web_form_analyze_cremotemcp:
  selector: "#registration-form"

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

### Batch Operations *(Phase 3 Pattern)*
```yaml
# Complete multiple actions at once
web_interact_multiple_cremotemcp:
  interactions:
    - selector: "#terms"
      action: "check"
    - selector: "#newsletter"
      action: "uncheck"
    - selector: "#submit"
      action: "click"
```

### Complex Form Workflow *(Phase 3 Pattern)*
```yaml
# 1. Navigate and analyze
web_navigate_cremotemcp:
  url: "https://example.com/register"

web_form_analyze_cremotemcp:
  selector: "form"

# 2. Fill and submit
web_form_fill_bulk_cremotemcp:
  fields:
    first_name: "John"
    last_name: "Doe"
    email: "john@example.com"

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

### Page State Monitoring *(Phase 4 Pattern)*
```yaml
# 1. Get page information
web_page_info_cremotemcp:
  timeout: 5

# 2. Check viewport
web_viewport_info_cremotemcp:
  timeout: 5

# 3. Verify content loaded
web_content_check_cremotemcp:
  type: "images"

# 4. Check for errors
web_content_check_cremotemcp:
  type: "errors"

# 5. Get performance data
web_performance_metrics_cremotemcp:
  timeout: 5
```

## Typical Workflow

1. **Navigate** to target page
2. **Check** if required elements exist and are ready *(New)*
3. **Fill** required form fields
4. **Check** form validation state *(New)*
5. **Click** submit buttons
6. **Take screenshots** for verification
7. **Navigate** to next page if needed

## Enhanced Workflow with Element Checking *(New)*

1. **Navigate** to page with screenshot
2. **Check** if form is loaded: `web_element_check_cremotemcp`
3. **Get** current form values: `web_element_attributes_cremotemcp`
4. **Fill** form fields conditionally
5. **Check** if submit button is enabled
6. **Submit** form and verify success

### web_screenshot_element_cremotemcp *(Phase 5)*
- `selector` (required): CSS selector for element
- `output` (required): Screenshot file path
- `tab` (optional): Tab ID
- `timeout` (optional): Timeout in seconds

### web_screenshot_enhanced_cremotemcp *(Phase 5)*
- `output` (required): Screenshot file path
- `full_page` (optional): Capture full page
- `tab` (optional): Tab ID
- `timeout` (optional): Timeout in seconds

### file_operations_bulk_cremotemcp *(Phase 5)*
- `operation` (required): "upload" or "download"
- `files` (required): Array of file operations
- `timeout` (optional): Timeout in seconds

### file_management_cremotemcp *(Phase 5)*
- `operation` (required): "cleanup", "list", or "info"
- `pattern` (optional): File pattern or path
- `max_age` (optional): Max age in hours for cleanup

## 🚀 Efficiency Tips

### Batch Operations (10x Faster)
- Use `web_form_fill_bulk_cremotemcp` instead of multiple `web_interact_cremotemcp`
- Use `web_extract_multiple_cremotemcp` instead of multiple `web_extract_cremotemcp`
- Use `web_interact_multiple_cremotemcp` for complex interaction sequences

### Smart Element Checking
- Always use `web_element_check_cremotemcp` before interactions
- Check form state with `web_form_analyze_cremotemcp` before filling
- Verify page loading with `web_content_check_cremotemcp`

### Enhanced Debugging
- Use `web_screenshot_element_cremotemcp` for targeted debugging
- Use `web_screenshot_enhanced_cremotemcp` for comprehensive documentation
- Check `console_logs_cremotemcp` for JavaScript errors

## Error Handling

- **Element not found**: Check CSS selector, use `web_element_check_cremotemcp` first
- **Timeout**: Increase timeout parameter or check page loading state
- **Navigation failed**: Verify URL accessibility, check network connectivity
- **Form submission failed**: Use `web_form_analyze_cremotemcp` to understand form structure

## Screenshots

Screenshots are automatically saved to `/tmp/navigate-{timestamp}.png` when requested.
Enhanced screenshots include metadata with timestamp, URL, title, and viewport information.

## 🎉 Production Ready

**27 comprehensive tools** across 5 enhancement phases provide complete web automation capabilities:
- **10x Form Efficiency**: Complete forms in 1-2 calls instead of 10+
- **Batch Operations**: Multiple data extractions and interactions in single calls
- **Smart Element Checking**: Conditional logic without timing issues
- **Rich Context**: Page state, performance metrics, and content verification
- **Enhanced Debugging**: Element-specific screenshots and comprehensive metadata

---

**Ready for Production**: Complete web automation platform optimized for LLM agents and production workflows.