# SeedDream 4.0 FAL MCP Server

A Model Context Protocol (MCP) server that provides image generation capabilities using Bytedance's SeedDream 4.0 model via the FAL AI platform.

## Features

SeedDream 4.0 is a new-generation image creation model that integrates image generation and image editing capabilities into a single, unified architecture:

- **Advanced Text-to-Image Generation** with improved quality and detail
- **Flexible Image Sizing** from 1024x1024 to 4096x4096 pixels
- **Multi-Image Generation** with configurable batch sizes
- **Enhanced Safety Checking** to filter inappropriate content
- **Unified Architecture** combining generation and editing capabilities
- **High-Quality Output** with superior detail and coherence
- **Fast Generation** with optimized processing

## Available Tools

### `generate_image`
Generate single or multiple images from a text prompt using SeedDream 4.0.

**Parameters:**
- `prompt` (required): Text description of the image to generate
- `image_size` (optional): Image dimensions - can be:
  - **Presets**: `square_1024`, `square_1280`, `square_1536`, `portrait_1024`, `portrait_1280`, `landscape_1024`, `landscape_1280`, `wide_1024`, `tall_1024`
  - **Custom**: `{width: number, height: number}` (1024-4096px range)
  - Default: `square_1280` (1280x1280)
- `num_images` (optional): Number of separate generations (1-6, default: 1)
- `max_images` (optional): Maximum images per generation (1-6, default: 1)
- `seed` (optional): Random seed for reproducible results
- `sync_mode` (optional): Wait for upload before response (default: false)
- `enable_safety_checker` (optional): Enable content filtering (default: true)

### `generate_image_batch`
Generate multiple images with different prompts in a single request.

**Parameters:**
- `prompts` (required): Array of text prompts (1-5 prompts)
- `image_size` (optional): Size for all images (preset or custom, default: `square_1280`)
- `enable_safety_checker` (optional): Enable safety checking (default: true)

## Installation

### Prerequisites

1. **FAL AI API Key**: Get your API key from [FAL AI](https://fal.ai/)
   - Sign up for an account at https://fal.ai/
   - Navigate to your dashboard and generate an API key
   - Keep this key secure as you'll need it for configuration

2. **Node.js**: Ensure you have Node.js installed (version 16 or higher)

### Quick Setup (Recommended)

The easiest way to use this server is through npx, which automatically downloads and runs the latest version:

#### For Claude Desktop App

Add the server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "seedream4": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-fal-mcp-server.git"
      ],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}
```

#### For Kilo Code MCP Settings

Add to your MCP settings file at:
`C:\Users\[username]\AppData\Roaming\Code\User\globalStorage\kilocode.kilo-code\settings\mcp_settings.json`

```json
{
  "mcpServers": {
    "seedream4": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-fal-mcp-server.git"
      ],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}
```

### Benefits of npx Configuration

✅ **Universal Access**: Works on any machine with Node.js
✅ **No Local Installation**: npx downloads and runs automatically
✅ **Always Latest Version**: Pulls from GitHub repository
✅ **Cross-Platform**: Windows, macOS, Linux compatible
✅ **Settings Sync**: Works everywhere you use your MCP client

### Manual Installation (Alternative)

If you prefer to install locally:

1. **Clone the repository**
   ```bash
   git clone https://github.com/PierrunoYT/seedream-v4-fal-mcp-server.git
   cd seedream-v4-fal-mcp-server
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Build the server**
   ```bash
   npm run build
   ```

4. **Use absolute path in configuration**
   ```json
   {
     "mcpServers": {
       "seedream4": {
         "command": "node",
         "args": ["/absolute/path/to/seedream-v4-fal-mcp-server/build/index.js"],
         "env": {
           "FAL_KEY": "your-fal-api-key-here"
         }
       }
     }
   }
   ```

**Helper script to get the absolute path:**
```bash
npm run get-path
```

## Usage Examples

Once configured, you can use the server through your MCP client:

### Basic Image Generation
```
Generate an image of a futuristic cityscape at sunset with flying cars
```

### Custom Image Size
```
Create a wide landscape image (1600x1280) of a serene mountain lake
```

### Multiple Images
```
Generate 3 variations of a cute robot character (num_images: 3)
```

### High-Resolution Generation
```
Create a detailed portrait in 1536x1536 resolution of a wise old wizard
```

### Batch Generation
```
Generate images for these prompts: "a red rose in morning dew", "a blue ocean wave", "a green forest path"
```

### With Custom Parameters
```
Generate a square image (1280x1280) of a magical forest with safety checker enabled and seed 12345
```

### Sync Mode for Immediate Access
```
Create an image of a space station with sync_mode enabled for immediate download
```

## Image Size Presets

SeedDream 4.0 supports the following preset sizes:

- **Square Formats**:
  - `square_1024`: 1024x1024
  - `square_1280`: 1280x1280 (default)
  - `square_1536`: 1536x1536

- **Portrait Formats**:
  - `portrait_1024`: 1024x1280
  - `portrait_1280`: 1280x1600

- **Landscape Formats**:
  - `landscape_1024`: 1280x1024
  - `landscape_1280`: 1600x1280

- **Special Formats**:
  - `wide_1024`: 1536x1024
  - `tall_1024`: 1024x1536

