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.

## Available Tools

The cremote MCP server provides ten comprehensive web automation, file transfer, and console debugging tools:

### 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"
- `selector` (required): CSS selector for the target element
- `value` (optional): Value for fill/upload 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"
```

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

## 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']"
```

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

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

This documentation should help LLMs effectively use the cremote MCP tools for web automation tasks.