list_windows
List all macOS windows organized by Spaces to identify which windows belong to each Space, providing detailed window information in JSON or summary format.
Instructions
List all windows organized by macOS Space. Returns detailed information about windows, spaces, and which windows belong to which Space.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format: 'json' (structured data) or 'summary' (human-readable) | json |
Implementation Reference
- capture_win_mcp/server.py:79-141 (handler)Main handler function for the list_windows tool. Refreshes tracker data, handles JSON or summary output formats, and returns structured or human-readable window lists organized by macOS Spaces.async def handle_list_windows(arguments: dict) -> list[TextContent]: """Handle list_windows tool call.""" try: # Refresh tracker data tracker.refresh() format_type = arguments.get("format", "json") if format_type == "json": # Return structured JSON data data = tracker.get_all_data() return [ TextContent( type="text", text=json.dumps(data, indent=2) ) ] else: # summary format # Return human-readable summary data = tracker.get_all_data() windows_by_space = tracker.get_windows_by_space() summary_lines = [] summary_lines.append(f"Total Spaces: {data['summary']['total_spaces']}") summary_lines.append(f"Total Windows: {data['summary']['total_windows']}") summary_lines.append("") # Create space map for quick lookup space_map = {s.get('index'): s for s in data['spaces']} for space_index in sorted(windows_by_space.keys()): windows = windows_by_space[space_index] space_info = space_map.get(space_index, {}) space_label = space_info.get('label', '(unlabeled)') is_visible = space_info.get('is-visible', False) visibility = "VISIBLE" if is_visible else "hidden" summary_lines.append(f"Space {space_index}: {space_label} ({visibility})") summary_lines.append(f" {len(windows)} window(s)") for window in windows: app_name = window.get('app', 'Unknown') title = window.get('title', '(Untitled)') win_id = window.get('id', 0) summary_lines.append(f" - [{app_name}] {title} (ID: {win_id})") summary_lines.append("") return [ TextContent( type="text", text="\n".join(summary_lines) ) ] except Exception as e: return [ TextContent( type="text", text=f"Error listing windows: {str(e)}" ) ]
- capture_win_mcp/server.py:29-44 (schema)Tool schema defining the list_windows tool, including name, description, and optional 'format' input parameter.Tool( name="list_windows", description="List all windows organized by macOS Space. Returns detailed information about windows, spaces, and which windows belong to which Space.", inputSchema={ "type": "object", "properties": { "format": { "type": "string", "description": "Output format: 'json' (structured data) or 'summary' (human-readable)", "enum": ["json", "summary"], "default": "json" } }, "required": [] } ),
- capture_win_mcp/server.py:71-72 (registration)Tool dispatch logic in the call_tool handler that routes list_windows calls to the handle_list_windows function.if name == "list_windows": return await handle_list_windows(arguments)
- capture_win_mcp/tracker.py:59-65 (helper)Refreshes the tracker by querying yabai for current spaces and windows data, called by the list_windows handler.def refresh(self): """Refresh space and window data.""" if self.has_yabai: self.spaces_data = self._query_yabai_spaces() self.windows_data = self._query_yabai_windows() else: raise RuntimeError("yabai not found. Install with: brew install koekeishiya/formulae/yabai")
- capture_win_mcp/tracker.py:45-57 (helper)Core utility that executes yabai query to list all windows, providing the raw data for the list_windows tool.def _query_yabai_windows(self) -> List[Dict]: """Query yabai for window information.""" try: result = subprocess.run( ['yabai', '-m', 'query', '--windows'], capture_output=True, text=True, timeout=5 ) return json.loads(result.stdout) except Exception as e: print(f"Warning: Could not query yabai windows: {e}") return []