android_start_emulator

Instructions

Implementation Reference

• src/tools/android.ts:560-621 (handler)

  The handler function for android_start_emulator tool. Validates input using Zod schema, checks if emulator is already running, spawns the emulator process with options, tracks the PID in runningEmulators map, and sets up exit handler.

  handler: async (args: any) => {
    const validation = AndroidEmulatorStartSchema.safeParse(args);
    if (!validation.success) {
      throw new Error(`Invalid request: ${validation.error.message}`);
    }
  
    const { avdName, options = {} } = validation.data;
  
    // Check if emulator is already running
    if (runningEmulators.has(avdName)) {
      return {
        success: true,
        data: {
          avdName,
          status: 'already_running',
          pid: runningEmulators.get(avdName),
          message: 'Emulator is already running',
        },
      };
    }
  
    const emulator_args = ['-avd', avdName];
    
    if (options.noWindow) {
      emulator_args.push('-no-window');
    }
    
    if (options.port) {
      emulator_args.push('-port', options.port.toString());
    }
    
    if (options.gpu) {
      emulator_args.push('-gpu', options.gpu);
    }
  
    // Start emulator in background
    const emulatorProcess = spawn('emulator', emulator_args, {
      detached: true,
      stdio: 'ignore',
    });
  
    // Track the process
    runningEmulators.set(avdName, emulatorProcess.pid!);
  
    // Handle process exit
    emulatorProcess.on('exit', () => {
      runningEmulators.delete(avdName);
    });
  
    // Unref to allow the parent process to exit
    emulatorProcess.unref();
  
    return {
      success: true,
      data: {
        avdName,
        pid: emulatorProcess.pid,
        status: 'started',
        options,
      },
    };
  }

• src/tools/android.ts:87-94 (schema)

  Zod validation schema used in the handler for input parameters: avdName (required string), options (optional object with noWindow boolean, port number 5554-5682, gpu enum).

  const AndroidEmulatorStartSchema = z.object({
    avdName: z.string().min(1),
    options: z.object({
      noWindow: z.boolean().optional(),
      port: z.number().min(5554).max(5682).optional(),
      gpu: z.enum(['auto', 'host', 'swiftshader_indirect', 'angle_indirect', 'guest']).optional(),
    }).optional(),
  });

• src/tools/android.ts:538-622 (registration)

  Registration of the android_start_emulator tool within the createAndroidTools function. Defines name, description, inputSchema (JSON schema), and references the handler function.

  tools.set('android_start_emulator', {
    name: 'android_start_emulator',
    description: 'Start an Android emulator',
    inputSchema: {
      type: 'object',
      properties: {
        avdName: { type: 'string', minLength: 1, description: 'AVD name to start' },
        options: {
          type: 'object',
          properties: {
            noWindow: { type: 'boolean', description: 'Run without UI window' },
            port: { type: 'number', minimum: 5554, maximum: 5682, description: 'Console port number' },
            gpu: { 
              type: 'string', 
              enum: ['auto', 'host', 'swiftshader_indirect', 'angle_indirect', 'guest'],
              description: 'GPU acceleration mode'
            }
          }
        }
      },
      required: ['avdName']
    },
    handler: async (args: any) => {
      const validation = AndroidEmulatorStartSchema.safeParse(args);
      if (!validation.success) {
        throw new Error(`Invalid request: ${validation.error.message}`);
      }
  
      const { avdName, options = {} } = validation.data;
  
      // Check if emulator is already running
      if (runningEmulators.has(avdName)) {
        return {
          success: true,
          data: {
            avdName,
            status: 'already_running',
            pid: runningEmulators.get(avdName),
            message: 'Emulator is already running',
          },
        };
      }
  
      const emulator_args = ['-avd', avdName];
      
      if (options.noWindow) {
        emulator_args.push('-no-window');
      }
      
      if (options.port) {
        emulator_args.push('-port', options.port.toString());
      }
      
      if (options.gpu) {
        emulator_args.push('-gpu', options.gpu);
      }
  
      // Start emulator in background
      const emulatorProcess = spawn('emulator', emulator_args, {
        detached: true,
        stdio: 'ignore',
      });
  
      // Track the process
      runningEmulators.set(avdName, emulatorProcess.pid!);
  
      // Handle process exit
      emulatorProcess.on('exit', () => {
        runningEmulators.delete(avdName);
      });
  
      // Unref to allow the parent process to exit
      emulatorProcess.unref();
  
      return {
        success: true,
        data: {
          avdName,
          pid: emulatorProcess.pid,
          status: 'started',
          options,
        },
      };
    }
  });

• src/utils/tool-categories.ts:142-150 (helper)

  Metadata registration in tool registry: categorizes as ESSENTIAL android tool requiring EMULATOR, with performance expectations.

  'android_start_emulator': {
    name: 'android_start_emulator',
    category: ToolCategory.ESSENTIAL,
    platform: 'android',
    requiredTools: [RequiredTool.EMULATOR],
    description: 'Start Android emulator',
    safeForTesting: false,
    performance: { expectedDuration: 60000, timeout: 180000 }
  },