launch_mac_app

Instructions

Implementation Reference

• src/tools/launch.ts:41-91 (handler)

  The asynchronous handler function that implements the core logic for the 'launch_mac_app' tool. It validates the appPath, checks if the file exists, constructs an 'open' command (optionally with args), executes it using promisified exec, and returns success or error responses with markdown text.

    async (params): Promise<ToolResponse> => {
      // Validate required parameters
      const appPathValidation = validateRequiredParam('appPath', params.appPath);
      if (!appPathValidation.isValid) {
        return appPathValidation.errorResponse!;
      }
  
      // Validate that the app file exists
      const fileExistsValidation = await validateFileExists(params.appPath);
      if (!fileExistsValidation.isValid) {
        return fileExistsValidation.errorResponse!;
      }
  
      log('info', `Starting launch macOS app request for ${params.appPath}`);
  
      try {
        // Construct the command
        let command = `open "${params.appPath}"`;
  
        // Add any additional arguments if provided
        if (params.args && params.args.length > 0) {
          command += ` --args ${params.args.join(' ')}`;
        }
  
        // Execute the command
        await execPromise(command);
  
        // Return success response
        return {
          content: [
            {
              type: 'text',
              text: `✅ macOS app launched successfully: ${params.appPath}`,
            },
          ],
        };
      } catch (error) {
        // Handle errors
        const errorMessage = error instanceof Error ? error.message : String(error);
        log('error', `Error during launch macOS app operation: ${errorMessage}`);
        return {
          content: [
            {
              type: 'text',
              text: `❌ Launch macOS app operation failed: ${errorMessage}`,
            },
          ],
        };
      }
    },
  );

• src/tools/launch.ts:35-40 (schema)

  Zod schema defining the input parameters for the 'launch_mac_app' tool: required 'appPath' string and optional 'args' array of strings.

  {
    appPath: z
      .string()
      .describe('Path to the macOS .app bundle to launch (full path to the .app directory)'),
    args: z.array(z.string()).optional().describe('Additional arguments to pass to the app'),
  },

• src/tools/launch.ts:31-92 (registration)

  The registerLaunchMacOSAppTool function registers the 'launch_mac_app' tool on the MCP server, providing name, description, input schema, and handler.

  export function registerLaunchMacOSAppTool(server: McpServer): void {
    server.tool(
      'launch_mac_app',
      "Launches a macOS application. IMPORTANT: You MUST provide the appPath parameter. Example: launch_mac_app({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_launch_macos_app.",
      {
        appPath: z
          .string()
          .describe('Path to the macOS .app bundle to launch (full path to the .app directory)'),
        args: z.array(z.string()).optional().describe('Additional arguments to pass to the app'),
      },
      async (params): Promise<ToolResponse> => {
        // Validate required parameters
        const appPathValidation = validateRequiredParam('appPath', params.appPath);
        if (!appPathValidation.isValid) {
          return appPathValidation.errorResponse!;
        }
  
        // Validate that the app file exists
        const fileExistsValidation = await validateFileExists(params.appPath);
        if (!fileExistsValidation.isValid) {
          return fileExistsValidation.errorResponse!;
        }
  
        log('info', `Starting launch macOS app request for ${params.appPath}`);
  
        try {
          // Construct the command
          let command = `open "${params.appPath}"`;
  
          // Add any additional arguments if provided
          if (params.args && params.args.length > 0) {
            command += ` --args ${params.args.join(' ')}`;
          }
  
          // Execute the command
          await execPromise(command);
  
          // Return success response
          return {
            content: [
              {
                type: 'text',
                text: `✅ macOS app launched successfully: ${params.appPath}`,
              },
            ],
          };
        } catch (error) {
          // Handle errors
          const errorMessage = error instanceof Error ? error.message : String(error);
          log('error', `Error during launch macOS app operation: ${errorMessage}`);
          return {
            content: [
              {
                type: 'text',
                text: `❌ Launch macOS app operation failed: ${errorMessage}`,
              },
            ],
          };
        }
      },
    );
  }

• src/utils/register-tools.ts:395-398 (registration)

  Configuration entry in the toolRegistrations array that includes registerLaunchMacOSAppTool, associating it with workflow groups and an enabling environment variable. This leads to the tool being registered via registerIfEnabled in registerTools.

    register: registerLaunchMacOSAppTool,
    groups: [ToolGroup.MACOS_WORKFLOW, ToolGroup.APP_DEPLOYMENT],
    envVar: 'XCODEBUILDMCP_TOOL_LAUNCH_MACOS_APP',
  },