terminator-mcp-agent 0.13.9 → 0.14.10

package/README.md

@@ -11,6 +11,14 @@ A Model Context Protocol (MCP) server that provides desktop GUI automation capab
 
 ## Quick Install
 
+### Claude Code
+
+Install with a single command:
+
+```bash
+claude mcp add terminator "npx -y terminator-mcp-agent" -s user
+```
+
 ### Cursor
 
 Copy and paste this URL into your browser's address bar:
@@ -81,6 +89,12 @@ terminator mcp run workflow.yml --dry-run
 
 # Use specific MCP server version
 terminator mcp run workflow.yml --command "npx -y terminator-mcp-agent@latest"
+
+# Run specific steps (requires step IDs in workflow)
+terminator mcp run workflow.yml --start-from "step_12" --end-at "step_13"
+
+# Run single step
+terminator mcp run workflow.yml --start-from "read_json" --end-at "read_json"
 ```
 
 **Workflow File Formats:**
@@ -123,61 +137,63 @@ Execute custom JavaScript or Python with access to desktop automation APIs via `
 
 **Passing Data Between Workflow Steps:**
 
-When using `engine` mode, you can pass data between steps using the `set_env` mechanism:
+When using `engine` mode, data automatically flows between steps:
 
 ```yaml
 steps:
-  # Step 1: Set environment variables for next step
+  # Step 1: Return data directly (NEW - simplified!)
   - tool_name: run_command
     arguments:
       engine: "javascript"
       run: |
-        // Example: Find files and pass data to next step
-        const { execSync } = require('child_process');
-        
         // Get file info (example)
         const filePath = 'C:\\data\\report.pdf';
         const fileSize = 1024;
-        
-        // Pass data to next step using set_env
+
         console.log(`Found file: ${filePath}`);
-        
-        // Method 1: Return set_env object (preferred)
+
+        // Just return fields directly - they auto-merge into env
         return {
-          set_env: {
-            file_path: filePath,
-            file_size: fileSize.toString()
-          },
-          status: 'found'
+          status: 'success',
+          file_path: filePath,      // Becomes env.file_path
+          file_size: fileSize        // Becomes env.file_size
         };
-        
-        // Method 2: GitHub Actions style (alternative)
-        // console.log(`::set-env name=file_path::${filePath}`);
 
-  # Step 2: Access data from previous step
+  # Step 2: Access data automatically
   - tool_name: run_command
     arguments:
       engine: "javascript"
       run: |
-        // Access environment variables from previous step
-        const filePath = '{{env.file_path}}';
-        const fileSize = '{{env.file_size}}';
-        
-        console.log(`Processing: ${filePath} (${fileSize} bytes)`);
-        
+        // env is automatically available - no setup needed!
+        console.log(`Processing: ${env.file_path} (${env.file_size} bytes)`);
+
+        // Workflow variables also auto-available
+        console.log(`Config: ${variables.max_retries}`);
+
+        // NEW: Direct variable access also works!
+        console.log(`Processing: ${file_path} (${file_size} bytes)`);
+        console.log(`Config: ${max_retries}`);
+
         // Continue with desktop automation
         const elements = await desktop.locator('role:button').all();
-        log(`Found ${elements.length} buttons`);
-        
+
+        // Return more data (auto-merges to env)
         return {
-          file_processed: filePath,
+          status: 'success',
+          file_processed: env.file_path,
           buttons_found: elements.length
         };
 ```
 
 **Important Notes on Data Passing:**
-- `set_env` only works with `engine` mode (JavaScript/Python), NOT with shell commands
-- Use `{{env.variable_name}}` syntax to access variables in subsequent steps
+
+- **NEW:** `env` and `variables` are automatically injected into all scripts
+- **NEW:** Non-reserved fields in return values auto-merge into env (no `set_env` wrapper needed)
+- **NEW:** Valid env fields are also available as individual variables (e.g., `file_path` instead of `env.file_path`)
+- Reserved fields that don't auto-merge: `status`, `error`, `logs`, `duration_ms`, `set_env`
+- Data passing only works with `engine` mode (JavaScript/Python), NOT with shell commands
+- Backward compatible: explicit `set_env` still works if needed
+- Individual variable names must be valid JavaScript identifiers (no spaces, special chars, or reserved keywords)
 - Watch for backslash escaping issues in Windows paths (may need double escaping)
 - Consider combining related operations in a single step if data passing becomes complex
 