You can also specify custom dimensions with `{width: number, height: number}` where both values are between 1024 and 4096 pixels.

## API Response Format

The server returns detailed information about generated images:

```
Successfully generated 1 image(s) using SeedDream 4.0:

Prompt: "a futuristic cityscape at sunset"
Image Size: 1280x1280
Number of Images: 1
Max Images per Generation: 1
Safety Checker: Enabled
Seed Used: 1234567890

Generated Images:
Image 1 (1280x1280):
  Local Path: ./images/seedream4_futuristic_cityscape_1234567890_1_2024-01-01T12-00-00-000Z.png
  Original URL: https://storage.googleapis.com/falserverless/...
```

## Development

### Local Testing
```bash
# Test the server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js
```

### Watch Mode
```bash
npm run watch
```

### Inspector Tool
```bash
npm run inspector
```

## Troubleshooting

### Common Issues

1. **"FAL_KEY environment variable is not set"**
   - The server will continue running and show this helpful error message
   - Ensure your FAL API key is properly set in the MCP configuration
   - Verify the key is valid and has sufficient credits
   - **Note**: The server no longer crashes when the API key is missing

2. **"Server not showing up in Claude"**
   - If using npx configuration, ensure you have Node.js installed
   - For manual installation, check that the absolute path is correct
   - Restart Claude Desktop after configuration changes
   - Verify the JSON configuration syntax is valid

3. **"Generation failed"**
   - Check your FAL AI account has sufficient credits
   - Verify your API key has the necessary permissions
   - Try with a simpler prompt to test connectivity
   - Ensure image dimensions are within the 1024-4096 range

4. **"Invalid image size"**
   - Use valid presets or ensure custom dimensions are between 1024-4096
   - Check that width and height are both specified for custom sizes

5. **"npx command not found"**
   - Ensure Node.js is properly installed
   - Try running `node --version` and `npm --version` to verify installation

### Server Stability Improvements

✅ **Robust Error Handling**: Server continues running even without API token
✅ **Graceful Shutdown**: Proper handling of SIGINT and SIGTERM signals
✅ **User-Friendly Messages**: Clear error messages with setup instructions
✅ **No More Crashes**: Eliminated `process.exit()` calls that caused connection drops
✅ **Enhanced Validation**: Comprehensive input validation for all parameters

### Debug Logging

The server outputs debug information to stderr, which can help diagnose issues:
- Generation progress updates
- Error messages with helpful instructions
- API call details
- Image download status
- Graceful shutdown notifications

## What's New in SeedDream 4.0

### Improvements over SeedDream 3.0

- **Unified Architecture**: Combines generation and editing in one model
- **Enhanced Quality**: Improved image detail and coherence
- **Flexible Sizing**: Support for custom dimensions up to 4096px
- **Multi-Image Generation**: Better control over batch generation
- **Advanced Safety**: Enhanced content filtering capabilities
- **Better Performance**: Optimized generation pipeline

### Migration from SeedDream 3.0

If you're upgrading from SeedDream 3.0:

1. **API Endpoint**: Now uses `fal-ai/bytedance/seedream/v4/text-to-image`
2. **Aspect Ratios**: Replaced with flexible `image_size` parameter
3. **New Parameters**: Added `max_images`, `sync_mode`, `enable_safety_checker`
4. **Size Limits**: Expanded from 2K to 4K maximum resolution
5. **Presets**: New convenient size presets for common use cases

## Pricing

Image generation costs are determined by FAL AI's pricing structure. Check [FAL AI Pricing](https://fal.ai/pricing) for current rates.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Support

For issues related to:
- **This MCP server**: Open an issue in this repository
- **FAL AI API**: Contact FAL AI support
- **SeedDream 4.0 model**: Refer to FAL AI documentation

## Changelog

### v0.2.0 (Latest - SeedDream 4.0)
- **🚀 Upgraded to SeedDream 4.0**: New unified architecture for generation and editing
- **📐 Flexible Image Sizing**: Support for custom dimensions up to 4096x4096
- **🎯 Enhanced Presets**: 9 convenient size presets for common use cases
- **🔒 Advanced Safety**: Improved content filtering with configurable safety checker
- **⚡ Multi-Image Generation**: Better control with `num_images` and `max_images`
- **🔄 Sync Mode**: Option for immediate image access without CDN delays
- **🛡️ Enhanced Validation**: Comprehensive input validation for all parameters
- **📊 Better Responses**: More detailed generation information and status

### v0.1.1 (SeedDream 3.0)
- **🔧 Fixed connection drops**: Removed `process.exit()` calls that caused server crashes
- **🛡️ Improved error handling**: Server continues running even without API token
- **🌍 Added portability**: npx configuration works on any machine
- **📦 Enhanced stability**: Graceful shutdown handlers and null safety checks
- **💬 Better user experience**: Clear error messages with setup instructions
- **🔄 Auto-updating**: npx pulls latest version from GitHub automatically

### v0.1.0 (SeedDream 3.0)
- Initial release with SeedDream 3.0
- Support for single and batch image generation
- Bilingual prompt support (English/Chinese)
- Multiple aspect ratios
- Configurable generation parameters