npm - @hybridlabor-api/aos - Versions diffs - 4.3.0 → 4.4.1 - Mend

@hybridlabor-api/aos 4.3.0 → 4.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1052) hide show

package/mcps/windows-computer-use-mcp/docs/TOOLS.md DELETED Viewed

@@ -1,80 +0,0 @@
-# MCP tools reference
-22 portmanteau tools. All use `operation` enum. Responses are `ToolResult {status, message, data, recovery_tip}`.
-## Core automation
-| Tool | Key operations | Added |
-|------|---------------|-------|
-| `automation_windows` | list, find, focus, maximize, minimize, close, position, state | — |
-| `automation_elements` | click, set_text, list, info, get_text, exists, wait | — |
-| `automation_elements` (verify) | + `verify=True`, `verify_text="expected"` — outcome check after action | 1 |
-| `automation_mouse` | click, double_click, right_click, scroll, drag, hover, position, telemetry | — |
-| `automation_keyboard` | type, hotkey, press, hold, release | — |
-| `automation_visual` | screenshot, extract_text (OCR), find_image, highlight | — |
-| `automation_assert` | hash, diff, wait_stable, assert_changed, assert_unchanged, assert_template, assert_text | — |
-| `automation_dialog` | set_path, confirm, submit_path (file dialog entry) | — |
-| `automation_shortcut` | send, list, describe (app-specific semantic shortcuts) | — |
-| `automation_task` | run, status, cancel, list_profiles, list_templates | — |
-| `automation_system` | status, info, clipboard, processes, start_app, **telemetry** | 2 |
-| `get_window_state` | per-window UIA snapshot (ax/som/vision), snapshot_id + element_index | — |
-| `get_desktop_state` | full desktop UI tree with optional OCR enrichment | — |
-## Autonomous & agentic
-| Tool | Key operations | Added |
-|------|---------------|-------|
-| `automation_mission` | **run** (goal → decompose → execute → retry → verify), plan, status, cancel | 1 |
-| `automation_mission` (workflow) | **workflow** — explicit steps, app launch, timeout, data chaining with `$ref:` | 3, 5 |
-| `automation_macro` | record, stop, replay, **replay_with_verify**, list | 3 |
-| `automation_smart` | **click** (intent-based, across all windows), **discover**, list_apps, list_controls | 4 |
-| `automation_watch` | start, status, stop, list (background thread, 4 condition types) | 5 |
-| `automation_analyze` | crawl, discover, portfolio (WinApp UI tree analysis with HUD overlay) | — |
-## Safety & opt-in
-| Tool | Notes |
-|------|-------|
-| `approve_automation` | Grant HITL time window for mouse/keyboard |
-| `automation_safety` | status, reset_counters — kill switch, rate limits, dry-run |
-| `automation_face` | **Off by default** — `WINDOWS_COMPUTER_USE_MCP_ENABLE_FACE=1` + `face` extra |
-| `global_keylogger` | **Off by default** — `WINDOWS_COMPUTER_USE_MCP_ENABLE_KEYLOGGER=1` (non-stealth debug hook) |
-## Examples
-```python
-# Autonomous mission
-automation_mission(run="open Notepad, type 'hello world', save as test.txt")
-# Smart intent-based click (finds across all windows)
-automation_smart(click="the Save button")
-# Record and replay a sequence
-automation_macro(record=True)  # ... run tools ...  automation_macro(stop=True)
-automation_macro(replay=True, name="my_macro")
-# Watch for a window to appear
-automation_watch(start=True, condition="window_appears", target="Update Available")
-# Poll with:  automation_watch(status=True, watcher_id=...)
-# Multi-app workflow with data chaining
-automation_mission(workflow=True, app="notepad.exe", actions=[
-    {"tool": "elements", "params": {"click": True, "title": "Yes"}, "store_as": "clicked"},
-    {"tool": "mouse", "params": {"click": True, "x": 100, "y": 200}},
-])
-# Telemetry query
-automation_system(telemetry=True)
-```
-## Retry policy (server-side)
-All mutating operations use `RetryPolicy` with strategy chain: refocus → wait_stable → fallback_selector → escalate. Each strategy gets up to 3 attempts with exponential backoff. The mission engine additionally self-heals: if target window dies, re-launches the app and retries.
-## Adaptive element location
-When `automation_elements(click, title="Save")` fails, the cascade tries: title → auto_id → control_id → class+type → OCR region scan. The winning strategy is logged to telemetry so future missions can prefer it.
-## Telemetry
-Every action is logged to `~/.windows-computer-use-mcp/telemetry.db`. Query with `automation_system(telemetry=True)` for per-tool failure rates, best strategies, and top error patterns.