@@ -269,12 +285,14 @@ The `execute_browser_script` tool enables direct JavaScript execution in browser
 #### 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
@@ -286,19 +304,19 @@ The `execute_browser_script` tool enables direct JavaScript execution in browser
 // Get full HTML DOM (be mindful of size limits)
 execute_browser_script({
   selector: "role:Window|name:Google Chrome",
-  script: "document.documentElement.outerHTML"
-})
+  script: "document.documentElement.outerHTML",
+});
 
 // Get structured page information
 execute_browser_script({
-  selector: "role:Window|name:Google Chrome", 
+  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({
@@ -322,8 +340,8 @@ execute_browser_script({
       name: m.name || m.property,
       content: m.content
     }))
-  })`
-})
+  })`,
+});
 ```
 
 #### Handling Large DOMs
@@ -346,8 +364,8 @@ execute_browser_script({
       totalLength: html.length,
       truncated: html.length > maxLength
     })
-  `
-})
+  `,
+});
 ```
 
 #### Advanced DOM Analysis
@@ -382,8 +400,98 @@ execute_browser_script({
         .map(s => { try { return JSON.parse(s.textContent); } catch { return null; } })
         .filter(Boolean)
     })
-  `
-})
+  `,
+});
+```
+
+#### Passing Data with Environment Variables
+
+The `execute_browser_script` tool now supports passing data through `env` and `outputs` parameters:
+
+```javascript
+// Step 1: Set environment variables in JavaScript
+run_command({
+  engine: "javascript",
+  run: `
+    return {
+      set_env: {
+        userName: 'John Doe',
+        userId: '12345',
+        apiKey: 'secret-key'
+      }
+    };
+  `,
+});
+
+// Step 2: Use environment variables in browser script
+execute_browser_script({
+  selector: "role:Window",
+  env: {
+    userName: "{{env.userName}}",
+    userId: "{{env.userId}}",
+  },
+  script: `
+    // Parse env if it's a JSON string (for backward compatibility)
+    const parsedEnv = typeof env === 'string' ? JSON.parse(env) : env;
+
+    // Use the data - traditional way
+    console.log('Processing user:', parsedEnv.userName);
+
+    // NEW: Direct variable access also works!
+    console.log('Processing user:', userName);  // Direct access
+    console.log('User ID:', userId);            // No env prefix needed
+
+    // Fill form with data
+    document.querySelector('#username').value = userName;
+    document.querySelector('#userid').value = userId;
+    
+    // Return result and set new variables
+    JSON.stringify({
+      status: 'form_filled',
+      set_env: {
+        form_submitted: 'true',
+        timestamp: new Date().toISOString()
+      }
+    });
+  `,
+});
+```
+
+#### Loading Scripts from Files
+
+You can load JavaScript from external files using the `script_file` parameter:
+
+```javascript
+// browser_scripts/extract_data.js
+const parsedEnv = typeof env === "string" ? JSON.parse(env) : env;
+const parsedOutputs =
+  typeof outputs === "string" ? JSON.parse(outputs) : outputs;
+
+console.log("Script loaded from file");
+console.log("User:", parsedEnv?.userName);
+console.log("Previous result:", parsedOutputs?.previousStep);
+
+// Extract and return data
+JSON.stringify({
+  extractedData: {
+    url: window.location.href,
+    title: document.title,
+    forms: document.forms.length,
+  },
+  set_env: {
+    extraction_complete: "true",
+  },
+});
+
+// In your workflow:
+execute_browser_script({
+  selector: "role:Window",
+  script_file: "browser_scripts/extract_data.js",
+  env: {
+    userName: "{{env.userName}}",
+    previousStep: "{{env.previousStep}}",
+  },
+});
 ```
 
 #### Important Notes
@@ -396,6 +504,8 @@ execute_browser_script({
 
 4. **Error Handling**: Always wrap complex DOM operations in try-catch blocks and return meaningful error messages.
 
+5. **Data Injection**: When using `env` or `outputs` parameters, they are injected as JavaScript variables at the beginning of your script. Always parse them if they might be JSON strings.
+
 ## Local Development
 
 To build and test the agent from the source code:
@@ -541,6 +651,7 @@ The agent automatically detects headless environments and initializes a virtual
 **Activation**:
 
 Virtual display activates automatically when:
+
 - Environment variable `TERMINATOR_HEADLESS=true` is set
 - No console window is available (common in VM/container scenarios)
 - Running as a Windows service or scheduled task
@@ -698,11 +809,100 @@ For additional help, see the [Terminator CLI documentation](../terminator-cli/RE
 4. **Groups & Control Flow** – Add `group_name`, `skippable`, `if`, or `continue_on_error` to any step for advanced branching.
 5. **Output Parsing** – Always end with a step that includes the UI tree, then use the declarative JSON DSL to mine the data you need.
 
-### 3. Running the Workflow
+### 3. State Persistence & Partial Execution
+
+The `execute_sequence` tool supports powerful features for workflow debugging and resumption:
+
+#### Partial Execution with Step Ranges
+
+You can run specific portions of a workflow using `start_from_step` and `end_at_step` parameters:
+
+```jsonc
+{
+  "tool_name": "execute_sequence",
+  "arguments": {
+    "url": "file://path/to/workflow.yml",
+    "start_from_step": "read_json_file",    // Start from this step ID
+    "end_at_step": "fill_journal_entries",  // Stop after this step (inclusive)
+    "follow_fallback": false                // Don't follow fallback_id beyond end_at_step (default: false)
+  }
+}
+```
+
+**Examples:**
+- Run single step: Set both `start_from_step` and `end_at_step` to the same ID
+- Run step range: Set different IDs for start and end
+- Run from step to end: Only set `start_from_step`
+- Run from beginning to step: Only set `end_at_step`
+- Debug without fallback: Use `follow_fallback: false` to prevent jumping to troubleshooting steps when a bounded step fails
+
+#### Automatic State Persistence
+
+When using `file://` URLs, the workflow state (environment variables) is automatically saved to a `.workflow_state` folder:
+
+1. **State is saved** after each step that modifies environment variables via `set_env` or has a tool result with an ID
+2. **State is loaded** when starting from a specific step
+3. **Location**: `.workflow_state/<workflow_hash>.json` in the workflow's directory
+4. **Tool results** from all tools (not just scripts) are automatically stored as `{step_id}_result` and `{step_id}_status`
+
+This enables:
+- **Debugging**: Run steps individually to inspect state between executions
+- **Recovery**: Resume failed workflows from the last successful step
+- **Testing**: Test specific steps without re-running the entire workflow
+
+#### Data Passing Between Steps
+
+Steps can pass data using multiple methods:
+
+##### 1. Tool Result Storage (NEW)
+
+ALL tools with an `id` field automatically store their results in the environment:
+
+```yaml
+steps:
+  # Any tool with an ID stores its result
+  - id: check_apps
+    tool_name: get_applications
+    arguments:
+      include_tree: false
+
+  # Access the result in JavaScript
+  - tool_name: run_command
+    arguments:
+      engine: javascript
+      run: |
+        // Direct variable access - auto-injected!
+        const apps = check_apps_result || [];
+        const status = check_apps_status; // "success" or "error"
+        console.log(`Found ${apps[0]?.applications?.length} apps`);
+```
+
+##### 2. Script Return Values
+
+Steps can pass data using the `set_env` mechanism in `run_command` with engine mode:
+
+```javascript
+// Step 12: Read and process data
+return {
+  set_env: {
+    file_path: "C:/data/input.json",
+    journal_entries: JSON.stringify(entries),
+    total_debit: "100.50"
+  }
+};
+
+// Step 13: Use the data (NEW - simplified access!)
+const filePath = file_path;  // Direct access, no {{env.}} needed!
+const entries = JSON.parse(journal_entries);
+const debit = total_debit;
+```
+
+### 4. Running the Workflow
 
 1. Ensure the Terminator MCP agent is running (it will auto-start in supported editors).
 2. Send the JSON above as the body of an `execute_sequence` tool call from your LLM or test harness.
