mcp-remote-macos-use

Instructions

Implementation Reference

• src/action_handlers.py:486-557 (handler)

  The handler function that executes the tool logic: opens Spotlight with Cmd+Space, types the app identifier, and presses Enter to launch it via VNC key events.

  def handle_remote_macos_open_application(arguments: dict[str, Any]) -> List[types.TextContent]:
      """
      Opens or activates an application on the remote MacOS machine using VNC.
  
      Args:
          arguments: Dictionary containing:
              - identifier: App name, path, or bundle ID
  
      Returns:
          List containing a TextContent with the result
      """
      # Use environment variables
      host = MACOS_HOST
      port = MACOS_PORT
      password = MACOS_PASSWORD
      username = MACOS_USERNAME
      encryption = VNC_ENCRYPTION
  
      identifier = arguments.get("identifier")
      if not identifier:
          raise ValueError("identifier is required")
  
      start_time = time.time()
  
      # 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:
          # Send Command+Space to open Spotlight
          cmd_key = 0xffeb  # Command key
          space_key = 0x20  # Space key
  
          # Press Command+Space
          vnc.send_key_event(cmd_key, True)
          vnc.send_key_event(space_key, True)
  
          # Release Command+Space
          vnc.send_key_event(space_key, False)
          vnc.send_key_event(cmd_key, False)
  
          # Small delay to let Spotlight open
          time.sleep(0.5)
  
          # Type the application name
          vnc.send_text(identifier)
  
          # Small delay to let Spotlight find the app
          time.sleep(0.5)
  
          # Press Enter to launch
          enter_key = 0xff0d
          vnc.send_key_event(enter_key, True)
          vnc.send_key_event(enter_key, False)
  
          end_time = time.time()
          processing_time = round(end_time - start_time, 3)
  
          return [types.TextContent(
              type="text",
              text=f"Launched application: {identifier}\nProcessing time: {processing_time}s"
          )]
  
      finally:
          # Close VNC connection
          vnc.close()

• src/mcp_remote_macos_use/server.py:218-231 (registration)

  Tool registration in the list_tools() method, including name, description, and input schema definition.

  types.Tool(
      name="remote_macos_open_application",
      description="Opens/activates an application and returns its PID for further interactions.",
      inputSchema={
          "type": "object",
          "properties": {
              "identifier": {
                  "type": "string",
                  "description": "REQUIRED. App name, path, or bundle ID."
              }
          },
          "required": ["identifier"]
      },
  ),

• src/mcp_remote_macos_use/server.py:280-281 (registration)

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

  elif name == "remote_macos_open_application":
      return handle_remote_macos_open_application(arguments)

• src/mcp_remote_macos_use/server.py:221-229 (schema)

  Input schema definition for the tool, specifying the required 'identifier' parameter.

  inputSchema={
      "type": "object",
      "properties": {
          "identifier": {
              "type": "string",
              "description": "REQUIRED. App name, path, or bundle ID."
          }
      },
      "required": ["identifier"]