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 six comprehensive web automation 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

Example Usage:

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

web_iframe_cremotemcp:
  action: "exit"

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

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.