-3. Inspect the response: if parsing succeeds you’ll see something like
+3. Inspect the response: if parsing succeeds you'll see something like
+
 ### Realtime events (SSE)
 
 When running with the HTTP transport, you can subscribe to realtime workflow events at a separate endpoint outside `/mcp`:
@@ -713,12 +913,11 @@ When running with the HTTP transport, you can subscribe to realtime workflow eve
 Example in Node.js:
 
 ```js
-import EventSource from 'eventsource';
-const es = new EventSource('http://127.0.0.1:3000/events');
-es.onmessage = (e) => console.log('event', e.data);
+import EventSource from "eventsource";
+const es = new EventSource("http://127.0.0.1:3000/events");
+es.onmessage = (e) => console.log("event", e.data);
 ```
 
-
 ```jsonc
 {
   "parsed_output": {
@@ -727,11 +926,103 @@ es.onmessage = (e) => console.log('event', e.data);
 }
 ```
 
-### 4. Tips for Production Workflows
+### 5. Working with Tool Results
+
+Every tool that has an `id` field automatically stores its result for use in later steps:
+
+```yaml
+steps:
+  # Capture browser DOM
+  - id: capture_dom
+    tool_name: execute_browser_script
+    arguments:
+      selector: "role:Window"
+      script: "return document.documentElement.innerHTML;"
+
+  # Validate an element exists
+  - id: check_button
+    tool_name: validate_element
+    arguments:
+      selector: "role:Button|name:Submit"
+
+  # Use both results in script
+  - tool_name: run_command
+    arguments:
+      engine: javascript
+      run: |
+        // All tool results are auto-injected as variables
+        const dom = capture_dom_result?.content || '';
+        const buttonExists = check_button_status === 'success';
+
+        if (buttonExists) {
+          const button = check_button_result[0]?.element;
+          console.log(`Submit button at: ${button?.bounds?.x}, ${button?.bounds?.y}`);
+        }
+
+        return { dom_length: dom.length, has_button: buttonExists };
+```
+
+Tool results are accessible as:
+- `{step_id}_result`: The tool's return value (content, element info, etc.)
+- `{step_id}_status`: Either "success" or "error"
+
+### 6. Tips for Production Workflows
 
 - **Never hard-code credentials** – use environment variables or your secret manager.
 - **Keep workflows short** – <100 steps is ideal. Break large tasks into multiple sequences.
