Files

Josh at WLTechBlog 1b01b1e857 bump

2025-10-16 11:26:23 -05:00

37 KiB

Raw Blame History

Cremote MCP Tools - LLM Usage Guide

Cremote MCP server provides 66 web automation and accessibility testing tools. All tools accept optional tab (tab ID) and timeout (seconds, default varies) parameters unless otherwise noted. Note that you do need to open a tab before any other tools will function.

Prerequisites

Tab Management Requirements

CRITICAL: You must explicitly create a browser tab before performing any other operations. Tab creation is the first step in any workflow.

# First operation must be tab creation
web_manage_tabs_cremotemcp: {action: "open"}

Tab Lifecycle Management

Creation: Use web_manage_tabs_cremotcp with action: "open" to create a new tab
Identification: The system returns a unique tab ID that must be used for subsequent operations
Switching: Use web_manage_tabs_cremotcp with action: "switch" and the specific tab ID
Listing: Use web_manage_tabs_cremotcp with action: "list" to view all available tabs
Closure: Use web_manage_tabs_cremotcp with action: "close" to clean up resources

Setup Verification Procedures

Before starting any automated workflow, verify your setup:

# 1. Check MCP server connection
version_cremotemcp: {}

# 2. Create a test tab
web_manage_tabs_cremotemcp: {action: "open"}

# 3. Navigate to a simple page
web_navigate_cremotemcp: {url: "https://example.com"}

# 4. Verify page loaded
web_page_info_cremotemcp: {}

System Requirements and Dependencies

Browser Engine: Chromium-based browser engine (automatically provided)
Memory: Minimum 512MB available RAM for basic operations
Storage: 100MB+ free space for screenshots and file operations
Network: Stable internet connection for web page access
Permissions: File system access for upload/download operations

Common Setup Issues

Tab Not Created Error: Always create a tab before any other operations
Timeout Errors: Increase timeout values for slow-loading pages
File Access Errors: Verify file paths and permissions for upload/download operations

Tool Categories

Core Automation (12): navigate, interact, extract, screenshot, tabs, iframe, console, file operations
Element Inspection (2): check state, get attributes
Data Extraction (4): multiple selectors, links, tables, text patterns
Forms (3): analyze, bulk fill, batch interact
Page Intelligence (4): page info, viewport, performance, content check
Screenshots (3): basic, element, enhanced with metadata
File Management (3): upload, download, bulk operations
Cache Control (5): enable/disable/clear cache, cookies, storage, all site data
Mouse/Keyboard (11): drag-drop (3 variants), right/double/middle/hover click, mouse move, scroll wheel, key combos, special keys, modifier clicks
Accessibility Tree (3): full tree, partial tree, query by role/name
Accessibility Testing (18): axe-core, contrast checks, keyboard nav, forms, WCAG compliance, media validation, OCR, animations, cross-page consistency, zoom/reflow tests

Core Automation Tools

web_navigate_cremotemcp

Navigate to URL, optionally take screenshot.

url (required): URL to navigate to
screenshot (optional): boolean, take screenshot after navigation
Default timeout: 5s

web_interact_cremotemcp

Interact with elements: click, fill, submit, upload, select.

action (required): "click", "fill", "submit", "upload", "select"
selector (required): CSS selector
value (optional): for fill/upload/select actions
Note: upload action auto-transfers files from host to container
Default timeout: 5s

web_extract_cremotemcp

Extract page data: source HTML, element content, or execute JavaScript.

type (required): "source", "element", "javascript"
selector (optional): required for "element" type
code (optional): required for "javascript" type
Default timeout: 5s

web_screenshot_cremotemcp

Take page screenshots with zoom/viewport options.

output (required): file path for screenshot
full_page (optional): boolean, capture full page (default: false)
width (optional): viewport width in pixels
height (optional): viewport height in pixels
zoom_level (optional): zoom level (e.g., 1.0, 2.0, 4.0)
Default timeout: 5s

web_manage_tabs_cremotemcp

Manage browser tabs: open, close, list, switch.

action (required): "open", "close", "list", "switch"
tab (optional): required for "close" and "switch"
Default timeout: 5s

web_iframe_cremotemcp

Switch iframe context for subsequent operations.

action (required): "enter", "exit"
selector (optional): iframe CSS selector, required for "enter"
Default timeout: 5s

console_command_cremotemcp

Execute JavaScript in browser console.

command (required): JavaScript code to execute
inject_library (optional): library name (axe, jquery, lodash, moment, underscore) or URL
Default timeout: 5s

console_logs_cremotemcp

Get console logs from browser tab.

clear (optional): boolean, clear logs after retrieval (default: false)
Default timeout: 5s

file_upload_cremotemcp

Upload file from client to container. Note: web_interact_cremotemcp with action="upload" now auto-handles transfers.

