mcp features

2025-08-17 18:39:15 -05:00
parent e1f2c45c3a
commit e5f998e005
25 changed files with 10222 additions and 48 deletions
--- a/mcp/README.md
+++ b/mcp/README.md
@@ -2,26 +2,44 @@

 This is a Model Context Protocol (MCP) server that exposes cremote's web automation capabilities to LLMs and AI agents. Instead of using CLI commands, this server provides a structured API that maintains state and provides intelligent abstractions.

+## 🎉 Complete Web Automation Platform
+
+**27 comprehensive tools** across 5 enhancement phases, providing a complete web automation toolkit for LLM agents:
+
+- **Phase 1**: Element state checking and conditional logic (2 tools)
+- **Phase 2**: Enhanced data extraction and batch operations (4 tools)
+- **Phase 3**: Form analysis and bulk operations (3 tools)
+- **Phase 4**: Page state and metadata tools (4 tools)
+- **Phase 5**: Enhanced screenshots and file management (4 tools)
+- **Core Tools**: Essential web automation capabilities (10 tools)
+
 ## Features

 - **State Management**: Automatically tracks current tab, tab history, and iframe context
 - **Intelligent Abstractions**: High-level tools that combine multiple cremote operations
+- **Batch Operations**: Reduce round trips with bulk operations and multi-selector extraction
+- **Form Intelligence**: Complete form analysis and bulk filling capabilities
+- **Rich Context**: Page metadata, performance metrics, and content verification
+- **Enhanced Screenshots**: Element-specific and metadata-rich screenshot capture
+- **File Management**: Bulk file operations and automated cleanup
 - **Automatic Screenshots**: Optional screenshot capture for debugging and documentation
 - **Error Recovery**: Better error handling and context for LLMs
 - **Resource Management**: Automatic cleanup and connection management

 ## Quick Start for LLMs

-**For LLM agents**: See the comprehensive [LLM MCP Guide](LLM_MCP_GUIDE.md) for detailed usage instructions, examples, and best practices.
+**For LLM agents**: See the comprehensive [LLM Usage Guide](LLM_USAGE_GUIDE.md) for detailed usage instructions, examples, and best practices.

-## Available Tools
+## Available Tools (27 Total)

-### 1. `web_navigate`
+### Core Web Automation Tools (10 tools)
+
+#### 1. `web_navigate_cremotemcp`
 Navigate to URLs with optional screenshot capture.

 ```json
 {
-  "name": "web_navigate",
+  "name": "web_navigate_cremotemcp",
  "arguments": {
    "url": "https://example.com",
    "screenshot": true,
@@ -30,12 +48,12 @@ Navigate to URLs with optional screenshot capture.
 }
 ```

-### 2. `web_interact`
+#### 2. `web_interact_cremotemcp`
 Interact with web elements (click, fill, submit, upload).

 ```json
 {
-  "name": "web_interact",
+  "name": "web_interact_cremotemcp",
  "arguments": {
    "action": "fill",
    "selector": "#username",
@@ -45,12 +63,12 @@ Interact with web elements (click, fill, submit, upload).
 }
 ```

-### 3. `web_extract`
+#### 3. `web_extract_cremotemcp`
 Extract data from pages (source, element HTML, JavaScript execution).

 ```json
 {
-  "name": "web_extract",
+  "name": "web_extract_cremotemcp",
  "arguments": {
    "type": "javascript",
    "code": "document.title",
@@ -59,12 +77,12 @@ Extract data from pages (source, element HTML, JavaScript execution).
 }
 ```

-### 4. `web_screenshot`
+#### 4. `web_screenshot_cremotemcp`
 Take screenshots of the current page.

 ```json
 {
-  "name": "web_screenshot",
+  "name": "web_screenshot_cremotemcp",
  "arguments": {
    "output": "/tmp/page.png",
    "full_page": true,
@@ -73,12 +91,12 @@ Take screenshots of the current page.
 }
 ```

