remote_macos_mouse_scroll

Instructions

Implementation Reference

• src/action_handlers.py:79-154 (handler)

  Main handler function for remote_macos_mouse_scroll tool. Connects via VNC, scales coordinates from source to target screen, moves mouse, sends Page Up/Down key based on direction for scrolling effect.

  def handle_remote_macos_mouse_scroll(arguments: dict[str, Any]) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
      """Perform a mouse scroll action on a remote MacOs machine."""
      # Use environment variables
      host = MACOS_HOST
      port = MACOS_PORT
      password = MACOS_PASSWORD
      username = MACOS_USERNAME
      encryption = VNC_ENCRYPTION
  
      # Get required parameters from arguments
      x = arguments.get("x")
      y = arguments.get("y")
      source_width = int(arguments.get("source_width", 1366))
      source_height = int(arguments.get("source_height", 768))
      direction = arguments.get("direction", "down")
  
      if x is None or y is None:
          raise ValueError("x and y coordinates are required")
  
      # Ensure source dimensions are positive
      if source_width <= 0 or source_height <= 0:
          raise ValueError("Source dimensions must be positive values")
  
      # Initialize VNC client
      vnc = VNCClient(host=host, port=port, password=password, username=username, encryption=encryption)
  
      # Connect to remote MacOs machine
      success, error_message = vnc.connect()
      if not success:
          error_msg = f"Failed to connect to remote MacOs machine at {host}:{port}. {error_message}"
          return [types.TextContent(type="text", text=error_msg)]
  
      try:
          # Get target screen dimensions
          target_width = vnc.width
          target_height = vnc.height
  
          # Scale coordinates
          scaled_x = int((x / source_width) * target_width)
          scaled_y = int((y / source_height) * target_height)
  
          # Ensure coordinates are within the screen bounds
          scaled_x = max(0, min(scaled_x, target_width - 1))
          scaled_y = max(0, min(scaled_y, target_height - 1))
  
          # First move the mouse to the target location without clicking
          move_result = vnc.send_pointer_event(scaled_x, scaled_y, 0)
  
          # Map of special keys for page up/down
          special_keys = {
              "up": 0xff55,    # Page Up key
              "down": 0xff56,  # Page Down key
          }
  
          # Send the appropriate page key based on direction
          key = special_keys["up" if direction.lower() == "up" else "down"]
          key_result = vnc.send_key_event(key, True) and vnc.send_key_event(key, False)
  
          # Prepare the response with useful details
          scale_factors = {
              "x": target_width / source_width,
              "y": target_height / source_height
          }
  
          return [types.TextContent(
              type="text",
              text=f"""Mouse move to ({scaled_x}, {scaled_y}) {'succeeded' if move_result else 'failed'}
  Page {direction} key press {'succeeded' if key_result else 'failed'}
  Source dimensions: {source_width}x{source_height}
  Target dimensions: {target_width}x{target_height}
  Scale factors: {scale_factors['x']:.4f}x, {scale_factors['y']:.4f}y"""
          )]
      finally:
          # Close VNC connection
          vnc.close()

• src/mcp_remote_macos_use/server.py:141-160 (registration)

  Tool registration in list_tools(), including name, description, and detailed input schema defining parameters for coordinates, scaling, and scroll direction.

  types.Tool(
      name="remote_macos_mouse_scroll",
      description="Perform a mouse scroll at specified coordinates on a remote MacOs machine, with automatic coordinate scaling. Uses environment variables for connection details.",
      inputSchema={
          "type": "object",
          "properties": {
              "x": {"type": "integer", "description": "X coordinate for mouse position (in source dimensions)"},
              "y": {"type": "integer", "description": "Y coordinate for mouse position (in source dimensions)"},
              "source_width": {"type": "integer", "description": "Width of the reference screen for coordinate scaling", "default": 1366},
              "source_height": {"type": "integer", "description": "Height of the reference screen for coordinate scaling", "default": 768},
              "direction": {
                  "type": "string",
                  "description": "Scroll direction",
                  "enum": ["up", "down"],
                  "default": "down"
              }
          },
          "required": ["x", "y"]
      },
  ),

• src/mcp_remote_macos_use/server.py:265-266 (registration)

  Dispatch logic in call_tool() that routes the tool call to the handle_remote_macos_mouse_scroll handler.

  elif name == "remote_macos_mouse_scroll":
      return handle_remote_macos_mouse_scroll(arguments)

• src/mcp_remote_macos_use/server.py:144-160 (schema)

  Input schema defining the parameters: x, y (required), source_width/height (defaults), direction (up/down).

      inputSchema={
          "type": "object",
          "properties": {
              "x": {"type": "integer", "description": "X coordinate for mouse position (in source dimensions)"},
              "y": {"type": "integer", "description": "Y coordinate for mouse position (in source dimensions)"},
              "source_width": {"type": "integer", "description": "Width of the reference screen for coordinate scaling", "default": 1366},
              "source_height": {"type": "integer", "description": "Height of the reference screen for coordinate scaling", "default": 768},
              "direction": {
                  "type": "string",
                  "description": "Scroll direction",
                  "enum": ["up", "down"],
                  "default": "down"
              }
          },
          "required": ["x", "y"]
      },
  ),