local_path (required): path on client machine
container_path (optional): path in container (defaults to /tmp/filename)

file_download_cremotemcp

Download file from container to client.

container_path (required): path in container
local_path (required): path on client machine

file_operations_bulk_cremotemcp

Bulk upload/download multiple files.

operation (required): "upload" or "download"
files (required): array of {local_path, container_path} objects
Default timeout: 30s

file_management_cremotemcp

File management: cleanup, list, get info.

operation (required): "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)

Element Inspection Tools

web_element_check_cremotemcp

Check element state: exists, visible, enabled, focused, selected.

selector (required): CSS selector
check_type (optional): "exists", "visible", "enabled", "focused", "selected", "all" (default: "exists")
Returns: JSON with boolean values for each check + count
Default timeout: 5s

web_element_attributes_cremotemcp

Get element attributes, properties, computed styles.

selector (required): CSS selector
attributes (optional): "all" or comma-separated list (default: "all")
Prefixes: none=HTML attr, style_=computed CSS, prop_=JS property
Default timeout: 5s

Data Extraction Tools

web_extract_multiple_cremotemcp

Extract from multiple selectors in one call.

selectors (required): object with label:selector pairs
Returns: {results: {label: content}, errors: {}}
Default timeout: 5s

web_extract_links_cremotemcp

Extract all links with filtering.

container_selector (optional): limit search to container
href_pattern (optional): regex to filter by href
text_pattern (optional): regex to filter by text
Returns: array of {href, text, title, target} + count
Default timeout: 5s

web_extract_table_cremotemcp

Extract table as structured JSON.

selector (required): table CSS selector
include_headers (optional): boolean (default: true)
Returns: {headers, rows, data (structured), count}
Default timeout: 5s

web_extract_text_cremotemcp

Extract text with pattern matching.

selector (required): CSS selector
pattern (optional): regex pattern to match
extract_type (optional): "text", "innerText", "textContent" (default: "textContent")
Returns: {text, matches, count}
Default timeout: 5s

Form Tools

web_form_analyze_cremotemcp

Analyze form structure, fields, requirements.

selector (required): form CSS selector
Returns: {action, method, fields[], field_count, can_submit, submit_text}
Default timeout: 5s

web_form_fill_bulk_cremotemcp

Fill entire form with key-value pairs.

fields (required): object mapping field names/selectors to values
form_selector (optional): form CSS selector
Returns: {filled_fields[], success_count, error_count, total_count}
Default timeout: 5s

web_interact_multiple_cremotemcp

Batch interactions in one call.

interactions (required): array of {selector, action, value} objects
Actions: "click", "fill", "select", "check", "uncheck"
Returns: {results[], success_count, error_count, total_count}
Default timeout: 5s

Page Intelligence Tools

web_page_info_cremotemcp

Get page metadata and state.

Returns: {title, url, loading_state, ready_state, domain, protocol, charset, cookie_enabled, online_status}
Default timeout: 5s

web_viewport_info_cremotemcp

Get viewport and scroll information.

Returns: {width, height, scroll_x, scroll_y, scroll_width, scroll_height, device_pixel_ratio, orientation}
Default timeout: 5s

web_performance_metrics_cremotemcp

Get page performance metrics.

Returns: {navigation_start, load_event_end, load_time, dom_load_time, resource_count, js_heap_size_used}
Default timeout: 5s

web_content_check_cremotemcp

Check content types and loading states.

type (required): "images", "scripts", "styles", "forms", "links", "iframes", "errors"
Returns: type-specific metrics (e.g., images_loaded, images_total)
Default timeout: 5s

Screenshot Tools

web_screenshot_element_cremotemcp

Screenshot specific element.

selector (required): element CSS selector
output (required): file path
Auto-scrolls element into view
Default timeout: 5s

web_screenshot_enhanced_cremotemcp

Screenshot with metadata.

output (required): file path
full_page (optional): boolean (default: false)
Returns: {timestamp, url, title, viewport_size, full_page, file_path, file_size, resolution}
Default timeout: 5s

Cache Control Tools

web_disable_cache_cremotemcp

Disable browser cache for tab. No required parameters. Default timeout: 5s

web_enable_cache_cremotemcp

Enable browser cache for tab. No required parameters. Default timeout: 5s

web_clear_cache_cremotemcp

Clear browser cache. No required parameters. Default timeout: 5s

web_clear_cookies_cremotemcp

Clear cookies. No required parameters. Default timeout: 5s

web_clear_storage_cremotemcp

Clear web storage (localStorage, sessionStorage, IndexedDB). No required parameters. Default timeout: 5s

web_clear_all_site_data_cremotemcp

Clear all site data (cookies, storage, cache). No required parameters. Default timeout: 5s

Mouse/Keyboard Tools

web_drag_and_drop_cremotemcp

Drag element to target element with HTML5 events.

