flutter_setup_environment
Install and configure Flutter SDK with automatic environment setup for mobile development. Choose installation actions, channels, and paths to prepare development systems.
Instructions
Complete Flutter SDK installation and environment setup with automatic path configuration
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | Action to perform (check status, install Flutter, configure paths, or full setup) | check |
| channel | No | Flutter channel to install | stable |
| installPath | No | Custom installation path (default: ~/development/flutter) | |
| autoConfig | No | Automatically configure shell environment |
Implementation Reference
- src/tools/setup-tools.ts:159-465 (handler)The main handler function implementing Flutter environment setup: performs platform-specific checks for Flutter/Android/Java, installs Flutter SDK (git clone preferred, fallback download), configures shell profiles (.zshrc/.bashrc) with PATH and env vars, provides recommendations.handler: async (args: any) => { const homeDir = os.homedir(); const platform = process.platform as 'darwin' | 'linux' | 'win32'; const results = { platform, checks: {} as any, installation: null as any, configuration: null as any, recommendations: [] as string[] }; // Determine default paths based on OS const platformPaths = { darwin: { flutter: path.join(homeDir, 'development', 'flutter'), androidSdk: path.join(homeDir, 'Library', 'Android', 'sdk'), shellConfig: path.join(homeDir, '.zshrc') }, linux: { flutter: path.join(homeDir, 'development', 'flutter'), androidSdk: path.join(homeDir, 'Android', 'Sdk'), shellConfig: path.join(homeDir, '.bashrc') }, win32: { flutter: 'C:\\src\\flutter', androidSdk: path.join(homeDir, 'AppData', 'Local', 'Android', 'Sdk'), shellConfig: null as string | null // Windows uses system environment variables } }; const defaultPaths = platformPaths[platform] || platformPaths.linux; const installPath = args.installPath || defaultPaths.flutter; // Action: CHECK - Check current environment status if (args.action === 'check' || args.action === 'full') { results.checks = { flutter: { installed: false, version: null, path: null, inPath: false }, android: { sdkInstalled: false, sdkPath: null, adbAvailable: false, platformTools: false, cmdlineTools: false, emulator: false, envVars: { ANDROID_HOME: process.env.ANDROID_HOME || null, ANDROID_SDK_ROOT: process.env.ANDROID_SDK_ROOT || null } }, java: { installed: false, version: null, path: null }, environment: { PATH: process.env.PATH?.includes('flutter'), shellConfig: null as string | null } }; // Check Flutter installation try { const { stdout: flutterPath } = await processExecutor.execute('which', ['flutter'], {}); if (flutterPath) { results.checks.flutter.installed = true; results.checks.flutter.path = flutterPath.trim(); results.checks.flutter.inPath = true; // Get Flutter version try { const { stdout: version } = await processExecutor.execute('flutter', ['--version'], {}); const versionMatch = version.match(/Flutter (\d+\.\d+\.\d+)/); if (versionMatch) { results.checks.flutter.version = versionMatch[1]; } } catch (e) { // Version check failed } } } catch (e) { // Flutter not in PATH, check common locations try { await fs.access(installPath); const flutterBin = path.join(installPath, 'bin', 'flutter'); await fs.access(flutterBin); results.checks.flutter.installed = true; results.checks.flutter.path = installPath; results.checks.flutter.inPath = false; results.recommendations.push('Flutter is installed but not in PATH. Run with action="configure" to fix.'); } catch (e) { results.recommendations.push('Flutter is not installed. Run with action="install" to install.'); } } // Check Android SDK const androidHome = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || defaultPaths.androidSdk; try { await fs.access(androidHome); results.checks.android.sdkInstalled = true; results.checks.android.sdkPath = androidHome; // Check specific Android tools const toolsToCheck = [ { name: 'adb', path: path.join(androidHome, 'platform-tools', 'adb'), key: 'adbAvailable' }, { name: 'platform-tools', path: path.join(androidHome, 'platform-tools'), key: 'platformTools' }, { name: 'cmdline-tools', path: path.join(androidHome, 'cmdline-tools'), key: 'cmdlineTools' }, { name: 'emulator', path: path.join(androidHome, 'emulator'), key: 'emulator' } ]; for (const tool of toolsToCheck) { try { await fs.access(tool.path); results.checks.android[tool.key] = true; } catch (e) { results.checks.android[tool.key] = false; results.recommendations.push(`Android ${tool.name} not found. Install Android SDK components.`); } } } catch (e) { results.recommendations.push('Android SDK not found. Install Android Studio or command-line tools.'); } // Check Java try { const { stdout: javaVersion } = await processExecutor.execute('java', ['-version'], {}); results.checks.java.installed = true; const versionMatch = javaVersion.match(/version "?(\d+)/); if (versionMatch) { results.checks.java.version = versionMatch[1]; } } catch (e) { results.recommendations.push('Java not found. Install JDK 11 or higher.'); } // Check shell configuration if (defaultPaths.shellConfig) { try { const shellContent = await fs.readFile(defaultPaths.shellConfig, 'utf-8'); results.checks.environment.shellConfig = defaultPaths.shellConfig; const hasFlutterPath = shellContent.includes('flutter/bin'); const hasAndroidHome = shellContent.includes('ANDROID_HOME'); if (!hasFlutterPath) { results.recommendations.push('Flutter not configured in shell. Run with action="configure".'); } if (!hasAndroidHome) { results.recommendations.push('Android SDK not configured in shell. Run with action="configure".'); } } catch (e) { results.recommendations.push('Shell configuration file not found.'); } } } // Action: INSTALL - Install Flutter SDK if (args.action === 'install' || args.action === 'full') { if (!results.checks?.flutter?.installed || args.action === 'install') { results.installation = { status: 'starting', path: installPath, channel: args.channel || 'stable' }; try { // Create installation directory await fs.mkdir(path.dirname(installPath), { recursive: true }); // Download Flutter based on platform const downloadUrls: Record<string, string> = { darwin: `https://storage.googleapis.com/flutter_infra_release/releases/${args.channel}/macos/flutter_macos_arm64-${args.channel}.zip`, linux: `https://storage.googleapis.com/flutter_infra_release/releases/${args.channel}/linux/flutter_linux_${args.channel}.tar.xz`, win32: `https://storage.googleapis.com/flutter_infra_release/releases/${args.channel}/windows/flutter_windows_${args.channel}.zip` }; const downloadUrl = downloadUrls[platform as string]; if (!downloadUrl) { throw new Error(`Unsupported platform: ${platform}`); } // Check if git is available for cloning try { await processExecutor.execute('git', ['--version'], {}); // Clone Flutter repository results.installation.method = 'git'; results.installation.status = 'cloning'; await processExecutor.execute('git', [ 'clone', 'https://github.com/flutter/flutter.git', '-b', args.channel || 'stable', installPath ], { timeout: 300000 }); // 5 minute timeout for clone results.installation.status = 'success'; results.installation.message = `Flutter installed successfully at ${installPath}`; } catch (gitError) { // Fallback to download method results.installation.method = 'download'; results.installation.status = 'downloading'; results.installation.error = 'Git not available, manual download required'; results.installation.downloadUrl = downloadUrl; results.recommendations.push(`Download Flutter manually from: ${downloadUrl}`); } } catch (error) { results.installation.status = 'failed'; results.installation.error = error instanceof Error ? error.message : String(error); } } } // Action: CONFIGURE - Configure environment variables if ((args.action === 'configure' || args.action === 'full') && args.autoConfig !== false) { results.configuration = { status: 'starting', shellConfig: defaultPaths.shellConfig, changes: [] as string[] }; if (platform === 'win32') { results.configuration.status = 'manual'; results.configuration.instructions = [ 'Add Flutter to Windows PATH:', `1. Add "${installPath}\\bin" to your PATH`, '2. Set ANDROID_HOME environment variable', '3. Restart your terminal' ]; } else if (defaultPaths.shellConfig) { try { const shellPath = defaultPaths.shellConfig; let shellContent = ''; try { shellContent = await fs.readFile(shellPath, 'utf-8'); } catch (e) { // File doesn't exist, create it shellContent = ''; } const additions = []; // Add Flutter configuration if not present if (!shellContent.includes('flutter/bin')) { const flutterPath = results.checks?.flutter?.path || installPath; additions.push(` # Flutter SDK Configuration export PATH="$PATH:${flutterPath}/bin" export PATH="$PATH:${flutterPath}/bin/cache/dart-sdk/bin" export PATH="$PATH:$HOME/.pub-cache/bin"`); results.configuration.changes.push('Added Flutter to PATH'); } // Add Android SDK configuration if not present if (!shellContent.includes('ANDROID_HOME') && results.checks?.android?.sdkPath) { additions.push(` # Android SDK Configuration export ANDROID_HOME="${results.checks.android.sdkPath}" export ANDROID_SDK_ROOT="${results.checks.android.sdkPath}" export PATH="$PATH:$ANDROID_HOME/platform-tools" export PATH="$PATH:$ANDROID_HOME/tools" export PATH="$PATH:$ANDROID_HOME/tools/bin" export PATH="$PATH:$ANDROID_HOME/emulator" export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin"`); results.configuration.changes.push('Added Android SDK configuration'); } // Add Chrome executable for web development (macOS) if (platform === 'darwin' && !shellContent.includes('CHROME_EXECUTABLE')) { additions.push(` # Chrome for Flutter Web Development export CHROME_EXECUTABLE="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"`); results.configuration.changes.push('Added Chrome executable for web development'); } if (additions.length > 0) { await fs.appendFile(shellPath, additions.join('\n') + '\n'); results.configuration.status = 'success'; results.configuration.message = `Updated ${shellPath}. Run 'source ${shellPath}' to apply changes.`; } else { results.configuration.status = 'unchanged'; results.configuration.message = 'Environment already configured correctly.'; } } catch (error) { results.configuration.status = 'failed'; results.configuration.error = error instanceof Error ? error.message : String(error); } } } // Final recommendations if (results.checks?.flutter?.installed && results.checks?.flutter?.inPath) { results.recommendations.push('Run "flutter doctor" to verify your setup.'); } return { success: true, data: results }; }
- src/tools/setup-tools.ts:133-157 (schema)Input schema defining parameters for the tool: action (check/install/configure/full), channel (stable/beta/dev/master), installPath, autoConfig.inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['check', 'install', 'configure', 'full'], description: 'Action to perform (check status, install Flutter, configure paths, or full setup)', default: 'check' }, channel: { type: 'string', enum: ['stable', 'beta', 'dev', 'master'], description: 'Flutter channel to install', default: 'stable' }, installPath: { type: 'string', description: 'Custom installation path (default: ~/development/flutter)', }, autoConfig: { type: 'boolean', description: 'Automatically configure shell environment', default: true } }
- src/tools/setup-tools.ts:130-466 (registration)Local registration of the tool into the setupTools Map within createSetupTools function.tools.set('flutter_setup_environment', { name: 'flutter_setup_environment', description: 'Complete Flutter SDK installation and environment setup with automatic path configuration', inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['check', 'install', 'configure', 'full'], description: 'Action to perform (check status, install Flutter, configure paths, or full setup)', default: 'check' }, channel: { type: 'string', enum: ['stable', 'beta', 'dev', 'master'], description: 'Flutter channel to install', default: 'stable' }, installPath: { type: 'string', description: 'Custom installation path (default: ~/development/flutter)', }, autoConfig: { type: 'boolean', description: 'Automatically configure shell environment', default: true } } }, handler: async (args: any) => { const homeDir = os.homedir(); const platform = process.platform as 'darwin' | 'linux' | 'win32'; const results = { platform, checks: {} as any, installation: null as any, configuration: null as any, recommendations: [] as string[] }; // Determine default paths based on OS const platformPaths = { darwin: { flutter: path.join(homeDir, 'development', 'flutter'), androidSdk: path.join(homeDir, 'Library', 'Android', 'sdk'), shellConfig: path.join(homeDir, '.zshrc') }, linux: { flutter: path.join(homeDir, 'development', 'flutter'), androidSdk: path.join(homeDir, 'Android', 'Sdk'), shellConfig: path.join(homeDir, '.bashrc') }, win32: { flutter: 'C:\\src\\flutter', androidSdk: path.join(homeDir, 'AppData', 'Local', 'Android', 'Sdk'), shellConfig: null as string | null // Windows uses system environment variables } }; const defaultPaths = platformPaths[platform] || platformPaths.linux; const installPath = args.installPath || defaultPaths.flutter; // Action: CHECK - Check current environment status if (args.action === 'check' || args.action === 'full') { results.checks = { flutter: { installed: false, version: null, path: null, inPath: false }, android: { sdkInstalled: false, sdkPath: null, adbAvailable: false, platformTools: false, cmdlineTools: false, emulator: false, envVars: { ANDROID_HOME: process.env.ANDROID_HOME || null, ANDROID_SDK_ROOT: process.env.ANDROID_SDK_ROOT || null } }, java: { installed: false, version: null, path: null }, environment: { PATH: process.env.PATH?.includes('flutter'), shellConfig: null as string | null } }; // Check Flutter installation try { const { stdout: flutterPath } = await processExecutor.execute('which', ['flutter'], {}); if (flutterPath) { results.checks.flutter.installed = true; results.checks.flutter.path = flutterPath.trim(); results.checks.flutter.inPath = true; // Get Flutter version try { const { stdout: version } = await processExecutor.execute('flutter', ['--version'], {}); const versionMatch = version.match(/Flutter (\d+\.\d+\.\d+)/); if (versionMatch) { results.checks.flutter.version = versionMatch[1]; } } catch (e) { // Version check failed } } } catch (e) { // Flutter not in PATH, check common locations try { await fs.access(installPath); const flutterBin = path.join(installPath, 'bin', 'flutter'); await fs.access(flutterBin); results.checks.flutter.installed = true; results.checks.flutter.path = installPath; results.checks.flutter.inPath = false; results.recommendations.push('Flutter is installed but not in PATH. Run with action="configure" to fix.'); } catch (e) { results.recommendations.push('Flutter is not installed. Run with action="install" to install.'); } } // Check Android SDK const androidHome = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || defaultPaths.androidSdk; try { await fs.access(androidHome); results.checks.android.sdkInstalled = true; results.checks.android.sdkPath = androidHome; // Check specific Android tools const toolsToCheck = [ { name: 'adb', path: path.join(androidHome, 'platform-tools', 'adb'), key: 'adbAvailable' }, { name: 'platform-tools', path: path.join(androidHome, 'platform-tools'), key: 'platformTools' }, { name: 'cmdline-tools', path: path.join(androidHome, 'cmdline-tools'), key: 'cmdlineTools' }, { name: 'emulator', path: path.join(androidHome, 'emulator'), key: 'emulator' } ]; for (const tool of toolsToCheck) { try { await fs.access(tool.path); results.checks.android[tool.key] = true; } catch (e) { results.checks.android[tool.key] = false; results.recommendations.push(`Android ${tool.name} not found. Install Android SDK components.`); } } } catch (e) { results.recommendations.push('Android SDK not found. Install Android Studio or command-line tools.'); } // Check Java try { const { stdout: javaVersion } = await processExecutor.execute('java', ['-version'], {}); results.checks.java.installed = true; const versionMatch = javaVersion.match(/version "?(\d+)/); if (versionMatch) { results.checks.java.version = versionMatch[1]; } } catch (e) { results.recommendations.push('Java not found. Install JDK 11 or higher.'); } // Check shell configuration if (defaultPaths.shellConfig) { try { const shellContent = await fs.readFile(defaultPaths.shellConfig, 'utf-8'); results.checks.environment.shellConfig = defaultPaths.shellConfig; const hasFlutterPath = shellContent.includes('flutter/bin'); const hasAndroidHome = shellContent.includes('ANDROID_HOME'); if (!hasFlutterPath) { results.recommendations.push('Flutter not configured in shell. Run with action="configure".'); } if (!hasAndroidHome) { results.recommendations.push('Android SDK not configured in shell. Run with action="configure".'); } } catch (e) { results.recommendations.push('Shell configuration file not found.'); } } } // Action: INSTALL - Install Flutter SDK if (args.action === 'install' || args.action === 'full') { if (!results.checks?.flutter?.installed || args.action === 'install') { results.installation = { status: 'starting', path: installPath, channel: args.channel || 'stable' }; try { // Create installation directory await fs.mkdir(path.dirname(installPath), { recursive: true }); // Download Flutter based on platform const downloadUrls: Record<string, string> = { darwin: `https://storage.googleapis.com/flutter_infra_release/releases/${args.channel}/macos/flutter_macos_arm64-${args.channel}.zip`, linux: `https://storage.googleapis.com/flutter_infra_release/releases/${args.channel}/linux/flutter_linux_${args.channel}.tar.xz`, win32: `https://storage.googleapis.com/flutter_infra_release/releases/${args.channel}/windows/flutter_windows_${args.channel}.zip` }; const downloadUrl = downloadUrls[platform as string]; if (!downloadUrl) { throw new Error(`Unsupported platform: ${platform}`); } // Check if git is available for cloning try { await processExecutor.execute('git', ['--version'], {}); // Clone Flutter repository results.installation.method = 'git'; results.installation.status = 'cloning'; await processExecutor.execute('git', [ 'clone', 'https://github.com/flutter/flutter.git', '-b', args.channel || 'stable', installPath ], { timeout: 300000 }); // 5 minute timeout for clone results.installation.status = 'success'; results.installation.message = `Flutter installed successfully at ${installPath}`; } catch (gitError) { // Fallback to download method results.installation.method = 'download'; results.installation.status = 'downloading'; results.installation.error = 'Git not available, manual download required'; results.installation.downloadUrl = downloadUrl; results.recommendations.push(`Download Flutter manually from: ${downloadUrl}`); } } catch (error) { results.installation.status = 'failed'; results.installation.error = error instanceof Error ? error.message : String(error); } } } // Action: CONFIGURE - Configure environment variables if ((args.action === 'configure' || args.action === 'full') && args.autoConfig !== false) { results.configuration = { status: 'starting', shellConfig: defaultPaths.shellConfig, changes: [] as string[] }; if (platform === 'win32') { results.configuration.status = 'manual'; results.configuration.instructions = [ 'Add Flutter to Windows PATH:', `1. Add "${installPath}\\bin" to your PATH`, '2. Set ANDROID_HOME environment variable', '3. Restart your terminal' ]; } else if (defaultPaths.shellConfig) { try { const shellPath = defaultPaths.shellConfig; let shellContent = ''; try { shellContent = await fs.readFile(shellPath, 'utf-8'); } catch (e) { // File doesn't exist, create it shellContent = ''; } const additions = []; // Add Flutter configuration if not present if (!shellContent.includes('flutter/bin')) { const flutterPath = results.checks?.flutter?.path || installPath; additions.push(` # Flutter SDK Configuration export PATH="$PATH:${flutterPath}/bin" export PATH="$PATH:${flutterPath}/bin/cache/dart-sdk/bin" export PATH="$PATH:$HOME/.pub-cache/bin"`); results.configuration.changes.push('Added Flutter to PATH'); } // Add Android SDK configuration if not present if (!shellContent.includes('ANDROID_HOME') && results.checks?.android?.sdkPath) { additions.push(` # Android SDK Configuration export ANDROID_HOME="${results.checks.android.sdkPath}" export ANDROID_SDK_ROOT="${results.checks.android.sdkPath}" export PATH="$PATH:$ANDROID_HOME/platform-tools" export PATH="$PATH:$ANDROID_HOME/tools" export PATH="$PATH:$ANDROID_HOME/tools/bin" export PATH="$PATH:$ANDROID_HOME/emulator" export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin"`); results.configuration.changes.push('Added Android SDK configuration'); } // Add Chrome executable for web development (macOS) if (platform === 'darwin' && !shellContent.includes('CHROME_EXECUTABLE')) { additions.push(` # Chrome for Flutter Web Development export CHROME_EXECUTABLE="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"`); results.configuration.changes.push('Added Chrome executable for web development'); } if (additions.length > 0) { await fs.appendFile(shellPath, additions.join('\n') + '\n'); results.configuration.status = 'success'; results.configuration.message = `Updated ${shellPath}. Run 'source ${shellPath}' to apply changes.`; } else { results.configuration.status = 'unchanged'; results.configuration.message = 'Environment already configured correctly.'; } } catch (error) { results.configuration.status = 'failed'; results.configuration.error = error instanceof Error ? error.message : String(error); } } } // Final recommendations if (results.checks?.flutter?.installed && results.checks?.flutter?.inPath) { results.recommendations.push('Run "flutter doctor" to verify your setup.'); } return { success: true, data: results }; } });
- src/server.ts:49-71 (registration)Top-level registration: createSetupTools is called and its tools (including flutter_setup_environment) are merged into the main tools Map if present in TOOL_REGISTRY.const setupTools = createSetupTools(globalProcessMap); // Combine all tool sources const allAvailableTools = new Map<string, any>([ ...androidTools.entries(), ...iosTools.entries(), ...flutterTools.entries(), ...superTools.entries(), ...setupTools.entries() ]); // Only register tools that are in TOOL_REGISTRY for (const toolName of Object.keys(TOOL_REGISTRY)) { if (allAvailableTools.has(toolName)) { tools.set(toolName, allAvailableTools.get(toolName)); } else if (toolName === 'health_check') { // health_check is handled separately below continue; } else { // Tool is in registry but not implemented - log warning console.warn(`Warning: Tool '${toolName}' is in TOOL_REGISTRY but not implemented`); } }
- src/utils/tool-categories.ts:386-394 (helper)Metadata registration in TOOL_REGISTRY, defining category, platform, requirements, performance expectations.'flutter_setup_environment': { name: 'flutter_setup_environment', category: ToolCategory.ESSENTIAL, platform: 'cross-platform', requiredTools: [], description: 'Complete Flutter SDK installation and environment setup with automatic path configuration', safeForTesting: true, performance: { expectedDuration: 5000, timeout: 600000 } },