MCP iOS Simulator Screenshot

Instructions

Implementation Reference

• src/services/screenshot-service.ts:32-77 (handler)

  Core handler function that executes the screenshot capture logic: validates device, captures using xcrun simctl, saves, resizes with sharp, and returns metadata.

  public async captureScreenshot(options: ScreenshotOptions = {}): Promise<ScreenshotResult> {
    try {
      // Prepare file paths
      const { outputPath } = this.prepareFilePaths(options);
      
      // Validate device ID (only if specified)
      if (options.deviceId && options.deviceId !== 'booted') {
        const isValid = await this.deviceValidator.isValidDeviceId(options.deviceId);
        if (!isValid) {
          throw new Error(`Invalid device ID: ${options.deviceId}. Please use a valid device ID or 'booted'.`);
        }
      }
  
      // Capture screenshot from simulator
      const imageBuffer = await this.captureSimulatorScreenshot(options.deviceId);
  
      // Save the image
      await fs.writeFile(outputPath, imageBuffer);
  
      // Process the image (resize if needed)
      const finalPath = options.resize !== false
        ? await this.resizeImage(outputPath, options.maxWidth || config.screenshot.defaultMaxWidth)
        : outputPath;
  
      // Get image metadata
      const metadata = await this.getImageMetadata(finalPath);
  
      // Get command line arguments
      const outputDir = this.outputManager.isUsingRootDirectoryDirectly() ?
        this.outputManager.getRootDirectory() : undefined;
  
      return {
        success: true,
        message: 'iOS Simulator screenshot saved successfully',
        filePath: finalPath,
        metadata,
        serverConfig: {
          commandLineArgs: {
            outputDir
          }
        }
      };
    } catch (error) {
      return this.createErrorResult(error);
    }
  }

• src/index.ts:192-218 (handler)

  MCP tool call handler that maps request parameters to ScreenshotOptions and delegates to ScreenshotService.captureScreenshot.

  private async handleScreenshotRequest(request: any): Promise<any> {
    try {
      const args = request.params.arguments as Record<string, unknown> || {};
      
      // Map API parameters to internal options
      const options: ScreenshotOptions = {
        outputFileName: args.output_filename as string,
        outputDirectoryName: args.output_directory_name as string,
        resize: args.resize as boolean,
        maxWidth: args.max_width as number,
        deviceId: args.device_id as string
      };
      
      // Capture screenshot
      const result = await this.screenshotService.captureScreenshot(options);
      
      // Return formatted response
      return this.createMcpResponse(result);
    } catch (error) {
      const err = error as Error;
      return this.createMcpResponse({
        success: false,
        message: `Error: ${err.message}`,
        error: { code: 'UNEXPECTED_ERROR' }
      });
    }
  }

• src/index.ts:153-187 (schema)

  Defines the tool schema including inputSchema with properties for filename, directory, resize options, and device ID.

  private getScreenshotToolDefinition() {
    return {
      name: 'get_screenshot',
      description: 'Capture a screenshot from iOS Simulator',
      inputSchema: {
        type: 'object',
        properties: {
          output_filename: {
            type: 'string',
            description: 'Output filename (if not specified, timestamp.png will be used)'
          },
          output_directory_name: {
            type: 'string',
            description: 'Subdirectory name for screenshots (if not specified, .screenshots will be used)',
            default: config.screenshot.defaultOutputDirName
          },
          resize: {
            type: 'boolean',
            description: 'Whether to resize the image to approximately VGA size',
            default: true
          },
          max_width: {
            type: 'integer',
            description: 'Maximum width for resizing (pixels)',
            default: config.screenshot.defaultMaxWidth
          },
          device_id: {
            type: 'string',
            description: 'Specify a simulator device (if not specified, the booted device will be used)'
          }
        },
        required: []
      }
    };
  }

• src/index.ts:133-135 (registration)

  Registers the get_screenshot tool by including it in the ListTools response.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [this.getScreenshotToolDefinition()]
  }));

• src/index.ts:139-141 (handler)

  Dispatch logic in CallToolRequestSchema handler that routes get_screenshot calls to the specific handler.

  if (request.params.name === 'get_screenshot') {
    return await this.handleScreenshotRequest(request);
  } else {