terminator-mcp-agent 0.12.17 → 0.13.0

package/README.md

@@ -2,14 +2,29 @@
 
 <!-- BADGES:START -->
 
-[<img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522terminator-mcp-agent%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522terminator-mcp-agent%2540latest%2522%255D%257D%257D)
-[<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522terminator-mcp-agent%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522terminator-mcp-agent%2540latest%2522%255D%257D%257D)
-[<img alt="Install in Cursor" src="https://img.shields.io/badge/Cursor-Cursor?style=flat-square&label=Install%20Server&color=22272e">](https://cursor.com/install-mcp?name=terminator-mcp-agent&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInRlcm1pbmF0b3ItbWNwLWFnZW50QGxhdGVzdCJdfQ%3D%3D)
+[<img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522terminator-mcp-agent%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522terminator-mcp-agent%2522%255D%257D%257D)
+[<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522terminator-mcp-agent%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522terminator-mcp-agent%2522%255D%257D%257D)
 
 <!-- BADGES:END -->
 
 A Model Context Protocol (MCP) server that provides desktop GUI automation capabilities using the [Terminator](https://github.com/mediar-ai/terminator) library. This server enables LLMs and agentic clients to interact with Windows, macOS, and Linux applications through structured accessibility APIs—no vision models or screenshots required.
 
+## Quick Install
+
+### Cursor
+
+Copy and paste this URL into your browser's address bar:
+
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=terminator-mcp-agent&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInRlcm1pbmF0b3ItbWNwLWFnZW50Il19
+```
+
+Or install manually:
+
+1. Open Cursor Settings (`Cmd/Ctrl + ,`)
+2. Go to the MCP tab
+3. Add server with command: `npx -y terminator-mcp-agent`
+
 ### HTTP Endpoints (when running with `-t http`)
 
 - `GET /health`: Always returns 200 while the process is alive.
@@ -102,15 +117,15 @@ Tool call wrapper format (`workflow.json`):
 }
 ```
 
-**JavaScript Execution in Workflows:**
+**Code Execution in Workflows (engine mode):**
 
-Execute custom JavaScript code with access to desktop automation APIs:
+Execute custom JavaScript or Python with access to desktop automation APIs via `run_command`:
 
 ```yaml
 steps:
-  - tool_name: run_javascript
+  - tool_name: run_command
     arguments:
-      engine: "nodejs"
+      engine: "javascript"
       script: |
         // Access desktop automation APIs
         const elements = await desktop.locator('role:button').all();
@@ -212,6 +227,140 @@ For simpler tasks, you can record your own actions to generate a baseline workfl
 3.  **Stop and Save**: Call `record_workflow` with `action: "stop"`. This returns a complete workflow JSON file containing all your recorded actions.
 4.  **Refine and Parse**: The recorded workflow is a great starting point. You can then refine the selectors for robustness, add a final step to capture the UI tree, and attach an `output_parser` to extract structured data, just as you would in the iterative workflow.
 
+### Browser DOM Inspection
+
+The `execute_browser_script` tool enables direct JavaScript execution in browser contexts, providing access to the full HTML DOM. This is particularly useful when you need information not available in the accessibility tree.
+
+#### When to Use DOM vs Accessibility Tree
+
+**Use Accessibility Tree (default) when:**
+- Navigating and interacting with UI elements
+- Working with semantic page structure
+- Building reliable automation workflows
+- Performance is critical (faster, cleaner data)
+
+**Use DOM Inspection when:**
+- Extracting data attributes, meta tags, or hidden inputs
+- Debugging why elements aren't appearing in accessibility tree
+- Scraping structured data from specific HTML patterns
+- Validating complete page structure or SEO elements
+
+#### Basic DOM Retrieval Patterns
+
+```javascript
+// Get full HTML DOM (be mindful of size limits)
+execute_browser_script({
+  selector: "role:Window|name:Google Chrome",
+  script: "document.documentElement.outerHTML"
+})
+
+// Get structured page information
+execute_browser_script({
+  selector: "role:Window|name:Google Chrome", 
+  script: `({
+    url: window.location.href,
+    title: document.title,
+    html: document.documentElement.outerHTML,
+    bodyText: document.body.innerText.substring(0, 1000)
+  })`
+})
+
+// Extract specific data (forms, hidden inputs, meta tags)
+execute_browser_script({
+  selector: "role:Window|name:Google Chrome",
+  script: `({
+    forms: Array.from(document.forms).map(f => ({
+      id: f.id,
+      action: f.action,
+      method: f.method,
+      inputs: Array.from(f.elements).map(e => ({
+        name: e.name,
+        type: e.type,
+        value: e.type === 'password' ? '[REDACTED]' : e.value
+      }))
+    })),
+    hiddenInputs: Array.from(document.querySelectorAll('input[type="hidden"]')).map(e => ({
+      name: e.name,
+      value: e.value
+    })),
+    metaTags: Array.from(document.querySelectorAll('meta')).map(m => ({
+      name: m.name || m.property,
+      content: m.content
+    }))
+  })`
+})
+```
+
+#### Handling Large DOMs
+
+The MCP protocol has response size limits (~30KB). For large DOMs, use truncation strategies:
+
+```javascript
+execute_browser_script({
+  selector: "role:Window|name:Google Chrome",
+  script: `
+    const html = document.documentElement.outerHTML;
+    const maxLength = 30000;
+    
+    ({
+      url: window.location.href,
+      title: document.title,
+      html: html.length > maxLength 
+        ? html.substring(0, maxLength) + '... [truncated at ' + maxLength + ' chars]'
+        : html,
+      totalLength: html.length,
+      truncated: html.length > maxLength
+    })
+  `
+})
+```
+
+#### Advanced DOM Analysis
+
+```javascript
+// Analyze page structure and extract semantic content
+execute_browser_script({
+  selector: "role:Window|name:Google Chrome",
+  script: `
+    // Remove scripts and styles for cleaner analysis
+    const clonedDoc = document.documentElement.cloneNode(true);
+    clonedDoc.querySelectorAll('script, style, noscript').forEach(el => el.remove());
+    
+    ({
+      // Page metrics
+      domElementCount: document.querySelectorAll('*').length,
+      formCount: document.forms.length,
+      linkCount: document.links.length,
+      imageCount: document.images.length,
+      
+      // Semantic structure
+      headings: Array.from(document.querySelectorAll('h1,h2,h3')).map(h => ({
+        level: h.tagName,
+        text: h.innerText.substring(0, 100)
+      })),
+      
+      // Clean HTML without scripts/styles
+      cleanHtml: clonedDoc.outerHTML.substring(0, 20000),
+      
+      // Data extraction
+      jsonLd: Array.from(document.querySelectorAll('script[type="application/ld+json"]'))
+        .map(s => { try { return JSON.parse(s.textContent); } catch { return null; } })
+        .filter(Boolean)
+    })
+  `
+})
+```
+
+#### Important Notes
+
+1. **Chrome Extension Required**: The `execute_browser_script` tool requires the Terminator browser extension to be installed. See the installation workflow examples for automated setup.
+
+2. **Security Considerations**: Be cautious when extracting sensitive data. The examples above redact password fields and you should follow similar practices.
+
+3. **Performance**: DOM operations are synchronous and can be slow on large pages. Consider using specific selectors rather than traversing the entire DOM.
+
+4. **Error Handling**: Always wrap complex DOM operations in try-catch blocks and return meaningful error messages.
+
 ## Local Development
 
 To build and test the agent from the source code:
@@ -294,11 +443,14 @@ terminator mcp run workflow.yml --url http://localhost:3000/mcp
 **Solution**: Verify JavaScript execution and API access:
 
 ```bash
-# Test basic JavaScript execution
-terminator mcp exec run_javascript '{"script": "return {test: true};"}'
+# Test basic JavaScript execution via run_command engine mode
+terminator mcp exec run_command '{"engine": "javascript", "run": "return {test: true};"}'
+
+# Test desktop API access with node engine
+terminator mcp exec run_command '{"engine": "node", "run": "const elements = await desktop.locator(\\\"role:button\\\").all(); return {count: elements.length};"}'
 
-# Test desktop API access with nodejs engine
-terminator mcp exec run_javascript '{"engine": "nodejs", "script": "const elements = await desktop.locator(\"role:button\").all(); return {count: elements.length};"}'
+# Test Python engine
+terminator mcp exec run_command '{"engine": "python", "run": "return {\\\"py\\\": True}"}'
 
 # Debug with verbose logging
 terminator mcp run workflow.yml --verbose

package/package.json

@@ -15,10 +15,10 @@
   ],
   "name": "terminator-mcp-agent",
   "optionalDependencies": {
-    "terminator-mcp-darwin-arm64": "0.12.17",
-    "terminator-mcp-darwin-x64": "0.12.17",
-    "terminator-mcp-linux-x64-gnu": "0.12.17",
-    "terminator-mcp-win32-x64-msvc": "0.12.17"
+    "terminator-mcp-darwin-arm64": "0.13.0",
+    "terminator-mcp-darwin-x64": "0.13.0",
+    "terminator-mcp-linux-x64-gnu": "0.13.0",
+    "terminator-mcp-win32-x64-msvc": "0.13.0"
   },
   "repository": {
     "type": "git",
@@ -30,5 +30,5 @@
     "sync-version": "node ./utils/sync-version.js",
     "update-badges": "node ./utils/update-badges.js"
   },
-  "version": "0.12.17"
+  "version": "0.13.0"
 }