take_screenshot

Instructions

Implementation Reference

• src/features/screenshot.ts:97-123 (handler)

  Main handler function that validates params, builds the screencapture command, and executes it. Imports ScreenshotParams, NotificationError, execAsync, and escapeString. Throws specific error types on failure.

  export async function takeScreenshot(params: ScreenshotParams): Promise<void> {
    try {
      validateScreenshotParams(params);
      const command = buildScreenshotCommand(params);
      await execAsync(command);
    } catch (error) {
      if (error instanceof NotificationError) {
        throw error;
      }
  
      const err = error as Error;
      if (err.message.includes('execution error')) {
        throw new NotificationError(
          NotificationErrorType.COMMAND_FAILED,
          'Failed to capture screenshot'
        );
      } else if (err.message.includes('permission')) {
        throw new NotificationError(
          NotificationErrorType.PERMISSION_DENIED,
          'Permission denied when trying to capture screenshot'
        );
      } else {
        throw new NotificationError(
          NotificationErrorType.UNKNOWN,
          `Unexpected error: ${err.message}`
        );
      }

• src/types.ts:65-78 (schema)

  TypeScript interface defining ScreenshotParams: path (required), type (fullscreen|window|selection, required), format (png|jpg|pdf|tiff), hideCursor, shadow, timestamp.

  export interface ScreenshotParams {
    /** Path where to save the screenshot */
    path: string;
    /** Type of screenshot to take */
    type: 'fullscreen' | 'window' | 'selection';
    /** Image format (png, jpg, pdf, tiff) */
    format?: 'png' | 'jpg' | 'pdf' | 'tiff';
    /** Whether to hide the cursor */
    hideCursor?: boolean;
    /** Whether to include the window shadow (only for window type) */
    shadow?: boolean;
    /** Timestamp to add to filename (defaults to current time) */
    timestamp?: boolean;
  }

• src/index.ts:144-178 (registration)

  Tool registration in ListToolsRequestSchema handler: name 'take_screenshot', description, and inputSchema with path, type, format, hideCursor, shadow, timestamp fields.

  name: 'take_screenshot',
  description: 'Take a screenshot using macOS screencapture',
  inputSchema: {
    type: 'object',
    properties: {
      path: {
        type: 'string',
        description: 'Path where to save the screenshot',
      },
      type: {
        type: 'string',
        enum: ['fullscreen', 'window', 'selection'],
        description: 'Type of screenshot to take',
      },
      format: {
        type: 'string',
        enum: ['png', 'jpg', 'pdf', 'tiff'],
        description: 'Image format',
      },
      hideCursor: {
        type: 'boolean',
        description: 'Whether to hide the cursor',
      },
      shadow: {
        type: 'boolean',
        description: 'Whether to include the window shadow (only for window type)',
      },
      timestamp: {
        type: 'boolean',
        description: 'Timestamp to add to filename',
      }
    },
    required: ['path', 'type'],
    additionalProperties: false,
  },

• src/index.ts:289-310 (handler)

  Case handler in CallToolRequestSchema switch statement: extracts params from request, constructs ScreenshotParams, calls takeScreenshot() from screenshot.ts, returns success message.

  case 'take_screenshot': {
    const { path, type, format, hideCursor, shadow, timestamp } = request.params.arguments as Record<string, unknown>;
    
    const params: ScreenshotParams = {
      path: path as string,
      type: type as 'fullscreen' | 'window' | 'selection',
      format: format as 'png' | 'jpg' | 'pdf' | 'tiff' | undefined,
      hideCursor: typeof hideCursor === 'boolean' ? hideCursor : undefined,
      shadow: typeof shadow === 'boolean' ? shadow : undefined,
      timestamp: typeof timestamp === 'boolean' ? timestamp : undefined
    };
  
    await takeScreenshot(params);
    return {
      content: [
        {
          type: 'text',
          text: 'Screenshot saved successfully',
        },
      ],
    };
  }

• src/features/screenshot.ts:54-92 (helper)

  Helper function buildScreenshotCommand that builds the macOS screencapture CLI command with flags for type (-w, -s), format (-t), hide cursor (-C), shadow (-o), and optional timestamp in filename.

  function buildScreenshotCommand(params: ScreenshotParams): string {
    let command = 'screencapture';
    
    // Screenshot type
    switch (params.type) {
      case 'window':
        command += ' -w'; // Capture window
        break;
      case 'selection':
        command += ' -s'; // Interactive selection
        break;
      // fullscreen is default, no flag needed
    }
    
    // Optional flags
    if (params.format) {
      command += ` -t ${params.format}`;
    }
    
    if (params.hideCursor) {
      command += ' -C'; // Hide cursor
    }
    
    if (params.type === 'window' && params.shadow === false) {
      command += ' -o'; // No window shadow
    }
    
    // Add timestamp to filename if requested
    let path = params.path;
    if (params.timestamp) {
      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
      const ext = params.format || 'png';
      path = path.replace(new RegExp(`\\.${ext}$`), `-${timestamp}.${ext}`);
    }
    
    command += ` "${escapeString(path)}"`;
    
    return command;
  }