# SeedDream 4.0 Replicate MCP Server

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

## Features

SeedDream 4.0 is a bilingual (Chinese and English) text-to-image model that excels at:

- **Native 2K high resolution output** with various aspect ratios
- **Exceptional text layout** for visually stunning results
- **Accurate small and large text generation**
- **Photorealistic portraits** with cinematic beauty
- **Fast generation** (3 seconds for 1K images)
- **Strong instruction following** and enhanced aesthetics

## Available Tools

### `generate_image`
Generate a single image from a text prompt using SeedDream 4.0 via Replicate.

**Parameters:**
- `prompt` (required): Text description of the image to generate (supports English and Chinese)
- `aspect_ratio` (optional): Image aspect ratio - one of: `1:1`, `3:4`, `4:3`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9`, `custom` (default: `16:9`)
- `size` (optional): Image size - one of: `small`, `regular`, `big` (default: `regular`)
  - `small`: Shortest dimension 512px
  - `regular`: Always 1 megapixel 
  - `big`: Longest dimension 2048px
  - Ignored if aspect ratio is `custom`
- `width` (optional): Image width in pixels (512-2048, only used when aspect_ratio is `custom`)
- `height` (optional): Image height in pixels (512-2048, only used when aspect_ratio is `custom`)
- `guidance_scale` (optional): Prompt adherence, higher = more literal (1.0-10.0, default: 2.5)
- `seed` (optional): Random seed for reproducible results (0-2147483647)

## Installation

### Prerequisites

1. **Replicate API Token**: Get your API token from [Replicate](https://replicate.com/)
   - Sign up for an account at https://replicate.com/
   - Navigate to your account settings and generate an API token
   - Keep this token 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": {
    "seedream": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-replicate-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_replicate_token_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": {
    "seedream": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-replicate-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_replicate_token_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-replicate-mcp-server.git
   cd seedream-v4-replicate-mcp-server
   ```

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

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

4. **Use absolute path in configuration**
   ```json
   {
     "mcpServers": {
       "seedream": {
         "command": "node",
         "args": ["/absolute/path/to/seedream-v4-replicate-mcp-server/build/index.js"],
         "env": {
           "REPLICATE_API_TOKEN": "r8_your_replicate_token_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 serene mountain landscape at sunset with a lake reflection
```

### Specific Aspect Ratio
```
Create a portrait-oriented image of a futuristic cityscape (aspect ratio 9:16)
```

### Multiple Images
```
Generate 3 variations of a cute robot character
```

### Batch Generation
```
Generate images for these prompts: "a red rose", "a blue ocean", "a green forest"
```

### Chinese Language Support
```
生成一张中国传统山水画的图片
```

### High Guidance for Precise Results
```
Generate a photorealistic portrait of a person reading a book in a library (guidance scale: 7.5)
```

## API Response Format

The server returns detailed information about generated images:

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

Prompt: "a serene mountain landscape at sunset"
Aspect Ratio: 1:1
Guidance Scale: 2.5
Seed Used: 1234567890

Generated Images:
Image 1 (1024x1024): https://v3.fal.media/files/...
```

## 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. **"REPLICATE_API_TOKEN environment variable is not set"**
   - The server will continue running and show this helpful error message
   - Ensure your Replicate API token is properly set in the MCP configuration
   - Verify the token is valid and has sufficient credits
   - **Note**: The server no longer crashes when the API token 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 Replicate account has sufficient credits
   - Verify your API token has the necessary permissions
   - Try with a simpler prompt to test connectivity

4. **"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

### 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
- Graceful shutdown notifications

## Pricing

Image generation costs are determined by Replicate's pricing structure. Check [Replicate Pricing](https://replicate.com/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
- **Replicate API**: Contact Replicate support
- **SeedDream 4.0 model**: Refer to Replicate documentation

## Changelog

### v0.1.1 (Latest)
- **🔧 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
- Initial release
- Support for single and batch image generation
- Bilingual prompt support (English/Chinese)
- Multiple aspect ratios
- Configurable generation parameters