download_file

Instructions

Implementation Reference

• src/index.ts:935-1037 (handler)

  The main handler function `handleDownloadFile` that executes the core logic: validates inputs, applies optional image transformations, downloads the file from Supabase Storage using `supabase.storage.download`, converts to base64 or binary, and returns structured result with auditing.

  async function handleDownloadFile(args: any, requestId: string, startTime: number) {
    const { bucket_name, file_path, return_format = 'base64', transform_options } = args;
    
    const inputHash = generateSecureHash(JSON.stringify({ bucket_name, file_path, return_format, transform_options }));
    
    try {
      // Input validation
      if (!bucket_name || typeof bucket_name !== 'string') {
        throw new Error('Invalid bucket_name parameter');
      }
      
      if (!file_path || typeof file_path !== 'string') {
        throw new Error('Invalid file_path parameter');
      }
      
      if (!['base64', 'binary'].includes(return_format)) {
        throw new Error('return_format must be either "base64" or "binary"');
      }
      
      // Prepare download options
      const downloadOptions: any = {};
      
      // Add transformation options if provided
      if (transform_options && typeof transform_options === 'object') {
        const { width, height, quality } = transform_options;
        
        if (width || height || quality) {
          downloadOptions.transform = {};
          if (width && typeof width === 'number' && width > 0) {
            downloadOptions.transform.width = width;
          }
          if (height && typeof height === 'number' && height > 0) {
            downloadOptions.transform.height = height;
          }
          if (quality && typeof quality === 'number' && quality > 0 && quality <= 100) {
            downloadOptions.transform.quality = quality;
          }
        }
      }
      
      // Download the file
      const { data, error } = await supabase.storage
        .from(bucket_name)
        .download(file_path, downloadOptions);
      
      if (error) {
        throw new Error(`Failed to download file: ${error.message}`);
      }
      
      if (!data) {
        throw new Error('No data received from download');
      }
      
      // Convert to buffer and then to requested format
      const buffer = await data.arrayBuffer();
      const fileBuffer = Buffer.from(buffer);
      
      let content: string;
      if (return_format === 'base64') {
        content = fileBuffer.toString('base64');
      } else {
        content = fileBuffer.toString('binary');
      }
      
      // Get file metadata
      const fileName = file_path.split('/').pop() || 'unknown';
      const contentType = data.type || 'application/octet-stream';
      
      auditRequest('download_file', true, inputHash);
      
      const result: DownloadFileResult = {
        success: true,
        file_path,
        file_name: fileName,
        content,
        content_type: contentType,
        file_size: fileBuffer.length,
        format: return_format,
        transformed: !!(transform_options && Object.keys(transform_options).length > 0),
        transform_options: transform_options || undefined,
        metadata: {
          last_modified: new Date().toISOString(),
          cache_control: 'no-cache'
        }
      };
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              ...result,
              request_id: requestId,
              processing_time: Date.now() - startTime
            }, null, 2)
          }
        ]
      };
    } catch (error) {
      auditRequest('download_file', false, inputHash, getErrorMessage(error));
      throw error;
    }
  }

• src/index.ts:278-328 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and detailed inputSchema with validation for bucket_name, file_path, return_format, and transform_options.

  name: 'download_file',
  description: 'Download file content directly with optional image transformations',
  inputSchema: {
    type: 'object',
    properties: {
      bucket_name: {
        type: 'string',
        description: 'Source bucket',
        minLength: 3,
        maxLength: 63
      },
      file_path: {
        type: 'string',
        description: 'Full file path in storage',
        maxLength: 1024
      },
      return_format: {
        type: 'string',
        description: 'Format to return file content',
        enum: ['base64', 'binary'],
        default: 'base64'
      },
      transform_options: {
        type: 'object',
        description: 'Optional image transformation settings',
        properties: {
          width: {
            type: 'number',
            description: 'Resize width in pixels',
            minimum: 1,
            maximum: 5000
          },
          height: {
            type: 'number',
            description: 'Resize height in pixels',
            minimum: 1,
            maximum: 5000
          },
          quality: {
            type: 'number',
            description: 'Image quality (1-100)',
            minimum: 1,
            maximum: 100
          }
        },
        additionalProperties: false
      }
    },
    required: ['bucket_name', 'file_path'],
    additionalProperties: false
  }

• src/modules/types.ts:286-305 (schema)

  Type definition for the output/result of the download_file tool, used in the handler to type the result object.

  export interface DownloadFileResult {
    success: boolean;
    file_path: string;
    file_name: string;
    content: string; // base64 or binary data
    content_type: string;
    file_size: number;
    format: 'base64' | 'binary';
    transformed: boolean;
    transform_options?: {
      width?: number;
      height?: number;
      quality?: number;
    };
    metadata?: {
      last_modified: string;
      etag?: string;
      cache_control?: string;
    };
  }