accessibility

mcp/LLM_USAGE_GUIDE.md

@@ -4,7 +4,7 @@ This guide explains how LLMs can use the cremote MCP (Model Context Protocol) to
 
 ## 🎉 Complete Web Automation Platform
 
-The cremote MCP server provides **27 comprehensive web automation tools** organized across 5 enhancement phases:
+The cremote MCP server provides **30 comprehensive web automation tools** organized across 6 enhancement phases:
 
 - **Core Tools (10)**: Essential web automation capabilities
 - **Phase 1 (2)**: Element state checking and conditional logic
@@ -12,8 +12,9 @@ The cremote MCP server provides **27 comprehensive web automation tools** organi
 - **Phase 3 (3)**: Form analysis and bulk operations
 - **Phase 4 (4)**: Page state and metadata tools
 - **Phase 5 (4)**: Enhanced screenshots and file management
+- **Phase 6 (3)**: Accessibility tree support for semantic understanding
 
-## Available Tools (27 Total)
+## Available Tools (30 Total)
 
 ### 1. `web_navigate_cremotemcp`
 Navigate to URLs and optionally take screenshots.
@@ -1337,12 +1338,89 @@ web_extract_multiple_cremotemcp:
     footer_text: "footer"
 ```
 
+### Phase 6: Accessibility Tree Support (3 Tools)
+
+#### `get_accessibility_tree_cremotemcp`
+Get the full accessibility tree for a page or with limited depth for semantic understanding.
+
+**Parameters:**
+- `tab` (optional): Tab ID, uses current tab if not specified
+- `depth` (optional): Maximum depth to retrieve, omit for full tree
+- `timeout` (optional): Timeout in seconds, default 5
+
+**Use Cases:**
+- Accessibility testing and compliance verification
+- Understanding page structure for screen readers
+- Semantic element discovery and analysis
+
+**Example:**
+```
+get_accessibility_tree_cremotemcp:
+  depth: 3
+  timeout: 10
+```
+
+#### `get_partial_accessibility_tree_cremotemcp`
+Get accessibility tree for a specific element and its relatives (ancestors, siblings, children).
+
+**Parameters:**
+- `selector`: CSS selector for the target element (required)
+- `tab` (optional): Tab ID, uses current tab if not specified
+- `fetch_relatives` (optional): Include relatives, default true
+- `timeout` (optional): Timeout in seconds, default 5
+
+**Use Cases:**
+- Focused accessibility analysis of specific components
+- Form accessibility structure analysis
+- Widget accessibility verification
+
+**Example:**
+```
+get_partial_accessibility_tree_cremotemcp:
+  selector: "form.login-form"
+  fetch_relatives: true
+  timeout: 10
+```
+
+#### `query_accessibility_tree_cremotemcp`
+Query accessibility tree for nodes matching specific criteria (accessible name, role, or scope).
+
+**Parameters:**
+- `tab` (optional): Tab ID, uses current tab if not specified
+- `selector` (optional): CSS selector to limit search scope
+- `accessible_name` (optional): Accessible name to match
+- `role` (optional): ARIA role to match (e.g., "button", "textbox", "link")
+- `timeout` (optional): Timeout in seconds, default 5
+
+**Use Cases:**
+- Find elements by their accessible names (what screen readers announce)
+- Locate elements by ARIA roles for semantic interaction
+- Accessibility-aware element discovery and testing
+
+**Examples:**
+```
+# Find all buttons on the page
+query_accessibility_tree_cremotemcp:
+  role: "button"
+
+# Find submit button by accessible name
+query_accessibility_tree_cremotemcp:
+  accessible_name: "Submit"
+  role: "button"
+
+# Find form controls within a specific form
+query_accessibility_tree_cremotemcp:
+  selector: "form.checkout"
+  role: "textbox"
+```
+
 ## Integration Notes
 
 - Tools use the `_cremotemcp` suffix to avoid naming conflicts
 - Responses include success status and descriptive messages
 - Screenshots are saved to `/tmp/` directory with timestamps
 - The underlying cremote daemon handles browser management
+- Accessibility tree tools provide semantic understanding of page structure
 
 ## Advanced Usage Examples
 
@@ -1483,6 +1561,40 @@ web_screenshot_enhanced_cremotemcp:
   full_page: true
 ```
 
+### Accessibility Testing and Semantic Automation
+```
+# Navigate to page for accessibility testing
+web_navigate_cremotemcp:
+  url: "https://myapp.com/form"
+  screenshot: true
+
+# Get full accessibility tree to analyze structure
+get_accessibility_tree_cremotemcp:
+  depth: 3
+  timeout: 10
+
+# Find form elements by accessible names (more robust than CSS selectors)
+query_accessibility_tree_cremotemcp:
+  accessible_name: "Email Address"
+  role: "textbox"
+
+# Fill form using accessibility-aware approach
+web_interact_cremotemcp:
+  action: "fill"
+  selector: "[aria-label='Email Address']"
+  value: "user@example.com"
+
+# Find and click submit button by accessible name
+query_accessibility_tree_cremotemcp:
+  accessible_name: "Submit Form"
+  role: "button"
+
+# Verify form accessibility structure
+get_partial_accessibility_tree_cremotemcp:
+  selector: "form"
+  fetch_relatives: true
+```
+
 ## 🎯 Best Practices for LLM Agents
 
 ### 1. **Use Batch Operations**
@@ -1505,10 +1617,16 @@ web_screenshot_enhanced_cremotemcp:
 - Leverage `console_logs_cremotemcp` for JavaScript error detection
 - Take `web_screenshot_enhanced_cremotemcp` with metadata for comprehensive documentation
 
+### 5. **Accessibility-Aware Automation**
+- Use `query_accessibility_tree_cremotemcp` to find elements by accessible names instead of fragile selectors
+- Verify accessibility compliance with `get_accessibility_tree_cremotemcp`
+- Test screen reader compatibility by analyzing semantic structure
+- Build more robust automation using ARIA roles and accessible names
+
 ## 🎉 Production Ready
 
-This comprehensive web automation platform provides **27 tools** across 5 enhancement phases, optimized specifically for LLM agents and production workflows. All tools include proper error handling, timeout management, and structured responses for reliable automation.
+This comprehensive web automation platform provides **30 tools** across 6 enhancement phases, optimized specifically for LLM agents and production workflows. All tools include proper error handling, timeout management, and structured responses for reliable automation.
 
 ---
 
-**Ready for Production**: Complete web automation platform with 27 tools, designed for maximum efficiency and reliability in LLM-driven workflows.
+**Ready for Production**: Complete web automation platform with 30 tools, designed for maximum efficiency and reliability in LLM-driven workflows.