gpt-edit/SETUP_GUIDE.md

# GPT-Edit MCP Server Setup Guide

## 🚀 Quick Setup

### 1. Install GPT-Edit

```bash
# Clone or navigate to the project
cd D:\Project\gpt-edit

# Install dependencies
pip install -r requirements.txt
```

### 2. Configure API Key

Create a `.env` file in the project directory:

```env
# Required
OPENAI_API_KEY=sk-your-api-key-here

# Directory paths (optional)
INPUT_PATH=./input_images
GENERATED_IMAGES_PATH=./generated_images
```

### 3. Configure Claude Desktop

Add GPT-Edit to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "gpt-edit": {
      "command": "python",
      "args": ["D:\\Project\\gpt-edit\\main.py"]"
    }
  }
}
```

### 4. Restart Claude Desktop

After saving the configuration, restart Claude Desktop completely.

## ⚙️ Configuration Options

### Environment Variables

Create a `.env` file in the project root:

```env
# Required
OPENAI_API_KEY=sk-your-api-key-here

# Directory Configuration (optional)
INPUT_PATH=./input_images                    # Source images directory
GENERATED_IMAGES_PATH=./generated_images     # Output directory

# File naming and processing (optional with defaults)
OUTPUT_FILENAME_PREFIX=gptimage1
MAX_IMAGE_SIZE_MB=4
DEFAULT_TIMEOUT=30
ENABLE_AUTO_OPTIMIZE=true
SAVE_ORIGINALS=true
SAVE_PARAMETERS=true
LOG_LEVEL=INFO
```

### Environment Variable Reference

| Variable | Description | Default | Example |
|----------|-------------|---------|---------|
| `OPENAI_API_KEY` | **Required** - Your OpenAI API key | - | `sk-xxxxx` |
| `INPUT_PATH` | Directory for source images | `./input_images` | `./my_images` |
| `GENERATED_IMAGES_PATH` | Directory for output files | `./generated_images` | `./results` |
| `OUTPUT_FILENAME_PREFIX` | Prefix for output files | `gptimage1` | `my_edit` |
| `MAX_IMAGE_SIZE_MB` | Auto-optimize threshold | `4` | `1-10` |
| `DEFAULT_TIMEOUT` | API request timeout (seconds) | `30` | `60` |
| `ENABLE_AUTO_OPTIMIZE` | Auto WebP conversion | `true` | `true/false` |
| `SAVE_ORIGINALS` | Copy input images to output | `true` | `true/false` |
| `SAVE_PARAMETERS` | Save JSON parameters | `true` | `true/false` |
| `LOG_LEVEL` | Logging level | `INFO` | `DEBUG`, `WARNING` |

## 📁 File Structure

After running, GPT-Edit creates this structure:

```
gpt-edit/
├── input_images/                  # Source images (INPUT_PATH)
│   ├── photo.jpg
│   ├── portrait.png
│   └── mask.png
├── generated_images/              # All output files (GENERATED_IMAGES_PATH)
│   ├── gptimage1_20250824_143022_000.png   # Original (copied from input)
│   ├── gptimage1_20250824_143022_001.png   # Edited output
│   └── gptimage1_20250824_143022_001.json  # Edit parameters
├── temp/                          # Temporary files (auto-cleaned)
└── gpt-edit.log                   # Debug log
```

## 🎯 Usage Examples in Claude

### Method 1: File-based editing (Recommended)
```
I placed photo.jpg in the input_images folder. 
Can you edit it using edit_image_from_file to make it more vibrant?
```

### Method 2: Direct upload editing
```
I have an image I'd like to edit. Can you make it more colorful and vibrant?
[Upload image to Claude]
```

### Method 3: Mask-based editing
```
I have photo.jpg and mask.png in input_images/. 
Can you use edit_with_mask_from_file to replace only the background?
```

## 🔍 Troubleshooting

### Common Issues and Solutions

#### "Server disconnected"
1. Check Python is installed: `python --version`
2. Verify dependencies: `pip list | grep mcp`
3. Check `.env` file exists with API key
4. Look at `gpt-edit.log` for errors

#### "API key not found"
1. Ensure `.env` file is in project root (same folder as `main.py`)
2. Check API key format: `OPENAI_API_KEY=sk-xxxxx`
3. No quotes needed around the key

#### "Method not found"
1. Update to latest code: `git pull`
2. Reinstall dependencies: `pip install -r requirements.txt`
3. Restart Claude Desktop completely

#### "Image too large"
- Enable auto-optimization: `ENABLE_AUTO_OPTIMIZE=true`
- Or increase limit: `MAX_IMAGE_SIZE_MB=8`

#### "Cannot find output images"
- Check `generated_images/` folder
- Files named: `gptimage1_{seed}_{date}_{time}_{number}.png`
- Look for most recent by timestamp

### Verify Installation

Test the setup:
```bash
python main.py
```

You should see:
```
Starting GPTEdit MCP Server
GPTEdit MCP Server is running...
Ready to process image editing requests
```

Press `Ctrl+C` to stop.

## 🛡️ Security Best Practices

1. **API Key Management**
   - Store API key only in `.env` file
   - Never commit `.env` to version control
   - Add `.env` to `.gitignore`

2. **File Permissions**
   - Ensure `generated_images/` is writable
   - Keep sensitive files in project directory only

3. **Logging**
   - Use `INFO` level for normal operation
   - `DEBUG` only for troubleshooting
   - Rotate logs periodically

## 📚 Additional Resources

- [OpenAI API Documentation](https://platform.openai.com/docs)
- [MCP Protocol Specification](https://modelcontextprotocol.io)
- [Project README](README.md)
- [Technical Specifications](TECHNICAL_SPECS.md)

## 💡 Tips

1. **Performance**
   - Smaller images (512x512) process faster
   - Batch editing is more efficient than individual edits
   - WebP format reduces file sizes significantly

2. **Quality**
   - Use clear, specific prompts
   - Provide masks for precise edits
   - Save parameters for reproducibility

3. **Organization**
   - Files are grouped by session (same seed)
   - JSON parameters allow replay of edits
   - Timestamps help track edit history

## 🆘 Support

For issues:
1. Check `gptedit.log` for detailed errors
2. Verify OpenAI API key has credits
3. Ensure all paths are accessible
4. Create an issue on GitHub

---

Happy editing with GPT-Edit! 🎨