XcodeBuildMCP

Instructions

Implementation Reference

• src/mcp/tools/macos/launch_mac_app.ts:27-75 (handler)

  The main handler function launch_mac_appLogic that validates the app path, constructs the 'open' command with optional args, executes it, and returns success or error response.

  export async function launch_mac_appLogic(
    params: LaunchMacAppParams,
    executor: CommandExecutor,
    fileSystem?: FileSystemExecutor,
  ): Promise<ToolResponse> {
    // Validate that the app file exists
    const fileExistsValidation = validateFileExists(params.appPath, fileSystem);
    if (!fileExistsValidation.isValid) {
      return fileExistsValidation.errorResponse!;
    }
  
    log('info', `Starting launch macOS app request for ${params.appPath}`);
  
    try {
      // Construct the command as string array for CommandExecutor
      const command = ['open', params.appPath];
  
      // Add any additional arguments if provided
      if (params.args && Array.isArray(params.args) && params.args.length > 0) {
        command.push('--args', ...params.args);
      }
  
      // Execute the command using CommandExecutor
      await executor(command, 'Launch macOS App');
  
      // 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}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/mcp/tools/macos/launch_mac_app.ts:17-22 (schema)

  Zod schema defining input parameters: appPath (string, required), args (optional array of strings).

  const launchMacAppSchema = z.object({
    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/mcp/tools/macos/launch_mac_app.ts:77-83 (registration)

  Tool registration exporting the tool object with name 'launch_mac_app', description, schema, and wrapped handler.

  export default {
    name: 'launch_mac_app',
    description:
      "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.",
    schema: launchMacAppSchema.shape, // MCP SDK compatibility
    handler: createTypedTool(launchMacAppSchema, launch_mac_appLogic, getDefaultCommandExecutor),
  };