Auto-Snap MCP

Instructions

List all available windows for screenshot capture.

Returns:
    JSON string containing list of windows with their IDs, titles, and properties.

Implementation Reference

• server.py:71-102 (handler)

  Primary MCP tool handler and registration for 'list_windows'. Initializes CrossPlatformWindowManager, lists windows, adds environment info, and returns formatted JSON response.

  @mcp.tool()
  async def list_windows() -> str:
      """
      List all available windows for screenshot capture.
      
      Returns:
          JSON string containing list of windows with their IDs, titles, and properties.
      """
      try:
          wm = get_window_manager()
          windows = wm.list_windows()
          env_info = wm.get_environment_info()
          
          result = {
              "status": "success",
              "windows": windows,
              "count": len(windows),
              "environment": env_info
          }
          
          return json.dumps(result, indent=2)
          
      except Exception as e:
          logger.error(f"Failed to list windows: {e}")
          return json.dumps({
              "status": "error",
              "error": str(e),
              "windows": [],
              "count": 0,
              "environment": {"error": "Could not determine environment"}
          })

• capture.py:1375-1390 (helper)

  CrossPlatformWindowManager.list_windows(): Platform-agnostic wrapper that delegates to specific manager (WindowsWindowManager or WindowCapture) and enriches window data with environment information.

  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 []

