files

2025-08-14 18:55:38 -05:00
parent d6209cd34f
commit dc6b288aa4
19 changed files with 4127 additions and 0 deletions
--- a/mcp/LLM_USAGE_GUIDE.md
+++ b/mcp/LLM_USAGE_GUIDE.md
@@ -0,0 +1,379 @@
+# Cremote MCP Tools - LLM Usage Guide
+
+This guide explains how LLMs can use the cremote MCP (Model Context Protocol) tools for web automation tasks.
+
+## Available Tools
+
+The cremote MCP server provides six comprehensive web automation tools:
+
+### 1. `web_navigate_cremotemcp`
+Navigate to URLs and optionally take screenshots.
+
+**Parameters:**
+- `url` (required): The URL to navigate to
+- `screenshot` (optional): Boolean, take a screenshot after navigation
+- `tab` (optional): Specific tab ID to use
+- `timeout` (optional): Timeout in seconds (default: 5)
+
+**Example Usage:**
+```
+web_navigate_cremotemcp:
+  url: "https://example.com"
+  screenshot: true
+```
+
+### 2. `web_interact_cremotemcp`
+Interact with web elements through various actions.
+
+**Parameters:**
+- `action` (required): One of "click", "fill", "submit", "upload"
+- `selector` (required): CSS selector for the target element
+- `value` (optional): Value for fill/upload actions
+- `tab` (optional): Specific tab ID to use
+- `timeout` (optional): Timeout in seconds (default: 5)
+
+**Example Usage:**
+```
+web_interact_cremotemcp:
+  action: "click"
+  selector: "button.submit"
+
+web_interact_cremotemcp:
+  action: "fill"
+  selector: "input[name='email']"
+  value: "user@example.com"
+```
+
+### 3. `web_extract_cremotemcp`
+Extract data from web pages (HTML source, element content, or JavaScript execution).
+
+**Parameters:**
+- `type` (required): One of "source", "element", "javascript"
+- `selector` (optional): CSS selector (required for "element" type)
+- `code` (optional): JavaScript code (required for "javascript" type)
+- `tab` (optional): Specific tab ID to use
+- `timeout` (optional): Timeout in seconds (default: 5)
+
+**Example Usage:**
+```
+web_extract_cremotemcp:
+  type: "source"
+
+web_extract_cremotemcp:
+  type: "element"
+  selector: "div.content"
+
+web_extract_cremotemcp:
+  type: "javascript"
+  code: "document.title"
+```
+
+### 4. `web_screenshot_cremotemcp`
+Take screenshots of web pages.
+
+**Parameters:**
+- `output` (required): File path where screenshot will be saved
+- `full_page` (optional): Capture full page (default: false)
+- `tab` (optional): Specific tab ID to use
+- `timeout` (optional): Timeout in seconds (default: 5)
+
+**Example Usage:**
+```
+web_screenshot_cremotemcp:
+  output: "/tmp/page-screenshot.png"
+  full_page: true
+```
+
+### 5. `web_manage_tabs_cremotemcp`
+Manage browser tabs (open, close, list, switch).
+
+**Parameters:**
+- `action` (required): One of "open", "close", "list", "switch"
+- `tab` (optional): Tab ID (required for "close" and "switch" actions)
+- `timeout` (optional): Timeout in seconds (default: 5)
+
+**Example Usage:**
+```
+web_manage_tabs_cremotemcp:
+  action: "open"
+
+web_manage_tabs_cremotemcp:
+  action: "list"
+
+web_manage_tabs_cremotemcp:
+  action: "switch"
+  tab: "ABC123"
+```
+
+### 6. `web_iframe_cremotemcp`
+Switch iframe context for subsequent operations.
+
+**Parameters:**
+- `action` (required): One of "enter", "exit"
+- `selector` (optional): Iframe CSS selector (required for "enter" action)
+- `tab` (optional): Specific tab ID to use
+
+**Example Usage:**
+```
+web_iframe_cremotemcp:
+  action: "enter"
+  selector: "iframe#payment-form"
+
+web_iframe_cremotemcp:
+  action: "exit"
+```
+
+## Common Usage Patterns
+
+### 1. Basic Web Navigation
+```
+# Navigate to a website
+web_navigate_cremotemcp:
+  url: "https://example.com"
+  screenshot: true
+```
+
+### 2. Form Interaction Sequence
+```
+# 1. Navigate to the page
+web_navigate_cremotemcp:
+  url: "https://example.com/login"
+
+# 2. Fill username field
+web_interact_cremotemcp:
+  action: "fill"
+  selector: "input[name='username']"
+  value: "myusername"
+
+# 3. Fill password field
+web_interact_cremotemcp:
+  action: "fill"
+  selector: "input[name='password']"
+  value: "mypassword"
+
+# 4. Submit the form
+web_interact_cremotemcp:
+  action: "submit"
+  selector: "form"
+```
+
+### 3. Clicking Elements
+```
+# Click a button
+web_interact_cremotemcp:
+  action: "click"
+  selector: "button#submit-btn"
+
+# Click a link
+web_interact_cremotemcp:
+  action: "click"
+  selector: "a[href='/dashboard']"
+```
+
+## Best Practices for LLMs
+
+### 1. Always Start with Navigation
+Before interacting with elements, navigate to the target page:
+```
+web_navigate_cremotemcp:
+  url: "https://target-website.com"
+```
+
+### 2. Use Specific CSS Selectors
+Be as specific as possible with selectors to avoid ambiguity:
+- Good: `input[name='email']`, `button.primary-submit`
+- Avoid: `input`, `button`
+
+### 3. Take Screenshots for Debugging
+When troubleshooting or documenting, use screenshots:
+```
+web_navigate_cremotemcp:
+  url: "https://example.com"
+  screenshot: true
+```
+
+### 4. Handle Timeouts Appropriately
+For slow-loading pages, increase timeout:
+```
+web_navigate_cremotemcp:
+  url: "https://slow-website.com"
+  timeout: 10
+```
+
+### 5. Sequential Operations
+Perform operations in logical sequence:
+1. Navigate to page
+2. Fill required fields
+3. Submit forms
+4. Navigate to next page if needed
+
+## Error Handling
+
+### Common Error Scenarios:
+1. **Element not found**: Selector doesn't match any elements
+2. **Timeout**: Page takes too long to load or element to appear
+3. **Navigation failed**: URL is invalid or unreachable
+
+### Troubleshooting Tips:
+1. Verify the URL is correct and accessible
+2. Check CSS selectors using browser developer tools
+3. Increase timeout for slow-loading content
+4. Take screenshots to see current page state
+
+## Tab Management
+
+The tools automatically manage browser tabs:
+- If no tab is specified, a new tab is created automatically
+- Tab IDs are returned in responses for reference
+- Multiple tabs can be managed by specifying tab IDs
+
+## Security Considerations
+
+### Safe Practices:
+- Only navigate to trusted websites
+- Be cautious with form submissions
+- Avoid entering sensitive information in examples
+- Use screenshots sparingly to avoid exposing sensitive data
+
+### Limitations:
+- Cannot bypass CAPTCHA or other anti-automation measures
+- Subject to same-origin policy restrictions
+- May not work with heavily JavaScript-dependent sites
+
+## Example: Complete Web Automation Task
+
+Here's a complete example of automating a web form:
+
+```
+# Step 1: Navigate to the form page
+web_navigate_cremotemcp:
+  url: "https://example.com/contact"
+  screenshot: true
+
+# Step 2: Fill out the contact form
+web_interact_cremotemcp:
+  action: "fill"
+  selector: "input[name='name']"
+  value: "John Doe"
+
+web_interact_cremotemcp:
+  action: "fill"
+  selector: "input[name='email']"
+  value: "john@example.com"
+
+web_interact_cremotemcp:
+  action: "fill"
+  selector: "textarea[name='message']"
+  value: "Hello, this is a test message."
+
+# Step 3: Submit the form
+web_interact_cremotemcp:
+  action: "submit"
+  selector: "form#contact-form"
+
+# Step 4: Take a screenshot of the result
+web_navigate_cremotemcp:
+  url: "current"  # Stay on current page
+  screenshot: true
+```
+
+## 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
+
+## Advanced Usage Examples
+
+### Testing Web Applications
+```
+# Navigate to application
+web_navigate_cremotemcp:
+  url: "https://myapp.com/login"
+  screenshot: true
+
+# Test login functionality
+web_interact_cremotemcp:
+  action: "fill"
+  selector: "#username"
+  value: "testuser"
+
+web_interact_cremotemcp:
+  action: "fill"
+  selector: "#password"
+  value: "testpass"
+
+web_interact_cremotemcp:
+  action: "click"
+  selector: "button[type='submit']"
+
+# Verify successful login
+web_navigate_cremotemcp:
+  url: "current"
+  screenshot: true
+```
+
+### Data Extraction Workflows
+```
+# Navigate to data source
+web_navigate_cremotemcp:
+  url: "https://data-site.com/table"
+
+# Click through pagination or filters
+web_interact_cremotemcp:
+  action: "click"
+  selector: ".filter-button"
+
+# Take screenshot to document current state
+web_navigate_cremotemcp:
+  url: "current"
+  screenshot: true
+```
+
+### File Upload Testing
+```
+# Navigate to upload form
+web_navigate_cremotemcp:
+  url: "https://example.com/upload"
+
+# Upload a file
+web_interact_cremotemcp:
+  action: "upload"
+  selector: "input[type='file']"
+  value: "/path/to/test-file.pdf"
+
+# Submit the upload form
+web_interact_cremotemcp:
+  action: "click"
+  selector: "button.upload-submit"
+```
+
+## Tool Response Format
+
+Both tools return structured responses:
+
+**Success Response:**
+```
+"Successfully navigated to https://example.com in tab ABC123 (screenshot saved to /tmp/navigate-1234567890.png)"
+```
+
+**Error Response:**
+```
+"failed to load URL: context deadline exceeded"
+```
+
+## CSS Selector Best Practices
+
+### Recommended Selector Types:
+1. **ID selectors**: `#unique-id` (most reliable)
+2. **Name attributes**: `input[name='fieldname']`
+3. **Class combinations**: `.primary.button`
+4. **Attribute selectors**: `button[data-action='submit']`
+
+### Avoid These Selectors:
+1. **Generic tags**: `div`, `span`, `input` (too broad)
+2. **Position-based**: `:nth-child()` (fragile)
+3. **Text-based**: `:contains()` (not standard CSS)
+
+This documentation should help LLMs effectively use the cremote MCP tools for web automation tasks.