-- **Capture errors** – `continue_on_error` is useful, but also log `result.status` codes to catch silent failures.
+- **Capture errors** – `continue_on_error` is useful, but also check `{step_id}_status` for tool failures.
 - **Version control** – Store workflow JSON in a repo and use PR reviews just like regular code.
+- **Use step IDs** – Give meaningful IDs to steps whose results you'll need later.
+
+## 🔍 Troubleshooting & Debugging
+
+### Finding MCP Server Logs
+
+MCP logs are saved to:
+- **Windows:** `%LOCALAPPDATA%\claude-cli-nodejs\Cache\<encoded-project-path>\mcp-logs-terminator-mcp-agent\`
+- **macOS/Linux:** `~/.local/share/claude-cli-nodejs/Cache/<encoded-project-path>/mcp-logs-terminator-mcp-agent/`
+
+Where `<encoded-project-path>` is your project path with special chars replaced (e.g., `C--Users-username-project`).
+Note: Logs are saved as `.txt` files, not `.log` files.
+
+**Read logs:**
+```powershell
+# Windows - Find and read latest logs (run in PowerShell)
+Get-ChildItem (Join-Path ([Environment]::GetFolderPath('LocalApplicationData')) 'claude-cli-nodejs\Cache\*\mcp-logs-terminator-mcp-agent\*.txt') | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 50
+```
+
+### Enable Debug Logging
+
+In your Claude MCP configuration (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "terminator-mcp-agent": {
+      "command": "path/to/terminator-mcp-agent",
+      "env": {
+        "LOG_LEVEL": "debug",  // or "info", "warn", "error"
+        "RUST_BACKTRACE": "1"   // for stack traces on errors
+      }
+    }
+  }
+}
+```
+
+### Common Debug Scenarios
+
+| Issue | What to Look For in Logs |
+|-------|--------------------------|
+| Workflow failures | Search for `fallback_id` triggers and `critical_error_occurred` |
+| Element not found | Look for selector resolution attempts, `find_element` timeouts |
+| Browser script errors | Check for `EVAL_ERROR`, Promise rejections, JavaScript exceptions |
+| Binary version issues | Startup logs show binary path and build timestamp |
+| MCP connection lost | Check for panic messages, ensure binary path is correct |
+
+### Fallback Mechanism
+
+Workflows support `fallback_id` to handle errors gracefully:
+- If a step fails and has `fallback_id`, it jumps to that step instead of stopping
+- Without `fallback_id`, errors may set `critical_error_occurred` and skip remaining steps
+- Use `troubleshooting:` section for recovery steps only accessed via fallback
 
 > Need more help? Browse the examples under `examples/` in this repo or open a discussion on GitHub.

package/package.json

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