enhanced-mcp-tools/examples/automation_tools_usage.md

ScreenshotTools Usage Guide

The ScreenshotTools module provides reliable screenshot capture capabilities using PIL.ImageGrab for cross-platform image capture without complex automation dependencies.

✅ Security Notice

ScreenshotTools include only SAFE operations that are read-only and cannot modify the user's system:

• SAFE Tools: Screenshot capture, clipboard image capture, screen info (always available)
• No Destructive Operations: Removed all keyboard, mouse, and dialog automation for security
• Reliable Dependencies: Uses maintained PIL.ImageGrab instead of unmaintained pyautogui

Available Tools

📸 Screenshot Capture (SAFE)

# Take a full screenshot
screenshot_take_screenshot(save_path="/tmp/screenshot.png", format="PNG")

# Take a region screenshot
screenshot_take_screenshot(bbox=[100, 100, 800, 600], return_base64=True)

# Capture image from clipboard
screenshot_capture_clipboard(save_path="/tmp/clipboard.png", format="PNG")

# Get screen information
screenshot_get_screen_info()

🛡️ Safety Features

✅ Safe by Design

# All tools are SAFE - no destructive operations available
# No enablement required - tools work immediately
screenshot_take_screenshot(save_path="/tmp/screenshot.png")

# Graceful error handling for unsupported environments
result = screenshot_capture_clipboard()
if not result.get('success'):
    print(f"Clipboard not available: {result.get('error')}")

🔧 Bulk Operations Integration

ScreenshotTools are integrated with BulkToolCaller for workflow automation:

# Create a screenshot workflow
bulk_operations_create_bulk_workflow(
    name="Screenshot Workflow",
    description="Take multiple screenshots and analyze",
    operations=[
        {
            "tool_name": "screenshot_take_screenshot",
            "arguments": {"save_path": "/tmp/screen1.png"},
            "description": "Take full screenshot"
        },
        {
            "tool_name": "screenshot_get_screen_info",
            "arguments": {},
            "description": "Get screen information"
        },
        {
            "tool_name": "screenshot_capture_clipboard",
            "arguments": {"save_path": "/tmp/clipboard.png"},
            "description": "Capture clipboard image"
        }
    ],
    mode="sequential"
)

🖥️ Environment Requirements

• GUI Environment: Requires active display (X11 on Linux, native on Windows/macOS)
• Headless Systems: Tools gracefully degrade with informative error messages
• Dependencies: Only PIL/Pillow (lightweight and maintained)
• Clipboard: Linux requires wl-paste or xclip for clipboard image capture

🎯 Use Cases

1. Documentation: Capture workflow screenshots, create tutorials
2. System Monitoring: Periodic screen captures for debugging
3. Visual Debugging: Capture screenshots at specific points
4. Content Creation: Automated screenshot capture for demos
5. Clipboard Integration: Capture and process clipboard images

🔍 Example: Screenshot Capture Workflow

# 1. Take full screenshot
result = screenshot_take_screenshot(save_path="/tmp/fullscreen.png", return_base64=True)

# 2. Take region screenshot
region_result = screenshot_take_screenshot(
    bbox=[100, 100, 800, 600],
    save_path="/tmp/region.png"
)

# 3. Get screen information for context
screen_info = screenshot_get_screen_info()

# 4. Try to capture clipboard image
clipboard_result = screenshot_capture_clipboard(save_path="/tmp/clipboard.png")

# 5. Process results
if result.get('success'):
    print(f"Screenshot captured: {result['size']} pixels")
if clipboard_result.get('success'):
    print(f"Clipboard image captured: {clipboard_result['size']}")
else:
    print(f"Clipboard capture: {clipboard_result.get('error')}")

The ScreenshotTools provide reliable screenshot capture capabilities using modern, maintained dependencies with built-in safety through read-only operations.