source (required): source element CSS selector
target (required): target element CSS selector
Default timeout: 5s

web_drag_and_drop_coordinates_cremotemcp

Drag element to specific coordinates.

source (required): source element CSS selector
x (required): target X coordinate
y (required): target Y coordinate
Default timeout: 5s

web_drag_and_drop_offset_cremotemcp

Drag element by relative offset.

source (required): source element CSS selector
offset_x (required): horizontal offset in pixels
offset_y (required): vertical offset in pixels
Default timeout: 5s

web_right_click_cremotemcp

Right-click on element to open context menu.

selector (required): element CSS selector
Default timeout: 5s

web_double_click_cremotemcp

Double-click on element for file operations or text selection.

selector (required): element CSS selector
Default timeout: 5s

web_middle_click_cremotemcp

Middle-click on element (typically opens links in new tabs).

selector (required): element CSS selector
Default timeout: 5s

web_hover_cremotemcp

Hover over element to trigger tooltips or dropdowns.

selector (required): element CSS selector
Default timeout: 5s

web_mouse_move_cremotemcp

Move mouse to coordinates without clicking.

x (required): X coordinate
y (required): Y coordinate
Default timeout: 5s

web_scroll_wheel_cremotemcp

Scroll with mouse wheel at coordinates.

x (required): X coordinate
y (required): Y coordinate
delta_y (required): vertical scroll delta (negative=up, positive=down)
delta_x (optional): horizontal scroll delta (default: 0)
Default timeout: 5s

web_key_combination_cremotemcp

Send key combinations (Ctrl+C, Alt+Tab, Shift+Enter, etc).

keys (required): key combination string
Default timeout: 5s

web_special_key_cremotemcp

Send special keys (Enter, Escape, Tab, F1-F12, Arrow keys, Home, End, PageUp, PageDown, Delete, Backspace).

key (required): special key name
Default timeout: 5s

web_modifier_click_cremotemcp

Click with modifier keys (Ctrl+click, Shift+click, Alt+click).

selector (required): element CSS selector
modifiers (required): modifier keys (e.g., "Ctrl", "Shift", "Alt", "Ctrl+Shift")
Default timeout: 5s

Accessibility Tree Tools

get_accessibility_tree_cremotemcp

Get full or depth-limited accessibility tree.

depth (optional): maximum depth to retrieve (omit for full tree)
include_contrast (optional): boolean, include contrast check data (default: false)
Default timeout: 5s

get_partial_accessibility_tree_cremotemcp

Get accessibility tree for specific element and relatives.

selector (required): element CSS selector
fetch_relatives (optional): boolean, include ancestors/siblings/children (default: true)
Default timeout: 5s

query_accessibility_tree_cremotemcp

Query accessibility tree by role/name.

selector (optional): CSS selector to limit scope
accessible_name (optional): accessible name to match
role (optional): ARIA role to match (e.g., "button", "textbox", "link")
Default timeout: 5s

Accessibility Testing Tools

version_cremotemcp

Get MCP server and daemon version information. No parameters required.

web_inject_axe_cremotemcp

Inject axe-core accessibility testing library. Auto-injection: Manual injection optional - web_run_axe_cremotemcp and web_page_accessibility_report_cremotemcp auto-inject if needed.

version (optional): axe-core version (default: "4.8.0")
Default timeout: 10s

web_run_axe_cremotemcp

Run axe-core tests, return violations/passes/incomplete/inapplicable. Auto-injects axe-core if not loaded.

run_only (optional): array of tags (e.g., ["wcag2a", "wcag2aa", "wcag21aa"])
rules (optional): specific rules configuration object
Returns: {url, timestamp, test_engine, violations[], passes[], incomplete[], inapplicable[]}
Default timeout: 30s

web_contrast_check_cremotemcp

Check color contrast ratios for text elements, verify WCAG AA/AAA compliance.

selector (optional): CSS selector for specific elements (defaults to all text)
Returns: {total_elements, passed_aa, failed_aa, passed_aaa, failed_aaa, unable_to_check, elements[]}
Default timeout: 10s

web_contrast_audit_cremotemcp

Smart contrast checking with prioritized failures and pattern detection. Returns only failures, significantly reducing token usage.

priority_selectors (optional): array of CSS selectors to prioritize (e.g., ["button", "a", "nav"])
threshold (optional): "AA" or "AAA" (default: "AA")
Returns: {pass_rate, critical_failures (top 20), failure_patterns}
Default timeout: 10s

web_gradient_contrast_check_cremotemcp

Check contrast for text on gradient backgrounds using ImageMagick. Samples 100 points, reports worst-case ratio.

selector (required): CSS selector for element with gradient background
Returns: {selector, text_color, darkest_bg_color, lightest_bg_color, worst_contrast, best_contrast, is_large_text, required_aa, required_aaa, passes_aa, passes_aaa, sample_points}
Default timeout: 10s

