shortcut/cremote
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
ac71ce87979c70e7a2d6aae43f6e3e1a8bc358d0
cremote/mcp/LLM_USAGE_GUIDE.md
Josh at WLTechBlog 4f64dc879b bump
2025-10-19 10:07:47 -05:00

25 KiB
Raw Blame History

Cremote MCP Tools - LLM Usage Guide

Cremote MCP server provides 67 web automation and accessibility testing tools. All tools accept optional tab (tab ID) and timeout (seconds, default varies) parameters unless otherwise noted.

🚀 NEW: Optimized Workflows (Reduce Tool Calls by 50-70%)

Key Optimizations

  1. web_navigate_cremotemcp - Now supports cache clearing and data extraction in a single call
  2. Read-only tools - Many tools now accept optional url and clear_cache parameters to navigate first
  3. web_accessibility_full_audit_cremotemcp - NEW master tool: navigate + clear cache + full accessibility audit in one call

Before vs After Examples

Before (3 tool calls):

web_navigate_cremotemcp: {url: "https://example.com"}
web_clear_cache_cremotemcp: {}
web_extract_cremotemcp: {type: "source"}

After (1 tool call):

web_navigate_cremotemcp: {
  url: "https://example.com",
  clear_cache: true,
  extract: "source"
}

Before (3 tool calls for accessibility):

web_navigate_cremotemcp: {url: "https://example.com"}
web_clear_cache_cremotemcp: {}
web_page_accessibility_report_cremotemcp: {tests: ["all"]}

After (1 tool call):

web_accessibility_full_audit_cremotemcp: {
  url: "https://example.com",
  clear_cache: true,
  tests: ["all"]
}

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 (19): axe-core, contrast checks, keyboard nav, forms, WCAG compliance, media validation, OCR, animations, cross-page consistency, zoom/reflow tests, NEW: full audit with navigation

Core Automation Tools

web_navigate_cremotemcp

Navigate to URL with optional cache clearing, screenshot, and data extraction in a single call.

  • url (required): URL to navigate to
  • clear_cache (optional): boolean, clear cache before navigation (default: false)
  • screenshot (optional): boolean, take screenshot after navigation
  • extract (optional): "source", "element", or "javascript" - extract data after navigation
  • extract_selector (optional): CSS selector for element extraction (required when extract="element")
  • extract_code (optional): JavaScript code to execute (required when extract="javascript")
  • 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. Optionally navigate to URL first with cache clearing.

  • type (required): "source", "element", "javascript"
  • selector (optional): required for "element" type
  • code (optional): required for "javascript" type
  • url (optional): navigate to URL before extraction
  • clear_cache (optional): boolean, clear cache before operation (default: false)
  • 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. Optionally navigate to URL first with cache clearing.

  • selector (required): CSS selector
  • check_type (optional): "exists", "visible", "enabled", "focused", "selected", "all" (default: "exists")
  • url (optional): navigate to URL before checking element
  • clear_cache (optional): boolean, clear cache before operation (default: false)
  • Returns: JSON with boolean values for each check + count
  • Default timeout: 5s

web_element_attributes_cremotemcp

Get element attributes, properties, computed styles. Optionally navigate to URL first with cache clearing.

  • selector (required): CSS selector
  • attributes (optional): "all" or comma-separated list (default: "all")
  • Prefixes: none=HTML attr, style_=computed CSS, prop_=JS property
  • url (optional): navigate to URL before getting attributes
  • clear_cache (optional): boolean, clear cache before operation (default: false)
  • 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. Optionally navigate to URL first with cache clearing.

  • url (optional): navigate to URL before getting page info
  • clear_cache (optional): boolean, clear cache before operation (default: false)
  • 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. NOTE: Auto-injection happens automatically when using web_run_axe_cremotemcp or web_page_accessibility_report_cremotemcp, so manual injection is optional.

  • 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. Automatically injects axe-core if not already 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). Automatically injects axe-core if not already 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_accessibility_full_audit_cremotemcp ⭐ NEW

Master accessibility tool: Navigate to URL, clear cache, and run comprehensive accessibility assessment in a single call. Combines navigation, cache clearing, and all accessibility tests. Automatically injects axe-core if not already loaded.

  • url (required): URL to navigate to and test
  • clear_cache (optional): boolean, clear cache before navigation (default: true)
  • 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
  • Use this tool for single-call accessibility audits with navigation

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

Common Patterns

Basic Navigation

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

  1. Use optimized workflows: Combine navigation, cache clearing, and operations in single calls to reduce tool usage by 50-70%
  2. Use specific CSS selectors: Prefer input[name='email'] over input
  3. Batch operations: Use web_interact_multiple_cremotemcp or web_form_fill_bulk_cremotemcp for efficiency
  4. Accessibility testing: Use web_accessibility_full_audit_cremotemcp for single-call audits with navigation, or web_page_accessibility_report_cremotemcp for current page assessment
  5. File uploads: Use web_interact_cremotemcp with action="upload" - auto-handles host-to-container transfer
  6. Timeouts: Increase for slow pages or complex operations
  7. Screenshots: Use web_screenshot_enhanced_cremotemcp for metadata, web_screenshot_element_cremotemcp for specific elements

Optimized Workflow Examples

Single-Call Accessibility Audit

# Before (3 calls):
web_navigate_cremotemcp: {url: "https://example.com"}
web_clear_cache_cremotemcp: {}
web_page_accessibility_report_cremotemcp: {tests: ["all"]}

# After (1 call):
web_accessibility_full_audit_cremotemcp: {
  url: "https://example.com",
  clear_cache: true,
  tests: ["all"],
  standard: "WCAG21AA"
}

Navigate and Extract

# Before (2 calls):
web_navigate_cremotemcp: {url: "https://example.com"}
web_extract_cremotemcp: {type: "source"}

# After (1 call):
web_navigate_cremotemcp: {
  url: "https://example.com",
  extract: "source"
}

Navigate, Clear Cache, and Check Element

# Before (3 calls):
web_navigate_cremotemcp: {url: "https://example.com"}
web_clear_cache_cremotemcp: {}
web_element_check_cremotemcp: {selector: "#login-button", check_type: "visible"}

# After (1 call):
web_element_check_cremotemcp: {
  url: "https://example.com",
  clear_cache: true,
  selector: "#login-button",
  check_type: "visible"
}

Navigate, Clear Cache, and Get Page Info

# Before (3 calls):
web_navigate_cremotemcp: {url: "https://example.com"}
web_clear_cache_cremotemcp: {}
web_page_info_cremotemcp: {}

# After (1 call):
web_page_info_cremotemcp: {
  url: "https://example.com",
  clear_cache: true
}

Error Handling

Common errors:

  • Element not found: Verify selector with browser dev tools
  • Timeout: Increase timeout parameter for slow-loading content
  • Navigation failed: Check URL accessibility
  • File not found: Verify file paths for upload/download operations

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)