-### 5. `web_manage_tabs`
+#### 5. `web_manage_tabs_cremotemcp`
 Manage browser tabs (open, close, list, switch).

 ```json
 {
-  "name": "web_manage_tabs",
+  "name": "web_manage_tabs_cremotemcp",
  "arguments": {
    "action": "open",
    "timeout": 5
@@ -86,12 +104,12 @@ Manage browser tabs (open, close, list, switch).
 }
 ```

-### 6. `web_iframe`
+#### 6. `web_iframe_cremotemcp`
 Switch iframe context for subsequent operations.

 ```json
 {
-  "name": "web_iframe",
+  "name": "web_iframe_cremotemcp",
  "arguments": {
    "action": "enter",
    "selector": "iframe#payment-form"
@@ -99,6 +117,445 @@ Switch iframe context for subsequent operations.
 }
 ```

+#### 7. `file_upload_cremotemcp`
+Upload files from client to container for use in form uploads.
+
+```json
+{
+  "name": "file_upload_cremotemcp",
+  "arguments": {
+    "local_path": "/local/file.txt",
+    "container_path": "/tmp/file.txt"
+  }
+}
+```
+
+#### 8. `file_download_cremotemcp`
+Download files from container to client (e.g., downloaded files from browser).
+
+```json
+{
+  "name": "file_download_cremotemcp",
+  "arguments": {
+    "container_path": "/tmp/downloaded-file.pdf",
+    "local_path": "/local/downloaded-file.pdf"
+  }
+}
+```
+
+#### 9. `console_logs_cremotemcp`
+Get console logs from the browser tab.
+
+```json
+{
+  "name": "console_logs_cremotemcp",
+  "arguments": {
+    "tab": "tab-123",
+    "timeout": 5
+  }
+}
+```
+
+#### 10. `console_command_cremotemcp`
+Execute commands in the browser console.
+
+```json
+{
+  "name": "console_command_cremotemcp",
+  "arguments": {
+    "command": "document.getElementById('test').innerHTML = 'Hello World'",
+    "tab": "tab-123",
+    "timeout": 5
+  }
+}
+```
+
+### Phase 1: Element State and Checking Tools (2 tools)
+
+#### 11. `web_element_check_cremotemcp`
+Check element existence, visibility, enabled state, and other properties without interaction.
+
+```json
+{
+  "name": "web_element_check_cremotemcp",
+  "arguments": {
+    "selector": "#submit-button",
+    "check_type": "all",
+    "timeout": 5
+  }
+}
+```
+
+**Check Types:**
+- `exists`: Check if element exists in DOM
+- `visible`: Check if element is visible (not hidden)
+- `enabled`: Check if element is enabled (not disabled)
+- `focused`: Check if element has focus
+- `selected`: Check if element is selected (checkboxes, radio buttons)
+- `all`: Check all states above
+
+**Response includes:**
+```json
+{
+  "exists": true,
+  "visible": true,
+  "enabled": false,
+  "focused": false,
+  "selected": true,
+  "count": 1
+}
+```
+
+#### 12. `web_element_attributes_cremotemcp`
+Get element attributes, properties, and computed styles.
+
+```json
+{
+  "name": "web_element_attributes_cremotemcp",
+  "arguments": {
+    "selector": "#user-profile",
+    "attributes": "all",
+    "timeout": 5
+  }
+}
+```
+
+**Attribute Options:**
+- `all`: Get common attributes, properties, and styles
+- `"id,class,href"`: Comma-separated list of specific attributes
+- `"style_display,style_color"`: Computed styles (prefix with `style_`)
+- `"prop_textContent,prop_value"`: JavaScript properties (prefix with `prop_`)
+
+**Example Response:**
+```json
+{
+  "id": "user-profile",
+  "class": "profile-card active",
+  "data-user-id": "12345",
+  "textContent": "John Doe",
+  "style_display": "block",
+  "style_color": "rgb(0, 0, 0)"
+}
+```
+
+### Phase 2: Enhanced Data Extraction Tools (4 tools)
+
+#### 13. `web_extract_multiple_cremotemcp`
+Extract data from multiple selectors in a single call for improved efficiency.
+
+```json
+{
+  "name": "web_extract_multiple_cremotemcp",
+  "arguments": {
+    "selectors": {
+      "title": "h1",
+      "price": ".price",
+      "description": ".product-description"
+    },
+    "timeout": 5
+  }
+}
+```
+
+#### 14. `web_extract_links_cremotemcp`
+Extract all links from a page with powerful filtering options.
+
+```json
+{
+  "name": "web_extract_links_cremotemcp",
+  "arguments": {
+    "container_selector": "nav",
+    "href_pattern": "https://.*",
+    "text_pattern": ".*Download.*",
+    "timeout": 5
+  }
+}
+```
+
+#### 15. `web_extract_table_cremotemcp`
+Extract table data as structured JSON with optional header processing.
+
+```json
+{
+  "name": "web_extract_table_cremotemcp",
+  "arguments": {
+    "selector": "#data-table",
+    "include_headers": true,
+    "timeout": 5
+  }
+}
+```
+
+#### 16. `web_extract_text_cremotemcp`
+Extract text content with optional pattern matching and different extraction types.
+
+```json
+{
+  "name": "web_extract_text_cremotemcp",
+  "arguments": {
+    "selector": ".content",
+    "pattern": "\\d{3}-\\d{3}-\\d{4}",
+    "extract_type": "textContent",
+    "timeout": 5
+  }
+}
+```
+
+### Phase 3: Form Analysis and Bulk Operations (3 tools)
+
+#### 17. `web_form_analyze_cremotemcp`
+Analyze forms completely to understand their structure, fields, and submission requirements.
+
+```json
+{
+  "name": "web_form_analyze_cremotemcp",
+  "arguments": {
+    "selector": "#registration-form",
+    "timeout": 10
+  }
+}
+```
+
+#### 18. `web_interact_multiple_cremotemcp`
+Perform multiple interactions in a single call for efficient batch operations.
+
+```json
+{
+  "name": "web_interact_multiple_cremotemcp",
+  "arguments": {
+    "interactions": [
+      {"selector": "#username", "action": "fill", "value": "testuser"},
+      {"selector": "#password", "action": "fill", "value": "testpass"},
+      {"selector": "#remember-me", "action": "check"},
+      {"selector": "#login-btn", "action": "click"}
+    ],
+    "timeout": 10
+  }
+}
+```
+
+#### 19. `web_form_fill_bulk_cremotemcp`
+Fill entire forms with key-value pairs in a single operation.
+
+```json
+{
+  "name": "web_form_fill_bulk_cremotemcp",
+  "arguments": {
+    "form_selector": "#contact-form",
+    "fields": {
+      "name": "John Doe",
+      "email": "john@example.com",
+      "message": "Hello, this is a test message."
+    },
+    "timeout": 10
+  }
+}
+```
+
+### Phase 4: Page State and Metadata Tools (4 tools)
+
+#### 20. `web_page_info_cremotemcp`
+Get comprehensive page metadata and state information.
+
+```json
+{
+  "name": "web_page_info_cremotemcp",
+  "arguments": {
+    "tab": "tab-123",
+    "timeout": 5
+  }
+}
+```
+
+Returns detailed page information including title, URL, loading state, domain, protocol, and browser status.
+
+#### 21. `web_viewport_info_cremotemcp`
+Get viewport and scroll information.
+
+```json
+{
+  "name": "web_viewport_info_cremotemcp",
+  "arguments": {
+    "tab": "tab-123",
+    "timeout": 5
+  }
+}
+```
+
+Returns viewport dimensions, scroll position, device pixel ratio, and orientation.
+
+#### 22. `web_performance_metrics_cremotemcp`
+Get page performance metrics.
+
+```json
+{
+  "name": "web_performance_metrics_cremotemcp",
+  "arguments": {
+    "tab": "tab-123",
+    "timeout": 5
+  }
+}
+```
+
+Returns performance data including load times, resource counts, and memory usage.
+
+#### 23. `web_content_check_cremotemcp`
+Check for specific content types and loading states.
+
+```json
+{
+  "name": "web_content_check_cremotemcp",
+  "arguments": {
+    "type": "images",
+    "tab": "tab-123",
+    "timeout": 5
+  }
+}
+```
+
+Supported content types: `images`, `scripts`, `styles`, `forms`, `links`, `iframes`, `errors`.
+
+### Phase 5: Enhanced Screenshot and File Management (4 tools)
+
+#### 24. `web_screenshot_element_cremotemcp`
+Take a screenshot of a specific element on the page.
+
+```json
+{
+  "name": "web_screenshot_element_cremotemcp",
+  "arguments": {
+    "selector": "#main-content",
+    "output": "/tmp/element-screenshot.png",
+    "tab": "tab-123",
+    "timeout": 5
+  }
+}
+```
+
+Automatically scrolls the element into view and captures a screenshot of just that element.
+
+#### 25. `web_screenshot_enhanced_cremotemcp`
+Take an enhanced screenshot with metadata.
+
+```json
+{
+  "name": "web_screenshot_enhanced_cremotemcp",
+  "arguments": {
+    "output": "/tmp/enhanced-screenshot.png",
+    "full_page": true,
+    "tab": "tab-123",
+    "timeout": 5
+  }
+}
+```
+
+Returns screenshot metadata including timestamp, URL, title, viewport size, and file information.
+
+#### 26. `file_operations_bulk_cremotemcp`
+Perform bulk file operations (upload/download multiple files).
+
+```json
+{
+  "name": "file_operations_bulk_cremotemcp",
+  "arguments": {
+    "operation": "upload",
+    "files": [
+      {
+        "local_path": "/local/file1.txt",
+        "container_path": "/tmp/file1.txt"
+      },
+      {
+        "local_path": "/local/file2.txt",
+        "container_path": "/tmp/file2.txt"
+      }
+    ],
+    "timeout": 30
+  }
+}
+```
+
+Supports both "upload" and "download" operations with detailed success/failure reporting.
+
+#### 27. `file_management_cremotemcp`
+Manage files (cleanup, list, get info).
+
+```json
+{
+  "name": "file_management_cremotemcp",
+  "arguments": {
+    "operation": "cleanup",
+    "pattern": "/tmp/cremote-*",
+    "max_age": "24"
+  }
+}
+```
+
+Operations: `cleanup` (remove old files), `list` (list files), `info` (get file details).
+
+## 🎉 Complete Enhancement Summary
+
+All 5 phases of the MCP enhancement plan have been successfully implemented, delivering a comprehensive web automation platform with **27 tools** organized across the following capabilities:
+
+### ✅ Phase 1: Element State and Checking (2 tools)
+**Enables conditional logic without timing issues**
+- `web_element_check_cremotemcp`: Check existence, visibility, enabled state, count elements
+- `web_element_attributes_cremotemcp`: Get attributes, properties, computed styles
+
+**Benefits**: LLMs can make decisions based on page state, prevent errors from trying to interact with non-existent elements, enable conditional workflows.
+
+### ✅ Phase 2: Enhanced Data Extraction (4 tools)
+**Dramatically improves data gathering efficiency**
+- `web_extract_multiple_cremotemcp`: Extract from multiple selectors in one call
+- `web_extract_links_cremotemcp`: Extract all links with filtering options
+- `web_extract_table_cremotemcp`: Extract table data as structured JSON
+- `web_extract_text_cremotemcp`: Extract text with pattern matching
+
+**Benefits**: Reduces multiple round trips to single calls, provides structured data ready for LLM processing, enables comprehensive page analysis.
+
+### ✅ Phase 3: Form Analysis and Bulk Operations (3 tools)
+**Streamlines form handling workflows with 10x efficiency**
+- `web_form_analyze_cremotemcp`: Analyze forms completely
+- `web_interact_multiple_cremotemcp`: Batch interactions
+- `web_form_fill_bulk_cremotemcp`: Fill entire forms with key-value pairs
+
+**Benefits**: Complete forms in 1-2 calls instead of 10+, form intelligence provides complete understanding before interaction, error prevention through field validation.
+
+### ✅ Phase 4: Page State and Metadata Tools (4 tools)
+**Provides rich context about page state for better debugging and monitoring**
+- `web_page_info_cremotemcp`: Get page metadata and loading state
+- `web_viewport_info_cremotemcp`: Get viewport and scroll information
+- `web_performance_metrics_cremotemcp`: Get performance data
+- `web_content_check_cremotemcp`: Check for specific content types
+
+**Benefits**: Better debugging and monitoring capabilities, performance optimization insights, content loading verification, rich page state context for LLM decision making.
+
+### ✅ Phase 5: Enhanced Screenshot and File Management (4 tools)
+**Improves debugging and file handling**
+- `web_screenshot_element_cremotemcp`: Screenshot specific elements
+- `web_screenshot_enhanced_cremotemcp`: Screenshots with metadata
+- `file_operations_bulk_cremotemcp`: Bulk file operations
+- `file_management_cremotemcp`: Temporary file cleanup
+
+**Benefits**: Better debugging with targeted screenshots, improved file handling workflows, automatic resource management, enhanced visual debugging capabilities.
+
+## Key Benefits for LLM Agents
+
+### 🚀 **Efficiency Gains**
+- **10x Form Efficiency**: Complete forms in 1-2 calls instead of 10+ individual interactions
+- **Batch Operations**: Multiple data extractions and interactions in single calls
+- **Reduced Round Trips**: Comprehensive tools minimize API call overhead
+
+### 🧠 **Intelligence & Context**
+- **Conditional Logic**: Element checking enables smart decision making without timing issues
+- **Rich Page Context**: Complete page state, performance metrics, and content verification
+- **Form Intelligence**: Complete form analysis before interaction prevents errors
+
+### 🛠 **Enhanced Capabilities**
+- **Visual Debugging**: Element-specific screenshots and enhanced metadata
+- **File Management**: Bulk operations and automated cleanup
+- **Error Prevention**: State checking and validation before actions
+- **Resource Management**: Automatic cleanup and connection handling
+
 ## Installation & Usage

 ### Prerequisites