web_keyboard_test_cremotemcp

Test keyboard navigation: tab order, focus indicators, keyboard traps.

Returns: {total_interactive, focusable, not_focusable, no_focus_indicator, keyboard_traps, issues[], tab_order[]}
Default timeout: 15s

web_keyboard_audit_cremotemcp

Keyboard navigation assessment with actionable summary. Reduces token usage by ~80% vs full test.

check_focus_indicators (optional): boolean (default: true)
check_tab_order (optional): boolean (default: true)
check_keyboard_traps (optional): boolean (default: true)
Returns: summary of issues by type/severity with recommendations
Default timeout: 15s

web_enhanced_accessibility_cremotemcp

Enhanced accessibility tree analysis with ARIA validation, role verification, relationship checking (WCAG 1.3.1, 4.1.2).

Returns: {total_elements, elements_with_issues, aria_violations, role_violations, relationship_issues, landmark_issues, elements[]}
Default timeout: 10s

web_form_accessibility_audit_cremotemcp

Comprehensive form accessibility check: labels, ARIA, keyboard, contrast.

form_selector (optional): CSS selector for specific form (defaults to all forms)
Returns: summarized form analysis with issues by category
Default timeout: 10s

web_page_accessibility_report_cremotemcp

Comprehensive page assessment combining axe-core, contrast, keyboard, forms. Token-efficient format (~4k tokens vs ~80k). Auto-injects axe-core if not loaded.

tests (optional): array of test types (e.g., ["wcag", "contrast", "keyboard", "forms"]) or ["all"]
standard (optional): WCAG standard (default: "WCAG21AA")
include_screenshots (optional): boolean (default: false)
Returns: {compliance_status, overall_score, legal_risk, issues by severity, contrast_summary, keyboard_summary, form_summary, estimated_remediation_hours}
Default timeout: 30s

web_media_validation_cremotemcp

Validate video/audio for WCAG compliance: captions, audio descriptions, transcripts, controls, autoplay.

Returns: {videos[], audios[], embedded_players[], transcript_links[], critical_violations, total_violations, warnings}
Default timeout: 10s

web_hover_focus_test_cremotemcp

Test WCAG 1.4.13 compliance for hover/focus content: dismissibility, hoverability, persistence.

Returns: {total_elements, elements_with_issues, passed_elements, issues[], tested_elements[]}
Default timeout: 10s

web_text_in_images_cremotemcp

Detect text in images using Tesseract OCR, flag WCAG 1.4.5/1.4.9 violations.

Returns: {total_images, images_with_text, images_without_text, violations, warnings, images[]}
Default timeout: 30s (OCR processing)

web_animation_flash_cremotemcp

Detect animations and flashing content that may trigger seizures (WCAG 2.3.1, 2.2.2).

Returns: {total_animations, flashing_content, rapid_animations, autoplay_animations, violations, warnings, elements[]}
Default timeout: 10s

web_cross_page_consistency_cremotemcp

Check consistency of navigation, headers, footers, landmarks across pages (WCAG 3.2.3, 3.2.4).

urls (required): array of URLs to check
Returns: {pages_checked, consistency_issues, navigation_issues, structure_issues, pages[]}
Default timeout: 10s per page

web_zoom_test_cremotemcp

Test page at zoom levels (100%, 200%, 400%), verify WCAG 1.4.4 and 1.4.10 compliance.

zoom_levels (optional): array of zoom levels (default: [1.0, 2.0, 4.0])
Returns: {zoom_levels[], issues[]}
Default timeout: 10s per level

web_reflow_test_cremotemcp

Test responsive design at WCAG breakpoints (320px, 1280px), verify WCAG 1.4.10 reflow compliance.

widths (optional): array of viewport widths in pixels (default: [320, 1280])
Returns: {breakpoints[], issues[]}
Default timeout: 10s per width

Connection Management

Connection Stability Considerations

The cremote MCP server maintains persistent browser sessions, but connections may be interrupted by:

Network instability: Intermittent connectivity issues
Long-running operations: Operations exceeding default timeout values
Resource constraints: Insufficient memory or CPU resources
Browser crashes: Unhandled exceptions in the browser engine

Error Code	Description	Recovery Action
`CONN_TIMEOUT`	Connection timeout exceeded	Increase timeout parameter or retry
`TAB_NOT_FOUND`	Specified tab ID doesn't exist	Create new tab or verify tab ID
`BROWSER_CRASHED`	Browser process has crashed	Restart MCP server and create new tab
`RESOURCE_EXHAUSTED`	Insufficient system resources	Close unused tabs or increase available memory
`NAVIGATION_FAILED`	Page navigation failed	Verify URL accessibility and network connection

Recovery Procedures for Interrupted Operations

Tab Recovery

