capture_window
Take screenshots of specific macOS windows by ID using yabai integration. Get window IDs from list_windows tool first, then capture images as base64-encoded PNG files with optional shadow inclusion.
Instructions
Capture a screenshot of a specific window by its ID. Returns the image as base64-encoded PNG. Use list_windows first to get window IDs.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| window_id | Yes | The window ID to capture (from list_windows) | |
| include_shadow | No | Include window shadow in the capture |
Implementation Reference
- capture_win_mcp/server.py:143-241 (handler)The primary handler function implementing the capture_window tool logic. It processes input arguments, verifies the window, uses subprocess to run macOS 'screencapture' command on the window ID, encodes the resulting PNG to base64, and returns TextContent with description and ImageContent with the screenshot.async def handle_capture_window(arguments: dict) -> list[ImageContent | TextContent]: """Handle capture_window tool call.""" try: window_id = arguments.get("window_id") include_shadow = arguments.get("include_shadow", True) if window_id is None: return [ TextContent( type="text", text="Error: window_id is required" ) ] # Refresh tracker to verify window exists tracker.refresh() window = tracker.get_window_by_id(window_id) if not window: return [ TextContent( type="text", text=f"Error: Window with ID {window_id} not found" ) ] # Create temporary file for screenshot temp_file = Path(f"/tmp/capture_win_{window_id}.png") # Build screencapture command cmd = ["screencapture", "-x"] # -x: no sound if not include_shadow: cmd.append("-o") # -o: no shadow cmd.extend(["-l", str(window_id)]) # -l: capture window by ID cmd.append(str(temp_file)) # Capture the window result = subprocess.run( cmd, capture_output=True, text=True, timeout=10 ) if result.returncode != 0: return [ TextContent( type="text", text=f"Error capturing window: {result.stderr}" ) ] # Read and encode the image if not temp_file.exists(): return [ TextContent( type="text", text="Error: Screenshot file not created" ) ] image_data = temp_file.read_bytes() base64_image = base64.b64encode(image_data).decode('utf-8') # Clean up temporary file temp_file.unlink() # Get window details for context app_name = window.get('app', 'Unknown') title = window.get('title', '(Untitled)') return [ TextContent( type="text", text=f"Captured window: [{app_name}] {title} (ID: {window_id})" ), ImageContent( type="image", data=base64_image, mimeType="image/png" ) ] except subprocess.TimeoutExpired: return [ TextContent( type="text", text="Error: Screenshot capture timed out" ) ] except Exception as e: return [ TextContent( type="text", text=f"Error capturing window: {str(e)}" ) ]
- capture_win_mcp/server.py:48-62 (schema)Input JSON schema for the capture_window tool, specifying the required 'window_id' parameter and optional 'include_shadow' boolean.inputSchema={ "type": "object", "properties": { "window_id": { "type": "integer", "description": "The window ID to capture (from list_windows)" }, "include_shadow": { "type": "boolean", "description": "Include window shadow in the capture", "default": True } }, "required": ["window_id"] }
- capture_win_mcp/server.py:45-63 (registration)Tool registration in list_tools(): defines the MCP Tool object for 'capture_window' with name, description, and input schema.Tool( name="capture_window", description="Capture a screenshot of a specific window by its ID. Returns the image as base64-encoded PNG. Use list_windows first to get window IDs.", inputSchema={ "type": "object", "properties": { "window_id": { "type": "integer", "description": "The window ID to capture (from list_windows)" }, "include_shadow": { "type": "boolean", "description": "Include window shadow in the capture", "default": True } }, "required": ["window_id"] } )
- capture_win_mcp/server.py:73-74 (registration)Dispatch registration in @app.call_tool(): routes calls to 'capture_window' to the handler function.elif name == "capture_window": return await handle_capture_window(arguments)