hyprland-mcp

Instructions

Implementation Reference

• hyprland_mcp/screenshot.py:138-177 (handler)

  The actual implementation of taking a screenshot and preparing the coordinate mapping.

  async def take_screenshot(
      monitor: str | None = None,
      window: str | None = None,
      region: str | None = None,
      max_width: int = 1024,
      quality: int = 60,
      include_cursor: bool = False,
  ) -> tuple[Image, str]:
      """Capture a screenshot, resize to fit max_width.
  
      Returns (Image, coordinate_info_string) where coordinate_info_string
      explains how to map image pixel positions to absolute screen coordinates.
      """
      png_bytes, origin_x, origin_y = await capture_raw(
          monitor=monitor, window=window, region=region, include_cursor=include_cursor,
      )
  
      # Get native dimensions before resize
      native_img = PILImage.open(io.BytesIO(png_bytes))
      native_w, native_h = native_img.width, native_img.height
  
      image, scale = resize_and_compress(png_bytes, max_width=max_width, quality=quality)
  
      # Build coordinate mapping info
      img_w = int(native_w * scale) if scale != 1.0 else native_w
      img_h = int(native_h * scale) if scale != 1.0 else native_h
      inv_scale = 1.0 / scale if scale != 1.0 else 1.0
  
      coord_info = (
          f"Coordinate mapping: This {img_w}x{img_h} image covers screen region "
          f"starting at absolute ({origin_x}, {origin_y}), "
          f"native size {native_w}x{native_h}.\n"
          f"To convert image coordinates to absolute screen coordinates:\n"
          f"  screen_x = image_x * {inv_scale:.2f} + {origin_x}\n"
          f"  screen_y = image_y * {inv_scale:.2f} + {origin_y}\n"
          f"IMPORTANT: Always use absolute screen coordinates with mouse tools, "
          f"never raw image pixel positions."
      )
  
      return image, coord_info

• hyprland_mcp/server.py:378-413 (registration)

  The registration of the "screenshot" tool in the MCP server.

  async def screenshot(
      monitor: str | None = None,
      window: str | None = None,
      region: str | None = None,
      max_width: int = 1024,
      quality: int = 60,
      include_cursor: bool = False,
  ) -> list:
      """Take a screenshot and return it as an inline image with coordinate mapping.
  
      Returns the image AND a coordinate mapping guide so you can convert image
      pixel positions to absolute screen coordinates for mouse tools.
  
      Supports three capture modes:
      - Full desktop/monitor (default): overview at reduced resolution
      - Window: capture a specific window by class/title
      - Region: capture a specific rectangle at higher resolution
  
      Args:
          monitor: Capture a specific monitor (e.g. "DP-1"). Default: all monitors.
          window: Capture a specific window by selector (e.g. "class:firefox")
          region: Capture a region as "X,Y WxH" (e.g. "100,200 800x600")
          max_width: Maximum output width in pixels (default 1024, lower = smaller output)
          quality: JPEG quality 1-100 (default 60, lower = smaller output)
          include_cursor: Whether to include the cursor in the screenshot
      """
      from . import screenshot as ss
      image, coord_info = await ss.take_screenshot(
          monitor=monitor,
          window=window,
          region=region,
          max_width=max_width,
          quality=quality,
          include_cursor=include_cursor,
      )
      return [image, coord_info]