1123 lines
37 KiB
Markdown
1123 lines
37 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
# First operation must be tab creation
|
|
web_manage_tabs_cremotemcp: {action: "open"}
|
|
```
|
|
|
|
#### Tab Lifecycle Management
|
|
|
|
1. **Creation**: Use `web_manage_tabs_cremotcp` with `action: "open"` to create a new tab
|
|
2. **Identification**: The system returns a unique tab ID that must be used for subsequent operations
|
|
3. **Switching**: Use `web_manage_tabs_cremotcp` with `action: "switch"` and the specific tab ID
|
|
4. **Listing**: Use `web_manage_tabs_cremotcp` with `action: "list"` to view all available tabs
|
|
5. **Closure**: Use `web_manage_tabs_cremotcp` with `action: "close"` to clean up resources
|
|
|
|
#### Setup Verification Procedures
|
|
|
|
Before starting any automated workflow, verify your setup:
|
|
|
|
```bash
|
|
# 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 Codes Related to Connection Issues
|
|
|
|
| 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Implement exponential backoff for retries
|
|
# Retry 1: timeout = 5s
|
|
# Retry 2: timeout = 10s
|
|
# Retry 3: timeout = 20s
|
|
```
|
|
|
|
---
|
|
|
|
## 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, 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
|
|
|
|
1. **Use specific CSS selectors**: Prefer `input[name='email']` over `input`
|
|
2. **Batch operations**: Use `web_interact_multiple_cremotemcp` or `web_form_fill_bulk_cremotemcp` for efficiency
|
|
3. **Accessibility testing**: Use `web_page_accessibility_report_cremotemcp` for comprehensive assessment with minimal tokens
|
|
4. **File uploads**: Use `web_interact_cremotemcp` with action="upload" - auto-handles host-to-container transfer
|
|
5. **Timeouts**: Increase for slow pages or complex operations
|
|
6. **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
|
|
|
|
#### DOM-Related Errors
|
|
```bash
|
|
# 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"}
|
|
```
|
|
|
|
#### Network-Related Errors
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```bash
|
|
# Navigate and test - axe-core auto-injects
|
|
web_navigate_cremotemcp: {url: "https://example.com"}
|
|
web_run_axe_cremotemcp: {run_only: ["wcag2aa"]}
|
|
```
|
|
|
|
#### Comprehensive Assessment
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
web_inject_axe_cremotemcp: {timeout: 15}
|
|
web_run_axe_cremotemcp: {}
|
|
```
|
|
|
|
#### Cross-Origin iframes
|
|
Test main page and same-origin iframes separately:
|
|
```bash
|
|
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:
|
|
```bash
|
|
web_inject_axe_cremotemcp: {version: "4.8.0"} # Latest
|
|
web_inject_axe_cremotemcp: {version: "4.6.3"} # Older browsers
|
|
```
|
|
|
|
### Comprehensive Testing Workflow
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
#### Navigation Tools
|
|
- `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
|
|
|
|
#### Successful Navigation Response
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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)
|
|
|