@@ -172,58 +629,64 @@ All tool responses include:
 }
 ```

-## Example Workflow
+## Example Workflows

+### Basic Login Workflow (Traditional Approach)
 ```json
 // 1. Navigate to a page
 {
-  "name": "web_navigate",
+  "name": "web_navigate_cremotemcp",
  "arguments": {
    "url": "https://example.com/login",
    "screenshot": true
  }
 }

-// 2. Fill login form
+// 2. Check if login form exists
 {
-  "name": "web_interact",
+  "name": "web_element_check_cremotemcp",
  "arguments": {
-    "action": "fill",
-    "selector": "#username",
-    "value": "testuser"
+    "selector": "#login-form",
+    "check_type": "exists"
  }
 }

+// 3. Fill login form using bulk operations
 {
-  "name": "web_interact",
+  "name": "web_form_fill_bulk_cremotemcp",
  "arguments": {
-    "action": "fill",
-    "selector": "#password",
-    "value": "password123"
+    "form_selector": "#login-form",
+    "fields": {
+      "username": "testuser",
+      "password": "password123"
+    }
  }
 }

-// 3. Submit form
+// 4. Submit and verify
 {
-  "name": "web_interact",
+  "name": "web_interact_cremotemcp",
  "arguments": {
    "action": "click",
    "selector": "#login-button"
  }
 }

