remote_macos_mouse_click

Click at specified coordinates on a remote macOS machine with automatic coordinate scaling. Uses environment variables for connection details.

Instructions

Perform a mouse click at specified coordinates on a remote MacOs machine, with automatic coordinate scaling. Uses environment variables for connection details.

Input Schema

TableJSON Schema

Name	Required	Description
`x`	Yes	X coordinate for mouse position (in source dimensions)
`y`	Yes	Y coordinate for mouse position (in source dimensions)
`source_width`	No	Width of the reference screen for coordinate scaling
`source_height`	No	Height of the reference screen for coordinate scaling
`button`	No	Mouse button (1=left, 2=middle, 3=right)

Implementation Reference

src/action_handlers.py:156-220 (handler)

The core handler function that connects to the remote Mac via VNC, scales input coordinates based on screen dimensions, performs the mouse click using VNCClient.send_mouse_click, and returns a text response with details on the action.

def handle_remote_macos_mouse_click(arguments: dict[str, Any]) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
    """Perform a mouse click 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))
    button = int(arguments.get("button", 1))

    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))

        # Single click
        result = vnc.send_mouse_click(scaled_x, scaled_y, button, 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 click (button {button}) from source ({x}, {y}) to target ({scaled_x}, {scaled_y}) {'succeeded' if 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:191-201 (schema)

Input schema definition for the tool, specifying parameters like x, y coordinates, source dimensions for scaling, and mouse button.

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},
        "button": {"type": "integer", "description": "Mouse button (1=left, 2=middle, 3=right)", "default": 1}
    },
    "required": ["x", "y"]
},

src/mcp_remote_macos_use/server.py:188-202 (registration)

Tool registration in the list_tools handler, defining name, description, and input schema.

types.Tool(
    name="remote_macos_mouse_click",
    description="Perform a mouse click 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},
            "button": {"type": "integer", "description": "Mouse button (1=left, 2=middle, 3=right)", "default": 1}
        },
        "required": ["x", "y"]
    },
),

src/mcp_remote_macos_use/server.py:274-275 (registration)
Dispatch logic in call_tool handler that routes calls to the specific handler function.
```
elif name == "remote_macos_mouse_click":
    return handle_remote_macos_mouse_click(arguments)
```

mcp-remote-macos-use