# Check available tabs
web_manage_tabs_cremotemcp: {action: "list"}

# If no tabs exist, create a new one
web_manage_tabs_cremotemcp: {action: "open"}

Workflow Recovery

# Resume navigation
web_navigate_cremotemcp: {url: "https://example.com", timeout: 10}

# Verify page state
web_page_info_cremotemcp: {}

Retry Mechanism Guidance

Safe to Retry (Idempotent Operations)

web_navigate_cremotemcp
web_screenshot_cremotemcp
web_extract_* operations
web_element_check_cremotemcp
web_page_info_cremotemcp

Use Caution When Retrying

web_interact_cremotemcp with "click" action
web_form_fill_bulk_cremotemcp
File upload operations
Form submission operations

Recommended Retry Pattern

# Implement exponential backoff for retries
# Retry 1: timeout = 5s
# Retry 2: timeout = 10s
# Retry 3: timeout = 20s

Common Patterns

web_navigate_cremotemcp: {url: "https://example.com", screenshot: true}

Form Completion

# Analyze form structure
web_form_analyze_cremotemcp: {selector: "#contact-form"}

# Fill all fields
web_form_fill_bulk_cremotemcp: {
  form_selector: "#contact-form",
  fields: {name: "John Doe", email: "john@example.com", message: "Test"}
}

# Submit
web_interact_cremotemcp: {action: "click", selector: "button[type='submit']"}

Batch Operations

web_interact_multiple_cremotemcp: {
  interactions: [
    {selector: "#agree", action: "check"},
    {selector: "#country", action: "select", value: "US"},
    {selector: "#submit", action: "click"}
  ]
}

File Upload (Auto-Transfer)

# Modern approach - auto-transfers from host
web_interact_cremotemcp: {
  action: "upload",
  selector: "input[type='file']",
  value: "/home/user/document.pdf"
}

Accessibility Assessment

# Comprehensive report (~4k tokens, auto-injects axe-core)
web_page_accessibility_report_cremotemcp: {
  tests: ["all"],
  standard: "WCAG21AA",
  timeout: 30
}

# Or individual tests
web_contrast_audit_cremotemcp: {priority_selectors: ["button", "a", "nav"]}
web_keyboard_audit_cremotemcp: {}
web_form_accessibility_audit_cremotemcp: {form_selector: "form"}

Data Extraction

# Extract multiple elements
web_extract_multiple_cremotemcp: {
  selectors: {
    title: "h1",
    price: ".price",
    description: ".description"
  }
}

# Extract table
web_extract_table_cremotemcp: {selector: "#data-table", include_headers: true}

# Extract links
web_extract_links_cremotemcp: {container_selector: "nav", href_pattern: "https://.*"}

Best Practices

Use specific CSS selectors: Prefer input[name='email'] over input
Batch operations: Use web_interact_multiple_cremotemcp or web_form_fill_bulk_cremotemcp for efficiency
Accessibility testing: Use web_page_accessibility_report_cremotemcp for comprehensive assessment with minimal tokens
File uploads: Use web_interact_cremotemcp with action="upload" - auto-handles host-to-container transfer
Timeouts: Increase for slow pages or complex operations
Screenshots: Use web_screenshot_enhanced_cremotemcp for metadata, web_screenshot_element_cremotemcp for specific elements

Error Handling

Comprehensive Error Codes and Meanings

Error Code	Category	Description	Recovery Procedure
`ELEMENT_NOT_FOUND`	DOM	Selector doesn't match any elements	Verify selector with browser dev tools
`ELEMENT_NOT_VISIBLE`	DOM	Element exists but is not visible	Scroll to element or check visibility conditions
`ELEMENT_NOT_INTERACTABLE`	DOM	Element exists but cannot be interacted with	Check if element is disabled or obscured
`TIMEOUT_EXCEEDED`	Network	Operation exceeded timeout limit	Increase timeout parameter or check network
`NAVIGATION_FAILED`	Network	Page navigation failed	Verify URL accessibility and network connection
`CONNECTION_LOST`	Network	Connection to browser lost	Re-establish connection and create new tab
`TAB_NOT_FOUND`	Session	Specified tab ID doesn't exist	Create new tab or verify tab ID
`BROWSER_CRASHED`	System	Browser process has crashed	Restart MCP server and create new tab
`RESOURCE_EXHAUSTED`	System	Insufficient system resources	Close unused tabs or increase available memory
`FILE_NOT_FOUND`	File	Specified file doesn't exist	Verify file paths for upload/download operations
`FILE_ACCESS_DENIED`	File	Insufficient permissions for file operation	Check file permissions and access rights
`INVALID_PARAMETER`	Validation	Parameter validation failed	Check parameter types and values
`IFRAME_NOT_FOUND`	DOM	Specified iframe doesn't exist	Verify iframe selector or check if iframe loaded
`SCRIPT_EXECUTION_FAILED`	JavaScript	JavaScript execution failed	Check script syntax and execution context