package/mcps/windows-computer-use-mcp/docs/TOOL_DOCSTRING_STANDARD.md DELETED Viewed

@@ -1,538 +0,0 @@
-# MCP Tool Docstring Standard
-**Version:** 1.0.0
-**Last Updated:** October 10, 2025
-**Status:** MANDATORY for all tools
----
-## Overview
-All MCP tools MUST have comprehensive multiline docstrings following this standard.
-## Required Sections
-Every tool docstring MUST include:
-1. **Brief Description** (1-2 sentences)
-2. **Parameters** section with all arguments
-3. **Returns** section with structure
-4. **Usage** section with context
-5. **Examples** section with code samples
-## Format Rules
-### ✅ REQUIRED
-- Use triple double-quotes (`"""`) to delimit docstrings
-- Start docstring immediately after function definition
-- Brief description on first line
-- Blank line after brief description
-- All sections properly formatted
-### ❌ PROHIBITED
-- **NO triple quotes (`"""`) inside docstrings** - Use single quotes or escape
-- NO missing parameter documentation
-- NO examples without expected output
-- NO vague descriptions
----
-## Template
-```python
-@mcp.tool()
-async def tool_name(
-    param1: str,
-    param2: int = 10,
-    param3: Optional[List[str]] = None
-) -> Dict[str, Any]:
-    '''Brief one-line description of what the tool does.
-    Detailed description providing context, use cases, and important notes about
-    the tool's behavior. This should help users understand when and how to use it.
-    Parameters:
-        param1: Description of the first parameter
-            - Required/Optional status
-            - Valid values or constraints
-            - Default value if applicable
-        param2: Description of second parameter (default: 10)
-            - Mention defaults in description
-            - Explain acceptable ranges
-        param3: Description of third parameter (default: None)
-            - Explain None behavior
-            - Describe list element types
-    Returns:
-        Dictionary containing:
-            - success: Boolean indicating operation success
-            - data: The actual data returned
-            - metadata: Additional information about the operation
-            - error: Error message if success is False
-    Usage:
-        This tool is used when you need to [explain use case]. It works by
-        [explain mechanism]. Best practices include [list recommendations].
-        Common scenarios:
-        - Scenario 1: When to use this tool
-        - Scenario 2: Another use case
-        - Scenario 3: Special considerations
-    Examples:
-        Basic usage:
-            result = await tool_name("value1", 20)
-            # Returns: {'success': True, 'data': [...]}
-        With optional parameters:
-            result = await tool_name(
-                "value1",
-                param2=50,
-                param3=["option1", "option2"]
-            )
-            # Returns: {'success': True, 'data': [...], 'metadata': {...}}
-        Error handling:
-            result = await tool_name("invalid_value")
-            if not result['success']:
-                print(f"Error: {result['error']}")
-            # Returns: {'success': False, 'error': 'Invalid value provided'}
-    Raises:
-        ValueError: When parameter validation fails
-        ConnectionError: When database connection is unavailable
-        TimeoutError: When operation exceeds timeout limit
-    Notes:
-        - Important consideration 1
-        - Important consideration 2
-        - Performance implications
-        - Security considerations
-    See Also:
-        - related_tool_name: For related functionality
-        - another_tool: For alternative approach
-    '''
-    # Implementation
-    pass
-```
----
-## Section Details
-### 1. Brief Description
-**Format:**
-```python
-'''Single sentence describing the tool's primary purpose.'''
-```
-**Requirements:**
-- One sentence maximum
-- Action-oriented (starts with verb)
-- Clear and concise
-- No technical jargon unless necessary
-**Examples:**
-- ✅ `'''Execute SQL query on specified database connection.'''`
-- ✅ `'''List all available database connections with their status.'''`
-- ❌ `'''Does stuff'''` (too vague)
-- ❌ `'''This tool is used to maybe do things with databases'''` (too wordy)
----
-### 2. Detailed Description
-**Format:**
-```python
-'''Brief description.
-Detailed explanation spanning multiple lines that provides full context,
-explains use cases, and describes the tool's behavior in detail.
-'''
-```
-**Requirements:**
-- Blank line after brief description
-- 2-5 sentences typical
-- Explain WHAT, WHY, and WHEN
-- Mention any important limitations
----
-### 3. Parameters Section
-**Format:**
-```python
-Parameters:
-    param_name: Parameter description
-        - Additional details about parameter
-        - Valid values or constraints
-        - Default if applicable
-    another_param: Another description (default: value)
-        - More details
-```
-**Requirements:**
-- List ALL parameters
-- Indent parameter descriptions
-- Include type information if not in signature
-- Mention defaults
-- Explain constraints and valid values
-- Use bullet points for complex parameters
-**Example:**
-```python
-Parameters:
-    connection_name: Name of the registered database connection
-        - Must be alphanumeric with underscores only
-        - Connection must be registered before use
-        - Case-sensitive
-    query: SQL query string to execute
-        - Must be valid SQL for the target database type
-        - Parameterized queries recommended for security
-        - Maximum length: 10,000 characters
-    timeout: Maximum execution time in seconds (default: 30)
-        - Must be positive integer
-        - None means no timeout
-        - Minimum: 1, Maximum: 3600
-```
----
-### 4. Returns Section
-**Format:**
-```python
-Returns:
-    Dictionary containing:
-        - key1: Description of first key
-        - key2: Description of second key
-        - key3: Optional key (only present when...)
-```
-**Requirements:**
-- Describe the return type structure
-- List all keys in returned dictionaries
-- Indicate optional vs required keys
-- Show nested structure if applicable
-- Give example values
-**Example:**
-```python
-Returns:
-    Dictionary containing:
-        - success: Boolean indicating if operation succeeded
-        - data: List of database records (empty list if none found)
-        - metadata: Dictionary with query execution details
-            - execution_time: Time in milliseconds
-            - row_count: Number of rows returned
-            - query_hash: Hash of executed query
-        - error: Error message string (only present if success is False)
-        - warnings: List of warning messages (optional)
-```
----
-### 5. Usage Section
-**Format:**
-```python
-Usage:
-    Explain when and how to use this tool. Describe the context,
-    common scenarios, and best practices.
-    Common scenarios:
-    - Scenario 1: Description
-    - Scenario 2: Description
-```
-**Requirements:**
-- Explain WHEN to use the tool
-- Describe typical workflows
-- List common scenarios
-- Mention best practices
-- Note any prerequisites
-**Example:**
-```python
-Usage:
-    Use this tool to retrieve a sample of data from any table for quick
-    inspection or validation. This is ideal for data exploration, schema
-    verification, or debugging purposes.
-    Common scenarios:
-    - Quick peek at table contents before running complex queries
-    - Verify data structure after schema migration
-    - Debug data quality issues
-    - Generate sample data for documentation
-    Best practices:
-    - Start with small sample sizes (10-50 rows)
-    - Use column filters to reduce data transfer
-    - Combine with describe_table for full context
-```
----
-### 6. Examples Section
-**Format:**
-```python
-Examples:
-    Basic usage:
-        code_example
-        # Expected output or behavior
-    Advanced usage:
-        code_example
-        # Expected output or behavior
-    Error handling:
-        code_example
-        # Expected error output
-```
-**Requirements:**
-- Provide at least 3 examples
-- Show basic, intermediate, and advanced usage
-- Include expected output
-- Show error handling
-- Use realistic values
-- Make examples runnable
-- Add comments explaining behavior
-**Example:**
-```python
-Examples:
-    Basic query execution:
-        result = await execute_query(
-            connection_name="production_db",
-            query="SELECT * FROM users WHERE active = true"
-        )
-        # Returns: {
-        #     'success': True,
-        #     'data': [{'id': 1, 'name': 'John', 'active': True}, ...],
-        #     'metadata': {'row_count': 42, 'execution_time': 125}
-        # }
-    Parameterized query with limit:
-        result = await execute_query(
-            connection_name="production_db",
-            query="SELECT * FROM users WHERE age > :min_age",
-            parameters={"min_age": 18},
-            limit=100
-        )
-        # Returns: Limited to 100 rows matching criteria
-    Error handling:
-        result = await execute_query(
-            connection_name="nonexistent_db",
-            query="SELECT * FROM users"
-        )
-        if not result['success']:
-            print(f"Query failed: {result['error']}")
-            # Logs: Query failed: Connection not found: nonexistent_db
-    Complex query with all options:
-        result = await execute_query(
-            connection_name="analytics_db",
-            query='''
-                SELECT department, COUNT(*) as emp_count
-                FROM employees
-                WHERE hire_date > :start_date
-                GROUP BY department
-                HAVING COUNT(*) > :min_count
-                ORDER BY emp_count DESC
-            ''',
-            parameters={
-                "start_date": "2023-01-01",
-                "min_count": 5
-            },
-            limit=20
-        )
-        # Returns: Top 20 departments with most recent hires
-```
----
-### 7. Raises Section (Optional but Recommended)
-**Format:**
-```python
-Raises:
-    ExceptionType: Description of when this exception occurs
-    AnotherException: Description of another exception
-```
-**Example:**
-```python
-Raises:
-    ValueError: If connection_name is empty or contains invalid characters
-    ConnectionError: If database connection cannot be established
-    QueryError: If SQL query is malformed or cannot be executed
-    TimeoutError: If query execution exceeds the specified timeout
-    PermissionError: If user lacks necessary database permissions
-```
----
-### 8. Notes Section (Optional)
-**Format:**
-```python
-Notes:
-    - Important note 1
-    - Important note 2
-    - Performance consideration
-    - Security consideration
-```
-**Example:**
-```python
-Notes:
-    - Large result sets may consume significant memory
-    - Query timeout defaults to 30 seconds but can be adjusted
-    - Parameterized queries are strongly recommended to prevent SQL injection
-    - Connection pooling is automatically managed
-    - Transactions are not implicitly started; use begin_transaction() if needed
-```
----
-### 9. See Also Section (Optional)
-**Format:**
-```python
-See Also:
-    - related_tool: Description of relation
-    - another_tool: Why you might use this instead
-```
-**Example:**
-```python
-See Also:
-    - quick_data_sample: For getting sample data without writing queries
-    - export_query_results: For executing queries and exporting to files
-    - describe_table: For understanding table schema before querying
-```
----
-## Avoiding Triple Quotes Inside Docstrings
-### The Problem
-This will break:
-```python
-def tool():
-    '''
-    Example usage:
-        data = {"key": """value"""}  # ❌ BREAKS!
-    '''
-```
-### Solutions
-**Option 1: Use Single Quotes**
-```python
-def tool():
-    '''
-    Example usage:
-        data = {"key": "value"}  # ✅ GOOD
-    '''
-```
-**Option 2: Use Escaped Quotes**
-```python
-def tool():
-    '''
-    Example usage:
-        # Use escaped quotes for multi-line strings
-        query = "SELECT * FROM table"  # ✅ GOOD
-    '''
-```
-**Option 3: Describe Instead of Show**
-```python
-def tool():
-    '''
-    Example usage:
-        # For multi-line strings, use appropriate quoting
-        query = "Your SQL query here"  # ✅ GOOD
-    '''
-```
----
-## Quick Checklist
-Before committing tool code, verify:
-- [ ] Brief description is clear and action-oriented
-- [ ] All parameters documented with types and defaults
-- [ ] Return structure fully described
-- [ ] Usage section explains when/why to use tool
-- [ ] At least 3 examples provided
-- [ ] Examples show expected output
-- [ ] Error handling example included
-- [ ] NO triple quotes inside docstring
-- [ ] Raises section lists possible exceptions
-- [ ] Notes section includes important details
----
-## Validation
-Use this regex to find tools with potentially bad docstrings:
-```bash
-# Find tools without examples
-grep -r "@mcp.tool" --include="*.py" -A 20 | grep -L "Examples:"
-# Find docstrings with triple quotes inside
-grep -r '""".*""".*"""' --include="*.py"
-```
----
-## Enforcement
-This standard is:
-- **MANDATORY** for all new tools
-- **REQUIRED** for all modified tools
-- **RECOMMENDED** for existing tools (gradual update)
-Tools without proper docstrings will:
-- Fail code review
-- Not be included in releases
-- Not appear in generated documentation
----
-## Benefits
-Following this standard provides:
-- **Better UX**: Users understand tools quickly
-- **Self-Documenting**: Code explains itself
-- **Fewer Support Issues**: Clear examples reduce questions
-- **Auto-Generated Docs**: Tools can parse these docstrings
-- **IDE Support**: Better autocomplete and hints
-- **Maintainability**: Future developers understand intent
----
-*Tool Docstring Standard v1.0.0*
-*Part of MCPB Packaging Documentation*
-*Location: `mcpb/docs/TOOL_DOCSTRING_STANDARD.md`*