list_windows
Retrieve detailed window information organized by macOS Spaces, including which windows belong to each Space, for system monitoring and management.
Instructions
List all windows organized by macOS Space. Returns detailed information about windows, spaces, and which windows belong to which Space.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format: 'json' (structured data) or 'summary' (human-readable) | json |
Input Schema (JSON Schema)
{
"properties": {
"format": {
"default": "json",
"description": "Output format: 'json' (structured data) or 'summary' (human-readable)",
"enum": [
"json",
"summary"
],
"type": "string"
}
},
"required": [],
"type": "object"
}
Implementation Reference
- capture_win_mcp/server.py:79-141 (handler)The primary handler function for the 'list_windows' tool. It refreshes the window tracker, processes the optional 'format' argument, and returns either structured JSON data or a human-readable summary of windows 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 (registration)Registers the 'list_windows' tool in the MCP server's list_tools() method, including its name, description, and input schema.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:32-43 (schema)Defines the input schema for the 'list_windows' tool, specifying an optional 'format' parameter with 'json' or 'summary' options.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/tracker.py:59-65 (helper)Supporting method called by the handler to refresh the latest spaces and windows data from yabai.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-58 (helper)Queries the yabai tool via subprocess to retrieve the list of all windows as JSON.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 []