-// 4. Extract result
+// 5. Extract multiple results at once
 {
-  "name": "web_extract",
+  "name": "web_extract_multiple_cremotemcp",
  "arguments": {
-    "type": "javascript",
-    "code": "document.querySelector('.welcome-message')?.textContent"
+    "selectors": {
+      "welcome_message": ".welcome-message",
+      "user_name": ".user-profile .name",
+      "last_login": ".user-info .last-login"
+    }
  }
 }

-// 5. Take final screenshot
+// 6. Take enhanced screenshot with metadata
 {
-  "name": "web_screenshot",
+  "name": "web_screenshot_enhanced_cremotemcp",
  "arguments": {
    "output": "/tmp/login-success.png",
    "full_page": true
@@ -231,15 +694,95 @@ All tool responses include:
 }
 ```

+### Advanced E-commerce Data Extraction Workflow
+```json
+// 1. Navigate and check page state
+{
+  "name": "web_navigate_cremotemcp",
+  "arguments": {
+    "url": "https://shop.example.com/products",
+    "screenshot": true
+  }
+}
+
+// 2. Get page performance metrics
+{
+  "name": "web_performance_metrics_cremotemcp",
+  "arguments": {}
+}
+
+// 3. Extract all product data in one call
+{
+  "name": "web_extract_multiple_cremotemcp",
+  "arguments": {
+    "selectors": {
+      "product_titles": ".product-card h3",
+      "prices": ".product-card .price",
+      "ratings": ".product-card .rating",
+      "availability": ".product-card .stock-status"
+    }
+  }
+}
+
+// 4. Extract all product links with filtering
+{
+  "name": "web_extract_links_cremotemcp",
+  "arguments": {
+    "container_selector": ".product-grid",
+    "href_pattern": ".*/product/.*",
+    "text_pattern": ".*"
+  }
+}
+
+// 5. Check if more products are loading
+{
+  "name": "web_content_check_cremotemcp",
+  "arguments": {
+    "type": "scripts"
+  }
+}
+```
+
 ## Benefits Over CLI

+### 🎯 **Enhanced Efficiency**
 - **State Management**: No need to manually track tab IDs
- **Better Error Context**: Rich error information for debugging
- **Automatic Screenshots**: Built-in screenshot capture for documentation
+- **Batch Operations**: 10x efficiency with bulk form filling and multi-selector extraction
 - **Intelligent Defaults**: Smart parameter handling and fallbacks
 - **Resource Cleanup**: Automatic management of tabs and files
+
+### 🔍 **Better Intelligence**
+- **Conditional Logic**: Element checking enables smart decision making
+- **Rich Context**: Page state, performance metrics, and content verification
+- **Form Intelligence**: Complete form analysis before interaction
+- **Error Prevention**: State validation before actions
+
+### 🛠 **Advanced Capabilities**
+- **Enhanced Screenshots**: Element-specific and metadata-rich capture
+- **File Management**: Bulk operations and automated cleanup
+- **Better Error Context**: Rich error information for debugging
 - **Structured Responses**: Consistent, parseable response format

+## 🎉 Production Ready
+
+This comprehensive web automation platform is **production ready** with:
+
+- **27 Tools**: Complete coverage of web automation needs
+- **5 Enhancement Phases**: Systematic capability building from basic to advanced
+- **Extensive Testing**: All tools validated and documented
+- **LLM Optimized**: Designed specifically for AI agent workflows
+- **Backward Compatible**: All existing tools continue to work unchanged
+
+### 📊 **Capability Matrix**
+| Category | Tools | Key Benefits |
+|----------|-------|--------------|
+| **Core Web Automation** | 10 tools | Navigation, interaction, extraction, screenshots, tabs, iframes, files, console |
+| **Element Intelligence** | 2 tools | Conditional logic, state checking, attribute inspection |
+| **Data Extraction** | 4 tools | Batch extraction, structured data, pattern matching, table processing |
+| **Form Automation** | 3 tools | Form analysis, bulk filling, batch interactions |
+| **Page Intelligence** | 4 tools | Page state, performance metrics, content verification, viewport info |
+| **Enhanced Capabilities** | 4 tools | Element screenshots, enhanced metadata, bulk file ops, file management |
+
 ## Development

 To extend the MCP server with new tools:
@@ -250,3 +793,7 @@ To extend the MCP server with new tools:
 4. Update this documentation

 The server is designed to be easily extensible while maintaining consistency with the cremote client library.
+
+---
+
+**🚀 Ready for Production**: Complete web automation platform with 27 tools across 5 enhancement phases, optimized for LLM agents and production workflows.