Recovery Procedures for Specific Error Types

# For ELEMENT_NOT_FOUND errors
# 1. Verify element exists
web_element_check_cremotemcp: {selector: "your-selector", check_type: "exists"}

# 2. Wait for element to load
console_command_cremotemcp: {command: "await new Promise(r => setTimeout(r, 2000))"}

# 3. Try alternative selectors
web_element_check_cremotemcp: {selector: "alternative-selector", check_type: "exists"}

# For TIMEOUT_EXCEEDED errors
# 1. Increase timeout
web_navigate_cremotemcp: {url: "https://example.com", timeout: 30}

# 2. Check network connectivity
web_page_info_cremotemcp: {}

# 3. Clear cache and retry
web_clear_cache_cremotemcp: {}
web_navigate_cremotemcp: {url: "https://example.com", timeout: 30}

File Operation Errors

# For FILE_NOT_FOUND errors
# 1. Check file exists on host
file_management_cremotemcp: {operation: "info", pattern: "/path/to/file"}

# 2. Verify file permissions
file_upload_cremotemcp: {local_path: "/path/to/file", container_path: "/tmp/test"}

# 3. Try alternative file path
file_upload_cremotemcp: {local_path: "/alternative/path/file", container_path: "/tmp/test"}

Idempotent Operations (Safe to Retry)

The following operations can be safely retried without side effects:

Navigation: web_navigate_cremotemcp
Screenshots: web_screenshot_cremotemcp, web_screenshot_element_cremotemcp
Data Extraction: web_extract_* operations
Element Inspection: web_element_check_cremotemcp, web_element_attributes_cremotemcp
Page Information: web_page_info_cremotemcp, web_viewport_info_cremotemcp
Accessibility Analysis: web_run_axe_cremotemcp, web_contrast_check_cremotemcp
Console Operations: console_command_cremotemcp, console_logs_cremotemcp

Error Propagation in Multi-Step Workflows

When building multi-step workflows, implement proper error handling:

# Example workflow with error handling
try {
  # Step 1: Navigate
  web_navigate_cremotemcp: {url: "https://example.com"}
} catch (error) {
  if (error.code === "NAVIGATION_FAILED") {
    # Retry with different approach
    web_clear_cache_cremotemcp: {}
    web_navigate_cremotemcp: {url: "https://example.com", timeout: 15}
  } else {
    # Propagate error
    throw error
  }
}

# Step 2: Check element exists
elementExists = web_element_check_cremotemcp: {selector: "#target"}
if (!elementExists.exists) {
  throw {code: "ELEMENT_NOT_FOUND", message: "Target element not found"}
}

# Step 3: Interact with element
web_interact_cremotemcp: {action: "click", selector: "#target"}

Error Response Format

All errors follow this consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "selector": "selector-that-failed",
      "timeout": 5000,
      "timestamp": "2023-10-16T16:16:57.262Z"
    }
  }
}

Axe-core Integration

Auto-Injection (Recommended)

NEW: Axe-core automatically injects when needed. Manual injection is optional.

Simplified Workflow

# Navigate and test - axe-core auto-injects
web_navigate_cremotemcp: {url: "https://example.com"}
web_run_axe_cremotemcp: {run_only: ["wcag2aa"]}

Comprehensive Assessment

# Single call - auto-injects and tests
web_page_accessibility_report_cremotemcp: {
  tests: ["all"],
  standard: "WCAG21AA"
}

Manual Injection (Optional)

For explicit control over injection timing or version:

# 1. Navigate to target page
web_navigate_cremotemcp: {url: "https://example.com"}

# 2. Manually inject specific version
web_inject_axe_cremotemcp: {version: "4.8.0"}

# 3. Run tests
web_run_axe_cremotemcp: {run_only: ["wcag2aa"]}

Injection Failure Handling

Auto-injection handles most scenarios automatically. For edge cases:

CSP Restrictions

If Content Security Policy blocks injection, manually inject before testing:

web_inject_axe_cremotemcp: {timeout: 15}
web_run_axe_cremotemcp: {}

Cross-Origin iframes

Test main page and same-origin iframes separately:

web_run_axe_cremotemcp: {}  # Main page
web_iframe_cremotemcp: {action: "enter", selector: "iframe"}
web_run_axe_cremotemcp: {}  # iframe content
web_iframe_cremotemcp: {action: "exit"}

Version Control

Specify axe-core version for compatibility:

web_inject_axe_cremotemcp: {version: "4.8.0"}  # Latest
web_inject_axe_cremotemcp: {version: "4.6.3"}  # Older browsers

Comprehensive Testing Workflow

# Navigate and test - auto-injects axe-core
web_navigate_cremotemcp: {url: "https://example.com"}
web_page_accessibility_report_cremotemcp: {
  tests: ["all"],
  standard: "WCAG21AA",
  timeout: 30
}

