Supabase Storage MCP

Instructions

Implementation Reference

• src/index.ts:1040-1210 (handler)

  Core handler function implementing file download from Supabase storage with support for content formats (base64/binary/signed_url), image transformations, custom filenames, and optional JavaScript auto-download triggers.

  async function handleDownloadFileWithAutoTrigger(args: any, requestId: string, startTime: number) {
    const { 
      bucket_name, 
      file_path, 
      return_format = 'base64', 
      transform_options,
      auto_download = false,
      custom_filename
    } = args;
    
    const inputHash = generateSecureHash(JSON.stringify({ bucket_name, file_path, return_format, transform_options, auto_download }));
    
    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', 'signed_url'].includes(return_format)) {
        throw new Error('return_format must be "base64", "binary", or "signed_url"');
      }
      
      let result: AutoDownloadFileResult;
      
      if (return_format === 'signed_url') {
        // Generate signed URL with auto-download parameter
        const { data, error } = await supabase.storage
          .from(bucket_name)
          .createSignedUrl(file_path, 3600);
        
        if (error) {
          throw new Error(`Failed to create signed URL: ${error.message}`);
        }
        
        const fileName = custom_filename || file_path.split('/').pop() || 'download';
        
        // Add download parameter for automatic download
        const downloadUrl = auto_download ? 
          `${data.signedUrl}&download=${encodeURIComponent(fileName)}` :
          data.signedUrl;
        
        result = {
          success: true,
          file_path,
          file_name: fileName,
          download_url: downloadUrl,
          content_type: 'application/octet-stream', // Will be determined by browser
          format: return_format,
          auto_download_enabled: auto_download,
          expires_at: new Date(Date.now() + 3600 * 1000).toISOString(),
          transformed: false,
          javascript_trigger: auto_download ? `window.location.href = "${downloadUrl}";` : undefined,
          metadata: {
            last_modified: new Date().toISOString(),
            cache_control: 'no-cache'
          }
        };
      } else {
        // Download file content directly
        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;
            }
          }
        }
        
        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');
        }
        
        const fileName = custom_filename || file_path.split('/').pop() || 'unknown';
        const contentType = data.type || 'application/octet-stream';
        
        // Generate JavaScript auto-download code if requested
        let javascriptTrigger: string | undefined;
        if (auto_download) {
          javascriptTrigger = `
  // Auto-download code for ${fileName}
  const base64Content = "${content}";
  const byteCharacters = atob(base64Content);
  const byteNumbers = new Array(byteCharacters.length);
  for (let i = 0; i < byteCharacters.length; i++) {
    byteNumbers[i] = byteCharacters.charCodeAt(i);
  }
  const byteArray = new Uint8Array(byteNumbers);
  const blob = new Blob([byteArray], { type: "${contentType}" });
  const url = window.URL.createObjectURL(blob);
  const link = document.createElement('a');
  link.href = url;
  link.download = "${fileName}";
  document.body.appendChild(link);
  link.click();
  document.body.removeChild(link);
  window.URL.revokeObjectURL(url);
  console.log('Download triggered for ${fileName}');`;
        }
        
        result = {
          success: true,
          file_path,
          file_name: fileName,
          content,
          content_type: contentType,
          file_size: fileBuffer.length,
          format: return_format,
          auto_download_enabled: auto_download,
          transformed: !!(transform_options && Object.keys(transform_options).length > 0),
          transform_options: transform_options || undefined,
          javascript_trigger: javascriptTrigger,
          metadata: {
            last_modified: new Date().toISOString(),
            cache_control: 'no-cache'
          }
        };
      }
      
      auditRequest('download_file_with_auto_trigger', true, inputHash);
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              ...result,
              request_id: requestId,
              processing_time: Date.now() - startTime
            }, null, 2)
          }
        ]
      };
    } catch (error) {
      auditRequest('download_file_with_auto_trigger', false, inputHash, getErrorMessage(error));
      throw error;
    }
  }

• src/index.ts:333-391 (schema)

  JSON Schema defining the input parameters and validation rules for the tool, including required bucket_name and file_path, optional return_format, auto_download flag, and transform_options.

  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 or URL',
        enum: ['base64', 'binary', 'signed_url'],
        default: 'base64'
      },
      auto_download: {
        type: 'boolean',
        description: 'Generate auto-download trigger code',
        default: false
      },
      custom_filename: {
        type: 'string',
        description: 'Custom filename for download',
        maxLength: 255
      },
      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/index.ts:330-392 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and inputSchema.

  {
    name: 'download_file_with_auto_trigger',
    description: 'Download file with optional auto-download trigger and custom filename support',
    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 or URL',
          enum: ['base64', 'binary', 'signed_url'],
          default: 'base64'
        },
        auto_download: {
          type: 'boolean',
          description: 'Generate auto-download trigger code',
          default: false
        },
        custom_filename: {
          type: 'string',
          description: 'Custom filename for download',
          maxLength: 255
        },
        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:307-329 (schema)

  TypeScript interface defining the output structure of the tool response, used in the handler for typing the result object.

  export interface AutoDownloadFileResult {
    success: boolean;
    file_path?: string;
    file_name: string;
    download_url?: string;
    content?: string;
    content_type: string;
    file_size?: number;
    format: 'base64' | 'binary' | 'signed_url';
    auto_download_enabled: boolean;
    expires_at?: string;
    transformed: boolean;
    transform_options?: {
      width?: number;
      height?: number;
      quality?: number;
    };
    javascript_trigger?: string;
    metadata?: {
      last_modified: string;
      cache_control?: string;
    };
  }

• src/index.ts:488-489 (registration)

  Dispatch registration in the main CallToolRequestSchema switch statement, routing calls to the handler function.

  case 'download_file_with_auto_trigger':
    return await handleDownloadFileWithAutoTrigger(args, requestId, startTime);