Auto-Snap MCP

Instructions

Capture screenshot of a specific window.

Args:
    window_id: Window ID to capture (from list_windows)
    output_path: Optional path to save the screenshot

Returns:
    JSON string with capture results and file path.

Implementation Reference

• server.py:104-138 (handler)

  MCP tool handler and registration for 'capture_window'. Handles input validation via type hints, delegates to CrossPlatformWindowManager, returns JSON results.

  @mcp.tool()
  async def capture_window(window_id: str, output_path: Optional[str] = None) -> str:
      """
      Capture screenshot of a specific window.
      
      Args:
          window_id: Window ID to capture (from list_windows)
          output_path: Optional path to save the screenshot
      
      Returns:
          JSON string with capture results and file path.
      """
      try:
          wm = get_window_manager()
          captured_path = wm.capture_window(window_id, output_path)
          
          result = {
              "status": "success",
              "window_id": window_id,
              "output_path": captured_path,
              "file_exists": Path(captured_path).exists(),
              "file_size_mb": round(Path(captured_path).stat().st_size / (1024 * 1024), 2)
          }
          
          return json.dumps(result, indent=2)
          
      except Exception as e:
          logger.error(f"Failed to capture window {window_id}: {e}")
          return json.dumps({
              "status": "error",
              "error": str(e),
              "window_id": window_id,
              "output_path": output_path
          })