Return Value Documentation

Standard Response Format

All tools follow a consistent response format for successful operations:

{
  "success": true,
  "result": {
    // Tool-specific data
  },
  "metadata": {
    "tab_id": "tab-identifier",
    "timestamp": "2023-10-16T16:19:33.708Z",
    "execution_time_ms": 1234
  }
}

Error Response Format

All errors follow this consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "selector": "selector-that-failed",
      "timeout": 5000,
      "timestamp": "2023-10-16T16:19:33.708Z"
    }
  }
}

Response Size Limitations

Standard responses: Limited to 1MB of JSON data
Large data operations: Automatically paginated or truncated
Screenshot operations: Files handled separately from JSON response
Accessibility reports: Comprehensive reports limited to ~4k tokens for efficiency

Tool-Specific Return Values

web_navigate_cremotemcp: {url, title, timestamp, loading_state}
web_manage_tabs_cremotemcp: {tabs[], active_tab, total_count}

Interaction Tools

web_interact_cremotemcp: {action_performed, element_info, timestamp}
web_interact_multiple_cremotemcp: {results[], success_count, error_count, total_count}

Data Extraction Tools

web_extract_*: {data, count, extraction_time, source_info}
web_extract_table_cremotemcp: {headers, rows, structured_data, row_count}
web_extract_multiple_cremotemcp: {results: {label: content}, errors: {}}

Element Inspection Tools

web_element_check_cremotemcp: {exists, visible, enabled, focused, selected, count}
web_element_attributes_cremotemcp: {attributes: {}, properties: {}, styles: {}}

Accessibility Tools

web_run_axe_cremotemcp: {violations[], passes[], incomplete[], inapplicable[]}
web_page_accessibility_report_cremotemcp: {compliance_status, overall_score, issues_by_severity}

File Operations

file_upload_cremotemcp: {file_size, upload_time, destination_path}
file_download_cremotemcp: {file_size, download_time, source_path}
file_operations_bulk_cremotemcp: {results[], success_count, error_count, total_size}

Examples of Successful and Failed Responses

{
  "success": true,
  "result": {
    "url": "https://example.com",
    "title": "Example Domain",
    "loading_state": "complete",
    "timestamp": "2023-10-16T16:19:33.708Z"
  },
  "metadata": {
    "tab_id": "tab-123",
    "timestamp": "2023-10-16T16:19:33.708Z",
    "execution_time_ms": 1234
  }
}

Failed Element Interaction Response

{
  "success": false,
  "error": {
    "code": "ELEMENT_NOT_FOUND",
    "message": "Selector '#nonexistent-element' did not match any elements",
    "details": {
      "selector": "#nonexistent-element",
      "timeout": 5000,
      "timestamp": "2023-10-16T16:19:33.708Z"
    }
  }
}

File Operations

File Transfer Mechanisms

Host to Container Transfer

File transfers from host to container are automatically handled for upload operations:

# Automatic transfer detection
web_interact_cremotemcp: {
  action: "upload",
  selector: "input[type='file']",
  value: "/home/user/document.pdf"  # Host path - auto-transferred
}

Container to Host Transfer

Files generated in the container (screenshots, downloads) are automatically transferred to host:

# Screenshot auto-transfer
web_screenshot_cremotemcp: {
  output: "/home/user/screenshot.png"  # Host destination
}

Supported Formats and Size Limitations

Supported File Formats

Images: PNG, JPG, JPEG, GIF, BMP, WebP
Documents: PDF, DOC, DOCX, TXT, CSV
Archives: ZIP, TAR, GZIP
Data: JSON, XML, YAML

Size Limitations

Single file upload: Maximum 50MB
Bulk operations: Maximum 100MB total
Screenshot files: Typically 1-5MB depending on page size
Large file handling: Automatic chunking for files >10MB

File Permission Requirements

Host System Requirements

Read permissions: Required for upload operations
Write permissions: Required for download operations
Directory access: Must have access to specified file paths

Container System Requirements

Temporary storage: /tmp directory for intermediate operations
Upload directory: Configurable upload location
Download directory: Configurable download location

Common Permission Issues and Solutions

# Check file permissions before upload
file_management_cremotemcp: {
  operation: "info",
  pattern: "/path/to/file"
}

# Verify write permissions for downloads
file_management_cremotemcp: {
  operation: "list",
  pattern: "/download/directory"
}

File Cleanup and Management

Automatic Cleanup

Temporary files: Automatically cleaned after 24 hours
Session files: Cleaned when tab is closed
Error files: Cleaned after failed operations

Manual Cleanup Options

# Clean files older than 24 hours
file_management_cremotemcp: {
  operation: "cleanup",
  max_age: "24"
}

