# Supabase Storage MCP

A secure, production-ready Model Context Protocol (MCP) server for Supabase Storage with advanced security features, batch operations, and comprehensive file management.

## Features

### 🛡️ Enterprise-Grade Security
- **Multi-layer Defense**: Rate limiting, threat detection, and audit logging
- **Input Validation**: Comprehensive validation with Zod schemas and DOMPurify sanitization  
- **Real-time Monitoring**: Security metrics and alert system
- **Path Traversal Prevention**: Advanced protection against directory traversal attacks
- **File Type Validation**: MIME type verification and file signature checking

### 🗂️ Bucket Management
- **Secure Bucket Creation**: Create storage buckets with security validation
- **Organized Structure**: Automated folder organization for scalable workflows
- **Batch Setup**: Initialize multiple buckets with consistent configuration

### 🖼️ Advanced File Operations
- **Batch Upload**: Upload 1-500 files with progress tracking and detailed reporting
- **Dual Input Support**: Handle both local file paths and base64 data (Claude Desktop compatible)
- **File Validation**: Size limits, MIME type checking, and signature verification
- **Transform on Download**: Resize, compress, and format images during download
- **Auto-Download System**: Generate JavaScript code for browser downloads

### 📁 File Management
- **Secure Downloads**: Time-limited signed URLs with access controls
- **Batch Operations**: Process multiple files efficiently 
- **Advanced Search**: Filter by extension, folder, and metadata
- **Custom Filenames**: Override default names during download

### 🔗 Auto-Download Features
- **Intelligent Triggers**: Automatic browser downloads with custom filenames
- **Batch Downloads**: Sequential downloads with configurable delays
- **JavaScript Generation**: Ready-to-use browser scripts
- **Multiple Formats**: Support for signed URLs, base64, and binary data

## Installation

### Prerequisites
- Node.js >= 18.0.0
- npm >= 8.0.0
- Supabase project with Storage enabled

### Setup

1. **Clone and install dependencies:**
```bash
git clone https://github.com/your-username/supabase-storage-mcp.git
cd supabase-storage-mcp
npm install
```

2. **Configure environment variables:**
```bash
cp .env.example .env
```

Edit `.env` with your Supabase credentials:
```env
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key
NODE_ENV=production
```

3. **Build the project:**
```bash
npm run build
```

4. **Start the MCP server:**
```bash
npm start
```

## Configuration

### Claude Desktop Integration

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "supabase-storage": {
      "command": "node",
      "args": ["/path/to/supabase-storage-mcp/dist/index.js"],
      "description": "Supabase Storage MCP for file and bucket management"
    }
  }
}
```

### Environment Variables

| Variable | Required | Description | Default |
|----------|----------|-------------|---------|
| `SUPABASE_URL` | ✅ | Your Supabase project URL | - |
| `SUPABASE_SERVICE_KEY` | ✅ | Your Supabase service role key | - |
| `NODE_ENV` | ❌ | Environment mode | `development` |
| `LOG_LEVEL` | ❌ | Logging verbosity | `info` |

### Security Configuration

The server includes comprehensive security features enabled by default:
- Rate limiting (100 requests per minute globally)
- File size limits (50MB per file, 500 files per batch)
- MIME type restrictions (images only by default)
- Path traversal protection
- Input sanitization

## Usage

### Basic Bucket Operations

```javascript
// Create a storage bucket
await mcp.call('create_bucket', {
  bucket_name: 'my-images',
  is_public: false
});

// Setup standard bucket structure
await mcp.call('setup_buckets', {
  base_bucket_name: 'storage',
  user_id: 'user123'
});
```

### File Upload

```javascript
// Upload multiple images (file paths)
await mcp.call('upload_image_batch', {
  bucket_name: 'storage-images',
  batch_id: 'batch001',
  folder_prefix: 'original',
  user_id: 'user123',
  image_paths: ['/path/to/image1.jpg', '/path/to/image2.png']
});

