MCP Mobile Server

Instructions

Implementation Reference

• src/tools/super-tools.ts:394-495 (handler)

  The core handler function implementing mobile_device_manager. It supports actions 'list', 'recommend', and 'ensure' for managing devices and emulators using composed Flutter tools.

  handler: async (args: any) => {
    const devices = [];
    const emulators = [];
    
    // Get all available devices
    const flutterDevices = await flutterTools.get('flutter_list_devices').handler({});
    if (flutterDevices.success) {
      devices.push(...(flutterDevices.data?.devices || []));
    }
    
    // Get available emulators
    const flutterEmulators = await flutterTools.get('flutter_list_emulators').handler({});
    if (flutterEmulators.success) {
      emulators.push(...(flutterEmulators.data?.emulators || []));
    }
    
    if (args.action === 'list') {
      return {
        success: true,
        data: { devices, emulators }
      };
    }
    
    if (args.action === 'recommend') {
      // Recommendation logic
      const recommendations = [];
      
      // Physical devices are usually preferred
      const physicalDevices = devices.filter((d: any) => !d.emulator);
      if (physicalDevices.length > 0) {
        recommendations.push({
          device: physicalDevices[0],
          reason: 'Physical device - best performance and real-world testing'
        });
      }
      
      // Running emulators
      const runningEmulators = devices.filter((d: any) => d.emulator);
      if (runningEmulators.length > 0) {
        recommendations.push({
          device: runningEmulators[0],
          reason: 'Emulator already running - ready to use'
        });
      }
      
      // Available emulators to start
      if (emulators.length > 0) {
        recommendations.push({
          emulator: emulators[0],
          reason: 'Emulator available - can be started on demand'
        });
      }
      
      return {
        success: true,
        data: {
          recommendations,
          bestOption: recommendations[0]
        }
      };
    }
    
    if (args.action === 'ensure') {
      // Ensure at least one device is available
      if (devices.length > 0) {
        return {
          success: true,
          data: {
            device: devices[0],
            message: 'Device already available'
          }
        };
      }
      
      // Try to start an emulator
      if (emulators.length > 0) {
        const launchResult = await flutterTools.get('flutter_launch_emulator').handler({
          emulatorId: emulators[0].id
        });
        
        return {
          success: launchResult.success,
          data: {
            emulator: emulators[0],
            launchResult,
            message: 'Started emulator'
          }
        };
      }
      
      return {
        success: false,
        error: 'No devices or emulators available'
      };
    }
  
    // Default return for unknown action
    return {
      success: false,
      error: `Unknown action: ${args.action}`
    };
  }

• src/tools/super-tools.ts:377-393 (schema)

  Input schema defining parameters for the mobile_device_manager tool: action (list/recommend/ensure) and platform filter.

  inputSchema: {
    type: 'object',
    properties: {
      action: {
        type: 'string',
        enum: ['list', 'recommend', 'ensure'],
        description: 'Action to perform',
        default: 'recommend'
      },
      platform: {
        type: 'string',
        enum: ['android', 'ios', 'any'],
        description: 'Target platform',
        default: 'any'
      }
    }
  },

• src/tools/super-tools.ts:374-496 (registration)

  Local registration of the mobile_device_manager tool within the createSuperTools function's tools Map.

  tools.set('mobile_device_manager', {
    name: 'mobile_device_manager',
    description: 'Smart device management: list all, recommend best, auto-start if needed',
    inputSchema: {
      type: 'object',
      properties: {
        action: {
          type: 'string',
          enum: ['list', 'recommend', 'ensure'],
          description: 'Action to perform',
          default: 'recommend'
        },
        platform: {
          type: 'string',
          enum: ['android', 'ios', 'any'],
          description: 'Target platform',
          default: 'any'
        }
      }
    },
    handler: async (args: any) => {
      const devices = [];
      const emulators = [];
      
      // Get all available devices
      const flutterDevices = await flutterTools.get('flutter_list_devices').handler({});
      if (flutterDevices.success) {
        devices.push(...(flutterDevices.data?.devices || []));
      }
      
      // Get available emulators
      const flutterEmulators = await flutterTools.get('flutter_list_emulators').handler({});
      if (flutterEmulators.success) {
        emulators.push(...(flutterEmulators.data?.emulators || []));
      }
      
      if (args.action === 'list') {
        return {
          success: true,
          data: { devices, emulators }
        };
      }
      
      if (args.action === 'recommend') {
        // Recommendation logic
        const recommendations = [];
        
        // Physical devices are usually preferred
        const physicalDevices = devices.filter((d: any) => !d.emulator);
        if (physicalDevices.length > 0) {
          recommendations.push({
            device: physicalDevices[0],
            reason: 'Physical device - best performance and real-world testing'
          });
        }
        
        // Running emulators
        const runningEmulators = devices.filter((d: any) => d.emulator);
        if (runningEmulators.length > 0) {
          recommendations.push({
            device: runningEmulators[0],
            reason: 'Emulator already running - ready to use'
          });
        }
        
        // Available emulators to start
        if (emulators.length > 0) {
          recommendations.push({
            emulator: emulators[0],
            reason: 'Emulator available - can be started on demand'
          });
        }
        
        return {
          success: true,
          data: {
            recommendations,
            bestOption: recommendations[0]
          }
        };
      }
      
      if (args.action === 'ensure') {
        // Ensure at least one device is available
        if (devices.length > 0) {
          return {
            success: true,
            data: {
              device: devices[0],
              message: 'Device already available'
            }
          };
        }
        
        // Try to start an emulator
        if (emulators.length > 0) {
          const launchResult = await flutterTools.get('flutter_launch_emulator').handler({
            emulatorId: emulators[0].id
          });
          
          return {
            success: launchResult.success,
            data: {
              emulator: emulators[0],
              launchResult,
              message: 'Started emulator'
            }
          };
        }
        
        return {
          success: false,
          error: 'No devices or emulators available'
        };
      }
  
      // Default return for unknown action
      return {
        success: false,
        error: `Unknown action: ${args.action}`
      };
    }
  });

• src/server.ts:61-71 (registration)

  Top-level registration loop in the MCP server that adds mobile_device_manager (from superTools) to the server's main tools Map if present 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:315-322 (helper)

  Metadata entry in TOOL_REGISTRY for mobile_device_manager, used for health checks and tool discovery.

  'mobile_device_manager': {
    name: 'mobile_device_manager',
    category: ToolCategory.ESSENTIAL,
    platform: 'cross-platform',
    requiredTools: [RequiredTool.FLUTTER],
    description: 'Smart device management: list all, recommend best, auto-start if needed',
    safeForTesting: false,
    performance: { expectedDuration: 30000, timeout: 180000 }