# Clean specific pattern
file_management_cremotemcp: {
  operation: "cleanup",
  pattern: "*.tmp"
}

# List all files before cleanup
file_management_cremotemcp: {
  operation: "list",
  pattern: "*"
}

Bulk File Operations

Efficient Bulk Upload

file_operations_bulk_cremotemcp: {
  operation: "upload",
  files: [
    {local_path: "/home/user/doc1.pdf", container_path: "/tmp/doc1.pdf"},
    {local_path: "/home/user/doc2.pdf", container_path: "/tmp/doc2.pdf"},
    {local_path: "/home/user/image.png", container_path: "/tmp/image.png"}
  ],
  timeout: 30
}

Efficient Bulk Download

file_operations_bulk_cremotemcp: {
  operation: "download",
  files: [
    {container_path: "/tmp/result1.pdf", local_path: "/home/user/result1.pdf"},
    {container_path: "/tmp/result2.pdf", local_path: "/home/user/result2.pdf"}
  ],
  timeout: 30
}

File Operation Error Handling

Common File Operation Errors

FILE_NOT_FOUND: Specified file doesn't exist
FILE_ACCESS_DENIED: Insufficient permissions
FILE_TOO_LARGE: File exceeds size limitations
UNSUPPORTED_FORMAT: File format not supported
TRANSFER_FAILED: Network or transfer interruption

Recovery Procedures

# For transfer failures, retry with smaller chunks
file_operations_bulk_cremotemcp: {
  operation: "upload",
  files: [
    {local_path: "/home/user/large-file.pdf", container_path: "/tmp/large-file.pdf"}
  ],
  timeout: 60  # Increase timeout for large files
}

Notes

All tools return structured JSON responses
Tab management is automatic if no tab ID specified
File upload operations now auto-detect host paths and transfer to container
Accessibility tools follow WCAG 2.1 Level AA/AAA standards
Screenshot tools automatically copy files from container to host
Default timeouts vary by tool complexity (5-30 seconds)

37 KiB Raw Blame History

Cremote MCP Tools - LLM Usage Guide

Prerequisites

Tab Management Requirements

Tab Lifecycle Management

Setup Verification Procedures

System Requirements and Dependencies

Common Setup Issues

Tool Categories

Core Automation Tools

web_navigate_cremotemcp

web_interact_cremotemcp

web_extract_cremotemcp

web_screenshot_cremotemcp

web_manage_tabs_cremotemcp

web_iframe_cremotemcp

console_command_cremotemcp

console_logs_cremotemcp

file_upload_cremotemcp

file_download_cremotemcp

file_operations_bulk_cremotemcp

file_management_cremotemcp

Element Inspection Tools

web_element_check_cremotemcp

web_element_attributes_cremotemcp

Data Extraction Tools

web_extract_multiple_cremotemcp

web_extract_links_cremotemcp

web_extract_table_cremotemcp

web_extract_text_cremotemcp

Form Tools

web_form_analyze_cremotemcp

web_form_fill_bulk_cremotemcp

web_interact_multiple_cremotemcp

Page Intelligence Tools

web_page_info_cremotemcp

web_viewport_info_cremotemcp

web_performance_metrics_cremotemcp

web_content_check_cremotemcp

Screenshot Tools

web_screenshot_element_cremotemcp

web_screenshot_enhanced_cremotemcp

Cache Control Tools

web_disable_cache_cremotemcp

web_enable_cache_cremotemcp

web_clear_cache_cremotemcp

web_clear_cookies_cremotemcp

web_clear_storage_cremotemcp

web_clear_all_site_data_cremotemcp

Mouse/Keyboard Tools

web_drag_and_drop_cremotemcp

web_drag_and_drop_coordinates_cremotemcp

web_drag_and_drop_offset_cremotemcp

web_right_click_cremotemcp

web_double_click_cremotemcp

web_middle_click_cremotemcp

web_hover_cremotemcp

web_mouse_move_cremotemcp

web_scroll_wheel_cremotemcp

web_key_combination_cremotemcp

web_special_key_cremotemcp

web_modifier_click_cremotemcp

Accessibility Tree Tools

get_accessibility_tree_cremotemcp

get_partial_accessibility_tree_cremotemcp

query_accessibility_tree_cremotemcp

Accessibility Testing Tools

version_cremotemcp

web_inject_axe_cremotemcp

web_run_axe_cremotemcp

web_contrast_check_cremotemcp

web_contrast_audit_cremotemcp

web_gradient_contrast_check_cremotemcp

web_keyboard_test_cremotemcp

web_keyboard_audit_cremotemcp

web_enhanced_accessibility_cremotemcp

web_form_accessibility_audit_cremotemcp

web_page_accessibility_report_cremotemcp

web_media_validation_cremotemcp

web_hover_focus_test_cremotemcp

37 KiB

Raw Blame History