flutter_dev_session

Set up Flutter development sessions by checking environment, listing devices, selecting optimal hardware, and running projects with hot reload for efficient mobile app development.

Instructions

Complete Flutter dev setup: check env, list devices, select best device, run with hot reload

Input Schema

TableJSON Schema

Name	Required	Description
`cwd`	Yes	Working directory (Flutter project root)
`target`	No	Target dart file (e.g., lib/main.dart)
`preferPhysical`	No	Prefer physical device over emulator

Implementation Reference

src/tools/super-tools.ts:154-228 (handler)

Core handler implementing the complete Flutter development session workflow: flutter doctor check, device detection and selection (preferring physical devices), app launch with hot reload support, and automatic emulator launch fallback with recursive retry.

handler: async (args: any) => {
  const steps = [];
  
  try {
    // Step 1: Run flutter doctor
    const doctorTool = flutterTools.get('flutter_doctor');
    const doctorResult = await doctorTool.handler({});
    steps.push({ step: 'doctor', ...doctorResult });
    
    // Step 2: List available devices
    const listTool = flutterTools.get('flutter_list_devices');
    const devicesResult = await listTool.handler({});
    steps.push({ step: 'list_devices', ...devicesResult });
    
    // Step 3: Select best device
    let selectedDevice = null;
    if (devicesResult.success && devicesResult.data?.devices?.length > 0) {
      const devices = devicesResult.data.devices;
      
      // Prioritize based on preference
      if (args.preferPhysical) {
        selectedDevice = devices.find((d: any) => !d.emulator) || devices[0];
      } else {
        selectedDevice = devices[0];
      }
    }
    
    // Step 4: Run flutter app
    if (selectedDevice) {
      const runTool = flutterTools.get('flutter_run');
      const runResult = await runTool.handler({
        cwd: args.cwd,
        deviceId: selectedDevice.id,
        target: args.target
      });
      steps.push({ step: 'run', ...runResult });
      
      return {
        success: true,
        data: {
          selectedDevice,
          sessionId: runResult.data?.sessionId,
          steps,
          message: `Flutter dev session started on ${selectedDevice.name}`
        }
      };
    } else {
      // No device available - try to start emulator
      const emulatorsResult = await flutterTools.get('flutter_list_emulators').handler({});
      
      if (emulatorsResult.success && emulatorsResult.data?.emulators?.length > 0) {
        const emulator = emulatorsResult.data.emulators[0];
        await flutterTools.get('flutter_launch_emulator').handler({ 
          emulatorId: emulator.id 
        });
        
        // Wait and retry
        await new Promise(resolve => setTimeout(resolve, 5000));
        return tools.get('flutter_dev_session').handler(args);
      }
      
      return {
        success: false,
        error: 'No devices available and no emulators to launch',
        steps
      };
    }
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : String(error),
      steps
    };
  }
}

src/tools/super-tools.ts:135-153 (schema)

Input schema defining parameters for the tool: cwd (required), optional target file and preferPhysical flag.

inputSchema: {
  type: 'object',
  properties: {
    cwd: {
      type: 'string',
      description: 'Working directory (Flutter project root)'
    },
    target: {
      type: 'string', 
      description: 'Target dart file (e.g., lib/main.dart)'
    },
    preferPhysical: {
      type: 'boolean',
      description: 'Prefer physical device over emulator',
      default: true
    }
  },
  required: ['cwd']
},

src/tools/super-tools.ts:132-229 (registration)

Registration of the flutter_dev_session super-tool in the tools Map within createSuperTools function.

tools.set('flutter_dev_session', {
  name: 'flutter_dev_session',
  description: 'Complete Flutter dev setup: check env, list devices, select best device, run with hot reload',
  inputSchema: {
    type: 'object',
    properties: {
      cwd: {
        type: 'string',
        description: 'Working directory (Flutter project root)'
      },
      target: {
        type: 'string', 
        description: 'Target dart file (e.g., lib/main.dart)'
      },
      preferPhysical: {
        type: 'boolean',
        description: 'Prefer physical device over emulator',
        default: true
      }
    },
    required: ['cwd']
  },
  handler: async (args: any) => {
    const steps = [];
    
    try {
      // Step 1: Run flutter doctor
      const doctorTool = flutterTools.get('flutter_doctor');
      const doctorResult = await doctorTool.handler({});
      steps.push({ step: 'doctor', ...doctorResult });
      
      // Step 2: List available devices
      const listTool = flutterTools.get('flutter_list_devices');
      const devicesResult = await listTool.handler({});
      steps.push({ step: 'list_devices', ...devicesResult });
      
      // Step 3: Select best device
      let selectedDevice = null;
      if (devicesResult.success && devicesResult.data?.devices?.length > 0) {
        const devices = devicesResult.data.devices;
        
        // Prioritize based on preference
        if (args.preferPhysical) {
          selectedDevice = devices.find((d: any) => !d.emulator) || devices[0];
        } else {
          selectedDevice = devices[0];
        }
      }
      
      // Step 4: Run flutter app
      if (selectedDevice) {
        const runTool = flutterTools.get('flutter_run');
        const runResult = await runTool.handler({
          cwd: args.cwd,
          deviceId: selectedDevice.id,
          target: args.target
        });
        steps.push({ step: 'run', ...runResult });
        
        return {
          success: true,
          data: {
            selectedDevice,
            sessionId: runResult.data?.sessionId,
            steps,
            message: `Flutter dev session started on ${selectedDevice.name}`
          }
        };
      } else {
        // No device available - try to start emulator
        const emulatorsResult = await flutterTools.get('flutter_list_emulators').handler({});
        
        if (emulatorsResult.success && emulatorsResult.data?.emulators?.length > 0) {
          const emulator = emulatorsResult.data.emulators[0];
          await flutterTools.get('flutter_launch_emulator').handler({ 
            emulatorId: emulator.id 
          });
          
          // Wait and retry
          await new Promise(resolve => setTimeout(resolve, 5000));
          return tools.get('flutter_dev_session').handler(args);
        }
        
        return {
          success: false,
          error: 'No devices available and no emulators to launch',
          steps
        };
      }
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : String(error),
        steps
      };
    }
  }
});

src/utils/tool-categories.ts:285-292 (helper)

Metadata entry in TOOL_REGISTRY providing categorization, platform info, requirements, and performance expectations for health checks and tool management.

'flutter_dev_session': {
  name: 'flutter_dev_session',
  category: ToolCategory.ESSENTIAL,
  platform: 'flutter',
  requiredTools: [RequiredTool.FLUTTER],
  description: 'Complete Flutter dev setup: check env, list devices, select best device, run with hot reload',
  safeForTesting: false,
  performance: { expectedDuration: 90000, timeout: 300000 }

MCP Mobile Server