// Upload with base64 data (Claude Desktop compatible)
await mcp.call('upload_image_batch', {
  bucket_name: 'storage-images',
  batch_id: 'batch002', 
  folder_prefix: 'original',
  user_id: 'user123',
  image_data: [
    {
      filename: 'image1.jpg',
      content: 'data:image/jpeg;base64,/9j/4AAQSkZJRg...',
      mime_type: 'image/jpeg'
    }
  ]
});
```

### File Management

```javascript
// List files in a bucket
await mcp.call('list_files', {
  bucket_name: 'storage-images',
  folder_path: 'original/user123',
  file_extension: '.jpg'
});

// Generate signed download URLs  
await mcp.call('get_file_url', {
  bucket_name: 'storage-images',
  storage_path: 'original/user123/batch001/image1.jpg',
  expires_in: 3600
});

// Batch signed URLs
await mcp.call('create_signed_urls', {
  bucket_name: 'storage-images',
  file_paths: ['path1.jpg', 'path2.png'],
  expires_in: 1800
});
```

### Advanced Downloads

```javascript
// Download with auto-trigger
await mcp.call('download_file_with_auto_trigger', {
  bucket_name: 'storage-images',
  file_path: 'original/user123/image1.jpg',
  return_format: 'base64',
  auto_download: true,
  custom_filename: 'my-image.jpg'
});

// Batch download with auto-trigger
await mcp.call('batch_download', {
  bucket_name: 'storage-images', 
  file_paths: ['image1.jpg', 'image2.png'],
  return_format: 'signed_url',
  auto_download: true,
  download_delay: 1000
});
```

### Image Transformations

```javascript
// Download with transformations
await mcp.call('download_file', {
  bucket_name: 'storage-images',
  file_path: 'original/image1.jpg',
  return_format: 'base64',
  transform_options: {
    width: 800,
    height: 600, 
    quality: 85
  }
});
```

### Security Monitoring

```javascript
// Get security status
await mcp.call('get_security_status', {});
```

## API Reference

### Tools

| Tool Name | Description |
|-----------|-------------|
| `create_bucket` | Create a new storage bucket |
| `setup_buckets` | Initialize standard bucket structure |
| `upload_image_batch` | Upload multiple files with validation |
| `list_files` | List files in bucket with filtering |
| `get_file_url` | Generate signed download URL |
| `create_signed_urls` | Generate multiple signed URLs |
| `download_file` | Download file content with transformations |
| `download_file_with_auto_trigger` | Download with auto-download JavaScript |
| `batch_download` | Download multiple files with auto-trigger |
| `get_security_status` | Get security metrics and status |

### File Organization

The server automatically organizes uploaded files in a structured format:

```
bucket-name/
├── original/
│   └── {user_id}/
│       └── {batch_id}/
│           ├── image1.jpg
│           └── image2.png
└── processed/
    └── {user_id}/
        └── {batch_id}/
            ├── thumb_image1.jpg  
            └── optimized_image2.png
```

## Security

### Built-in Protections
- **Rate Limiting**: Prevents API abuse
- **Input Validation**: Sanitizes all inputs  
- **File Validation**: MIME type and signature checking
- **Path Security**: Prevents directory traversal
- **Size Limits**: Configurable file and batch size limits
- **Audit Logging**: Complete operation tracking

### Security Best Practices
- Store your service role key securely
- Use environment variables for configuration
- Monitor security logs regularly
- Keep dependencies updated
- Use HTTPS in production

## Performance

### Batch Upload Performance
- **Small batches (1-25 files)**: ~15-30 seconds
- **Medium batches (26-100 files)**: ~45-90 seconds  
- **Large batches (101-500 files)**: ~3-8 minutes
- **Parallel uploads**: 3 concurrent streams
- **Memory efficient**: Streams large files

### Download Performance
- **File URL generation**: <50ms per URL
- **Direct downloads**: 100-500ms per file
- **Batch operations**: ~600 files per minute
- **Transform on download**: 200-800ms per image

## Development

### Build
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

### Security Audit
```bash
npm run security-check
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/your-username/supabase-storage-mcp/issues)
- **Documentation**: This README and inline code comments
- **Community**: [Discussions](https://github.com/your-username/supabase-storage-mcp/discussions)

---

Built with ❤️ for the MCP and Supabase communities.