Supabase Storage MCP

Instructions

Implementation Reference

• src/index.ts:842-932 (handler)

  The primary handler function for the 'create_signed_urls' tool. It destructures arguments (bucket_name, file_paths, expires_in), performs input validation, iterates over each file_path to generate signed URLs via supabase.storage.createSignedUrl(), handles individual errors, tracks success/failure counts, audits the request, and returns a comprehensive batch result including per-file details and overall statistics.

  async function handleCreateSignedUrls(args: any, requestId: string, startTime: number) {
    const { bucket_name, file_paths, expires_in = 3600 } = args;
    
    const inputHash = generateSecureHash(JSON.stringify({ bucket_name, file_count: file_paths.length, expires_in }));
    
    try {
      // Input validation
      if (!bucket_name || typeof bucket_name !== 'string') {
        throw new Error('Invalid bucket_name parameter');
      }
      
      if (!Array.isArray(file_paths) || file_paths.length === 0) {
        throw new Error('file_paths must be a non-empty array');
      }
      
      if (file_paths.length > 100) {
        throw new Error('Cannot generate more than 100 URLs in a single request');
      }
      
      const results = [];
      let successCount = 0;
      let errorCount = 0;
      
      // Process each file path
      for (const filePath of file_paths) {
        try {
          const { data, error } = await supabase.storage
            .from(bucket_name)
            .createSignedUrl(filePath, expires_in);
          
          if (error) {
            results.push({
              file_path: filePath,
              signed_url: '',
              expires_at: '',
              success: false,
              error: error.message
            });
            errorCount++;
          } else {
            const expiresAt = new Date(Date.now() + expires_in * 1000).toISOString();
            results.push({
              file_path: filePath,
              signed_url: data.signedUrl,
              expires_at: expiresAt,
              success: true
            });
            successCount++;
          }
        } catch (error) {
          results.push({
            file_path: filePath,
            signed_url: '',
            expires_at: '',
            success: false,
            error: getErrorMessage(error)
          });
          errorCount++;
        }
      }
      
      const successRate = file_paths.length > 0 ? `${Math.round((successCount / file_paths.length) * 100)}%` : '0%';
      
      auditRequest('create_signed_urls', successCount > 0, inputHash);
      
      const result: SignedUrlBatchResult = {
        urls: results,
        total_files: file_paths.length,
        successful_urls: successCount,
        failed_urls: errorCount,
        success_rate: successRate,
        expires_in
      };
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              ...result,
              request_id: requestId,
              processing_time: Date.now() - startTime
            }, null, 2)
          }
        ]
      };
    } catch (error) {
      auditRequest('create_signed_urls', false, inputHash, getErrorMessage(error));
      throw error;
    }
  }

• src/index.ts:246-275 (schema)

  Input schema definition for the create_signed_urls tool, specifying required bucket_name and file_paths array (1-100 items), optional expires_in (60s-7d, default 3600s), with length constraints and no additional properties.

  inputSchema: {
    type: 'object',
    properties: {
      bucket_name: {
        type: 'string',
        description: 'Source bucket',
        minLength: 3,
        maxLength: 63
      },
      file_paths: {
        type: 'array',
        description: 'Array of file paths to generate URLs for',
        items: {
          type: 'string',
          maxLength: 1024
        },
        minItems: 1,
        maxItems: 100
      },
      expires_in: {
        type: 'number',
        description: 'URL expiration in seconds (default: 3600)',
        minimum: 60,
        maximum: 604800,
        default: 3600
      }
    },
    required: ['bucket_name', 'file_paths'],
    additionalProperties: false
  }

• src/index.ts:244-276 (registration)

  MCP tool registration block in the ListToolsRequestSchema handler, defining the tool's name, description, and inputSchema for discovery by MCP clients.

    name: 'create_signed_urls',
    description: 'Generate multiple signed download URLs in a single request for batch operations',
    inputSchema: {
      type: 'object',
      properties: {
        bucket_name: {
          type: 'string',
          description: 'Source bucket',
          minLength: 3,
          maxLength: 63
        },
        file_paths: {
          type: 'array',
          description: 'Array of file paths to generate URLs for',
          items: {
            type: 'string',
            maxLength: 1024
          },
          minItems: 1,
          maxItems: 100
        },
        expires_in: {
          type: 'number',
          description: 'URL expiration in seconds (default: 3600)',
          minimum: 60,
          maximum: 604800,
          default: 3600
        }
      },
      required: ['bucket_name', 'file_paths'],
      additionalProperties: false
    }
  },

• src/index.ts:482-483 (registration)

  Dispatch case in the main CallToolRequestSchema switch statement that routes 'create_signed_urls' requests to the handleCreateSignedUrls handler function.

  case 'create_signed_urls':
    return await handleCreateSignedUrls(args, requestId, startTime);