list_files

Instructions

Implementation Reference

• src/index.ts:702-759 (handler)

  The handleListFiles function that executes the tool logic: lists files from a Supabase storage bucket optionally filtered by folder and extension, computes summary stats, performs audit logging, and returns structured response.

  async function handleListFiles(args: any, requestId: string, startTime: number) {
    const { bucket_name, folder_path, file_extension } = args;
    
    const inputHash = generateSecureHash(JSON.stringify({ bucket_name, folder_path, file_extension }));
    
    try {
      const { data, error } = await supabase.storage
        .from(bucket_name)
        .list(folder_path || '', {
          limit: 1000,
          sortBy: { column: 'name', order: 'asc' }
        });
      
      if (error) {
        throw new Error(`Failed to list files: ${error.message}`);
      }
      
      let files = data || [];
      
      // Filter by file extension if specified
      if (file_extension) {
        files = files.filter(file => file.name.toLowerCase().endsWith(file_extension.toLowerCase()));
      }
      
      const totalSize = files.reduce((sum, file) => sum + (file.metadata?.size || 0), 0);
      
      auditRequest('list_files', true, inputHash);
      
      const result: FileListResult = {
        files: files.map(file => ({
          name: file.name,
          path: folder_path ? `${folder_path}/${file.name}` : file.name,
          size: file.metadata?.size || 0,
          mime_type: file.metadata?.mimetype || 'unknown',
          last_modified: file.updated_at || file.created_at || new Date().toISOString(),
          metadata: file.metadata
        })),
        total_count: files.length,
        total_size: totalSize
      };
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              ...result,
              request_id: requestId,
              processing_time: Date.now() - startTime
            }, null, 2)
          }
        ]
      };
    } catch (error) {
      auditRequest('list_files', false, inputHash, getErrorMessage(error));
      throw error;
    }
  }

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

  Registration of the 'list_files' tool in the ListToolsRequestSchema handler, including name, description, and input schema.

  {
    name: 'list_files',
    description: 'Enumerate files in bucket folder for processing or download',
    inputSchema: {
      type: 'object',
      properties: {
        bucket_name: {
          type: 'string',
          description: 'Bucket to search',
          minLength: 3,
          maxLength: 63
        },
        folder_path: {
          type: 'string',
          description: 'Specific folder path',
          maxLength: 300
        },
        file_extension: {
          type: 'string',
          description: 'Filter by extension (.jpg, .png)',
          maxLength: 10
        }
      },
      required: ['bucket_name'],
      additionalProperties: false
    }
  },

• src/index.ts:473-474 (registration)

  Dispatch/registration case in the main CallToolRequestSchema switch statement that routes to the handleListFiles handler.

  case 'list_files':
    return await handleListFiles(args, requestId, startTime);

• src/index.ts:181-202 (schema)

  Input schema definition for the list_files tool validating bucket_name (required), optional folder_path and file_extension.

  inputSchema: {
    type: 'object',
    properties: {
      bucket_name: {
        type: 'string',
        description: 'Bucket to search',
        minLength: 3,
        maxLength: 63
      },
      folder_path: {
        type: 'string',
        description: 'Specific folder path',
        maxLength: 300
      },
      file_extension: {
        type: 'string',
        description: 'Filter by extension (.jpg, .png)',
        maxLength: 10
      }
    },
    required: ['bucket_name'],
    additionalProperties: false