• capture.py:235-459 (helper)

  WindowsWindowManager.capture_window: Primary implementation for Windows via WSL2/PowerShell. Uses PrintWindow API, handles minimized windows with stealth restoration, full PowerShell automation.

      def capture_window(self, window_id: str, output_path: Optional[str] = None) -> str:
          """
          Capture screenshot of a Windows application window.
          """
          if not self.powershell_available:
              raise Exception("PowerShell not available - cannot capture Windows applications")
          
          try:
              # Enhanced PowerShell script with PrintWindow support for minimized windows
              ps_script = f'''
              Add-Type -AssemblyName System.Windows.Forms
              Add-Type -AssemblyName System.Drawing
              
              $windowHandle = [IntPtr]{window_id}
              if ($windowHandle -eq 0) {{
                  Write-Error "Invalid window handle"
                  exit 1
              }}
              
              # Define comprehensive Windows API functions
              Add-Type @"
                  using System;
                  using System.Runtime.InteropServices;
                  public class Win32 {{
                      [StructLayout(LayoutKind.Sequential)]
                      public struct RECT {{
                          public int Left, Top, Right, Bottom;
                      }}
                      
                      // Window management APIs
                      [DllImport("user32.dll")]
                      public static extern bool GetWindowRect(IntPtr hWnd, out RECT lpRect);
                      
                      [DllImport("user32.dll")]
                      public static extern bool IsIconic(IntPtr hWnd);
                      
                      [DllImport("user32.dll")]
                      public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
                      
                      [DllImport("user32.dll")]
                      public static extern bool PrintWindow(IntPtr hWnd, IntPtr hdcBlt, uint nFlags);
                      
                      [DllImport("user32.dll")]
                      public static extern bool SetLayeredWindowAttributes(IntPtr hWnd, uint crKey, byte bAlpha, uint dwFlags);
                      
                      [DllImport("user32.dll")]
                      public static extern int GetWindowLong(IntPtr hWnd, int nIndex);
                      
                      [DllImport("user32.dll")]
                      public static extern int SetWindowLong(IntPtr hWnd, int nIndex, int dwNewLong);
                      
                      [DllImport("user32.dll")]
                      public static extern bool SetForegroundWindow(IntPtr hWnd);
                      
                      [DllImport("user32.dll")]
                      public static extern IntPtr GetForegroundWindow();
                      
                      [DllImport("user32.dll")]
                      public static extern bool EnumChildWindows(IntPtr hWndParent, EnumChildProc lpEnumFunc, IntPtr lParam);
                      
                      [DllImport("user32.dll")]
                      public static extern int GetClassName(IntPtr hWnd, System.Text.StringBuilder lpClassName, int nMaxCount);
                      
                      [DllImport("user32.dll")]
                      public static extern IntPtr FindWindowEx(IntPtr hWndParent, IntPtr hWndChildAfter, string lpszClass, string lpszWindow);
                      
                      [DllImport("user32.dll")]
                      public static extern bool PostMessage(IntPtr hWnd, uint Msg, IntPtr wParam, IntPtr lParam);
                      
                      [DllImport("user32.dll")]
                      public static extern IntPtr SendMessage(IntPtr hWnd, uint Msg, IntPtr wParam, IntPtr lParam);
                      
                      [DllImport("user32.dll")]
                      public static extern bool BringWindowToTop(IntPtr hWnd);
                      
                      public delegate bool EnumChildProc(IntPtr hWnd, IntPtr lParam);
                      
                      // Constants
                      public const int SW_HIDE = 0;
                      public const int SW_RESTORE = 9;
                      public const int SW_MINIMIZE = 6;
                      public const int SW_SHOW = 5;
                      public const int GWL_EXSTYLE = -20;
                      public const int WS_EX_LAYERED = 0x80000;
                      public const int LWA_ALPHA = 0x2;
                      public const uint PW_CLIENTONLY = 0x1;
                      public const uint PW_RENDERFULLCONTENT = 0x2;
                      
                      // Windows Messages
                      public const uint WM_KEYDOWN = 0x0100;
                      public const uint WM_KEYUP = 0x0101;
                      public const uint WM_CHAR = 0x0102;
                      public const uint WM_COMMAND = 0x0111;
                      public const uint WM_VSCROLL = 0x0115;
                      
                      // Virtual Key Codes
                      public const int VK_SPACE = 0x20;
                      public const int VK_PRIOR = 0x21;  // Page Up
                      public const int VK_NEXT = 0x22;   // Page Down
                      public const int VK_DOWN = 0x28;   // Down Arrow
                      public const int VK_UP = 0x26;     // Up Arrow
                      public const int VK_LEFT = 0x25;   // Left Arrow
                      public const int VK_RIGHT = 0x27;  // Right Arrow
                  }}
  "@
              
              # Check if window is minimized and implement smart capture logic
              $isMinimized = [Win32]::IsIconic($windowHandle)
              $wasMinimized = $false
              $originalExStyle = 0
              
              try {{
                  # Get window rectangle
                  $rect = New-Object Win32+RECT
                  $success = [Win32]::GetWindowRect($windowHandle, [ref]$rect)
                  
                  if (-not $success) {{
                      Write-Error "Could not get window rectangle"
                      exit 1
                  }}
                  
                  $width = $rect.Right - $rect.Left
                  $height = $rect.Bottom - $rect.Top
                  
                  if ($width -le 0 -or $height -le 0) {{
                      Write-Error "Invalid window dimensions: $($width)x$($height)"
                      exit 1
                  }}
                  
                  # Handle minimized windows with stealth restoration
                  if ($isMinimized) {{
                      Write-Verbose "Window is minimized, using stealth restoration technique"
                      $wasMinimized = $true
                      
                      # Make window transparent for stealth operation
                      $originalExStyle = [Win32]::GetWindowLong($windowHandle, [Win32]::GWL_EXSTYLE)
                      $newExStyle = $originalExStyle -bor [Win32]::WS_EX_LAYERED
                      [Win32]::SetWindowLong($windowHandle, [Win32]::GWL_EXSTYLE, $newExStyle) | Out-Null
                      [Win32]::SetLayeredWindowAttributes($windowHandle, 0, 1, [Win32]::LWA_ALPHA) | Out-Null
                      
                      # Restore window temporarily
                      [Win32]::ShowWindow($windowHandle, [Win32]::SW_RESTORE) | Out-Null
                      Start-Sleep -Milliseconds 100  # Brief pause for window to render
                      
                      # Update rectangle after restoration
                      $success = [Win32]::GetWindowRect($windowHandle, [ref]$rect)
                      if ($success) {{
                          $width = $rect.Right - $rect.Left
                          $height = $rect.Bottom - $rect.Top
                      }}
                  }}
                  
                  # Create bitmap for capture
                  $bitmap = New-Object System.Drawing.Bitmap($width, $height)
                  $graphics = [System.Drawing.Graphics]::FromImage($bitmap)
                  
                  # Try PrintWindow first (better for minimized/hidden windows)
                  $hdcBitmap = $graphics.GetHdc()
                  $printSuccess = [Win32]::PrintWindow($windowHandle, $hdcBitmap, [Win32]::PW_RENDERFULLCONTENT)
                  $graphics.ReleaseHdc($hdcBitmap)
                  
                  # Fallback to CopyFromScreen if PrintWindow fails
                  if (-not $printSuccess) {{
                      Write-Verbose "PrintWindow failed, falling back to CopyFromScreen"
                      if (-not $isMinimized) {{
                          $graphics.CopyFromScreen($rect.Left, $rect.Top, 0, 0, [System.Drawing.Size]::new($width, $height))
                      }} else {{
                          throw "Cannot capture minimized window with CopyFromScreen"
                      }}
                  }}
                  
                  $graphics.Dispose()
                  
                  # Save to temporary file
                  $tempPath = [System.IO.Path]::GetTempFileName() + ".png"
                  $bitmap.Save($tempPath, [System.Drawing.Imaging.ImageFormat]::Png)
                  $bitmap.Dispose()
                  
                  Write-Output $tempPath
                  
              }} finally {{
                  # Restore original window state if it was modified
                  if ($wasMinimized) {{
                      # Restore original transparency
                      [Win32]::SetWindowLong($windowHandle, [Win32]::GWL_EXSTYLE, $originalExStyle) | Out-Null
                      
                      # Re-minimize the window
                      [Win32]::ShowWindow($windowHandle, [Win32]::SW_MINIMIZE) | Out-Null
                  }}
              }}
              '''
              
              result = subprocess.run(
                  ['powershell.exe', '-Command', ps_script],
                  capture_output=True,
                  text=True,
                  check=True,
                  timeout=60,  # 60 second timeout for screenshot capture
                  encoding='utf-8',
                  errors='ignore'  # Ignore encoding errors to handle special characters
              )
              
              temp_windows_path = result.stdout.strip()
              if not temp_windows_path:
                  raise Exception("PowerShell did not return temp file path")
              
              # Convert Windows path to WSL path
              wsl_temp_path = self._windows_path_to_wsl(temp_windows_path)
              
              if output_path is None:
                  timestamp = int(time.time())
                  output_path = f"windows_capture_{window_id}_{timestamp}.png"
              
              # Copy from Windows temp to desired location
              subprocess.run(['cp', wsl_temp_path, output_path], check=True)
              
              # Clean up Windows temp file
              subprocess.run(
                  ['powershell.exe', '-Command', f'Remove-Item "{temp_windows_path}" -Force'],
                  check=False  # Don't fail if cleanup fails
              )
              
              logger.info(f"Windows application captured: {output_path}")
              return output_path