• capture.py:75-234 (helper)

  WindowsWindowManager.list_windows(): Core implementation for Windows using detailed PowerShell script with Win32 API calls to enumerate capturable windows (visible, minimized, maximized) with properties like ID, title, process info, state.

      def list_windows(self) -> List[Dict[str, str]]:
          """
          List all Windows applications with visible windows using PowerShell.
          Returns list of window info dictionaries.
          """
          if not self.powershell_available:
              logger.error("PowerShell not available - cannot list Windows applications")
              return []
              
          try:
              # Enhanced PowerShell script to get comprehensive window information
              ps_script = '''
              Add-Type -TypeDefinition @"
                  using System;
                  using System.Runtime.InteropServices;
                  using System.Text;
                  
                  public class Win32 {
                      [DllImport("user32.dll")]
                      public static extern bool IsWindowVisible(IntPtr hWnd);
                      
                      [DllImport("user32.dll")]
                      public static extern bool IsIconic(IntPtr hWnd);
                      
                      [DllImport("user32.dll")]
                      public static extern bool IsZoomed(IntPtr hWnd);
                      
                      [DllImport("user32.dll")]
                      public static extern int GetWindowText(IntPtr hWnd, StringBuilder lpString, int nMaxCount);
                      
                      [DllImport("user32.dll")]
                      public static extern int GetWindowTextLength(IntPtr hWnd);
                      
                      [DllImport("user32.dll")]
                      public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint lpdwProcessId);
                  }
  "@
  
              $windows = @()
  
              # Get processes with capturable windows only
              Get-Process | Where-Object { 
                  $_.MainWindowHandle -ne 0 -and $_.ProcessName -notmatch "^(dwm|csrss|winlogon|wininit)$"
              } | ForEach-Object {
                  $handle = [IntPtr]$_.MainWindowHandle
                  $isVisible = [Win32]::IsWindowVisible($handle)
                  $isMinimized = [Win32]::IsIconic($handle)
                  $isMaximized = [Win32]::IsZoomed($handle)
                  
                  # Only include windows that are in capturable states
                  # Skip hidden windows that can't be meaningfully captured
                  if (-not ($isVisible -or $isMinimized)) {
                      return  # Skip this window
                  }
                  
                  # Get window title using Windows API (more reliable than MainWindowTitle)
                  $titleLength = [Win32]::GetWindowTextLength($handle)
                  if ($titleLength -gt 0) {
                      $title = New-Object System.Text.StringBuilder($titleLength + 1)
                      [Win32]::GetWindowText($handle, $title, $title.Capacity) | Out-Null
                      $windowTitle = $title.ToString()
                  } else {
                      $windowTitle = $_.MainWindowTitle
                  }
                  
                  # Include window even if title is empty, but provide useful info
                  if ([string]::IsNullOrEmpty($windowTitle)) {
                      $windowTitle = "[$($_.ProcessName) - $($_.Id)]"
                  }
                  
                  # Determine window state - only capturable states
                  $windowState = if ($isMinimized) { 
                      "minimized" 
                  } elseif ($isMaximized) { 
                      "maximized" 
                  } else { 
                      "normal" 
                  }
                  
                  $windows += @{
                      id = $_.MainWindowHandle.ToString()
                      title = $windowTitle
                      process_name = $_.ProcessName
                      process_id = $_.Id.ToString()
                      window_handle = $_.MainWindowHandle.ToString()
                      is_visible = $isVisible
                      is_minimized = $isMinimized
                      is_maximized = $isMaximized
                      window_state = $windowState
                      type = "windows"
                  }
              }
  
              # Convert to JSON
              $windows | ConvertTo-Json -Compress
              '''
              
              result = subprocess.run(
                  ['powershell.exe', '-Command', ps_script],
                  capture_output=True,
                  text=True,
                  check=True,
                  timeout=30,  # 30 second timeout for window enumeration
                  encoding='utf-8',
                  errors='ignore'  # Ignore encoding errors to handle special characters
              )
              
              import json
              if result.stdout.strip():
                  try:
                      # Handle both single object and array responses
                      data = json.loads(result.stdout.strip())
                      if isinstance(data, dict):
                          data = [data]  # Convert single result to list
                      
                      windows = []
                      for window_info in data:
                          # Only include windows with valid window handles (> 0)
                          window_handle = str(window_info.get('window_handle', '0'))
                          if window_handle == '0':
                              continue  # Skip processes without actual windows
                          
                          # Use the enhanced window information from the new PowerShell script
                          windows.append({
                              'id': str(window_info.get('id', '')),
                              'title': window_info.get('title', ''),
                              'process_name': window_info.get('process_name', ''),
                              'process_id': str(window_info.get('process_id', '')),
                              'window_handle': window_handle,
                              'is_visible': window_info.get('is_visible', False),
                              'is_minimized': window_info.get('is_minimized', False),
                              'is_maximized': window_info.get('is_maximized', False),
                              'window_state': window_info.get('window_state', 'normal'),  # Default to normal instead of unknown
                              'type': 'windows'
                          })
                      
                      logger.info(f"Found {len(windows)} capturable windows using enhanced detection")
                      if windows:
                          # Log stats about capturable window states for debugging
                          normal_count = sum(1 for w in windows if w['window_state'] == 'normal')
                          minimized_count = sum(1 for w in windows if w['window_state'] == 'minimized')
                          maximized_count = sum(1 for w in windows if w['window_state'] == 'maximized')
                          logger.info(f"Window states: {normal_count} normal, {minimized_count} minimized, {maximized_count} maximized")
                      
                      return windows
                  except json.JSONDecodeError as e:
                      logger.error(f"Failed to parse PowerShell JSON output: {e}")
                      logger.error(f"PowerShell output was: {result.stdout[:500]}...")  # Log first 500 chars for debugging
                      return []
              else:
                  logger.warning("PowerShell returned empty output - no windows detected")
                  return []
              
          except subprocess.TimeoutExpired:
              logger.error("PowerShell window enumeration timed out after 30 seconds")
              return []
          except subprocess.CalledProcessError as e:
              logger.error(f"Failed to list Windows applications: {e}")
              return []

• capture.py:1439-1479 (helper)

  WindowCapture.list_windows(): Linux/X11-specific implementation using 'wmctrl -l' command to list windows with basic properties (ID, title, desktop, machine).

  def list_windows(self) -> List[Dict[str, str]]:
      """
      List all available windows using wmctrl command.
      Returns list of window info dictionaries.
      """
      try:
          # Use wmctrl to list windows
          result = subprocess.run(
              ['wmctrl', '-l'],
              capture_output=True,
              text=True,
              check=True,
              timeout=10  # 10 second timeout for window listing
          )
          
          windows = []
          for line in result.stdout.strip().split('\n'):
              if line.strip():
                  parts = line.split(None, 3)
                  if len(parts) >= 4:
                      window_id = parts[0]
                      desktop = parts[1]
                      machine = parts[2]
                      title = parts[3]
                      
                      windows.append({
                          'id': window_id,
                          'title': title,
                          'desktop': desktop,
                          'machine': machine
                      })
          
          return windows
          
      except subprocess.CalledProcessError as e:
          logger.error(f"Failed to list windows with wmctrl: {e}")
          return []
      except FileNotFoundError:
          logger.error("wmctrl not found. Please install: sudo apt-get install wmctrl")
          return []