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