• capture.py:1546-1576 (helper)

  WindowCapture.capture_window: Linux/X11 implementation using wmctrl for window focus/geometry and pyscreenshot (PIL) for region capture.

  def capture_window(self, window_id: str, output_path: Optional[str] = None) -> str:
      """
      Capture screenshot of a specific window.
      """
      try:
          # First focus the window
          if not self.focus_window(window_id):
              logger.warning(f"Could not focus window {window_id}, trying capture anyway")
          
          # Get window geometry
          geometry = self.get_window_geometry(window_id)
          
          if geometry:
              x, y, width, height = geometry
              # Capture the specific region
              screenshot = ImageGrab.grab(bbox=(x, y, x + width, y + height))
          else:
              logger.warning(f"Could not get geometry for window {window_id}, capturing full screen")
              screenshot = ImageGrab.grab()
          
          if output_path is None:
              timestamp = int(time.time())
              output_path = f"window_{window_id}_{timestamp}.png"
          
          screenshot.save(output_path)
          logger.info(f"Window captured: {output_path}")
          return output_path
          
      except Exception as e:
          logger.error(f"Failed to capture window {window_id}: {e}")
          raise

• capture.py:1347-1431 (helper)

  CrossPlatformWindowManager: Dispatches capture_window calls to platform-specific implementations (WindowsWindowManager for WSL/Windows, WindowCapture for Linux). Called by MCP handler.

  class CrossPlatformWindowManager:
      """
      Unified interface that automatically selects the appropriate window manager
      based on the runtime environment.
      """
      
      def __init__(self):
          self.environment = detect_environment()
          self.manager = self._create_manager()
          
      def _create_manager(self):
          """Create appropriate window manager based on environment."""
          if self.environment == 'wsl':
              # In WSL, try Windows manager first, fallback to Linux
              windows_manager = WindowsWindowManager()
              if windows_manager.powershell_available:
                  logger.info("Using Windows application manager (PowerShell from WSL2)")
                  return windows_manager
              else:
                  logger.info("PowerShell unavailable, falling back to Linux X11 manager")
                  return WindowCapture()
          elif self.environment == 'windows':
              logger.info("Using Windows application manager")
              return WindowsWindowManager()
          else:  # linux
              logger.info("Using Linux X11 window manager")
              return WindowCapture()
      
      def list_windows(self) -> List[Dict[str, str]]:
          """List all available windows using the appropriate manager."""
          try:
              windows = self.manager.list_windows()
              
              # Add environment info to each window
              for window in windows:
                  window['environment'] = self.environment
                  if 'type' not in window:
                      window['type'] = 'x11' if self.environment == 'linux' else self.environment
                      
              return windows
          except Exception as e:
              logger.error(f"Failed to list windows: {e}")
              return []
      
      def capture_window(self, window_id: str, output_path: Optional[str] = None) -> str:
          """Capture screenshot of a specific window."""
          return self.manager.capture_window(window_id, output_path)
      
      def capture_full_screen(self, output_path: Optional[str] = None) -> str:
          """Capture full screen screenshot."""
          if hasattr(self.manager, 'capture_full_screen'):
              return self.manager.capture_full_screen(output_path)
          else:
              # Fallback using pyscreenshot
              try:
                  screenshot = ImageGrab.grab()
                  
                  if output_path is None:
                      timestamp = int(time.time())
                      output_path = f"screenshot_{timestamp}.png"
                  
                  screenshot.save(output_path)
                  logger.info(f"Full screen captured: {output_path}")
                  return output_path
                  
              except Exception as e:
                  logger.error(f"Failed to capture full screen: {e}")
                  raise
      
      def get_environment_info(self) -> Dict[str, str]:
          """Get information about the current environment and capabilities."""
          info = {
              'environment': self.environment,
              'manager_type': type(self.manager).__name__
          }
          
          if isinstance(self.manager, WindowsWindowManager):
              info['powershell_available'] = self.manager.powershell_available
          elif isinstance(self.manager, WindowCapture):
              missing_deps = check_dependencies()
              info['missing_dependencies'] = missing_deps
              info['x11_available'] = len(missing_deps) == 0
              
          return info