gpt-edit/WORKFLOW.md

# GPT-Edit MCP Server - Directory-based Processing Workflow

## 개요
이 문서는 GPT-Edit MCP 서버의 INPUT_PATH 기반 이미지 편집 및 처리 워크플로우를 설명합니다.

## 워크플로우

### 1. File-based Edit Processing (권장)
```
Client -> MCP Server: edit_image_from_file tool
├── input_image_name: "photo.jpg"
├── prompt: "edit description"
└── MCP Server Process:
    ├── 1. INPUT_PATH/photo.jpg 읽기
    ├── 2. base64 변환
    ├── 3. 이미지 편집 (OpenAI API)
    ├── 4. GENERATED_IMAGES_PATH에 저장:
    │   ├── {base_name}_000.png (원본 복사)
    │   └── {base_name}_001.png (편집본)
    └── 5. 응답: 편집된 이미지 + 메타데이터
```

### 2. Mask-based Edit Processing (권장)
```
Client -> MCP Server: edit_with_mask_from_file tool
├── input_image_name: "photo.jpg"
├── mask_image_name: "mask.png"
├── prompt: "edit description"
└── MCP Server Process:
    ├── 1. INPUT_PATH에서 파일들 읽기:
    │   ├── INPUT_PATH/photo.jpg
    │   └── INPUT_PATH/mask.png
    ├── 2. base64 변환
    ├── 3. 마스크 이미지 편집 (OpenAI API)
    ├── 4. GENERATED_IMAGES_PATH에 저장:
    │   ├── {base_name}_000.png (원본)
    │   ├── {base_name}_mask_000.png (마스크)
    │   └── {base_name}_001.png (편집본)
    └── 5. 응답: 편집된 이미지 + 메타데이터
```

### 3. Direct Upload Processing (선택사항)
```
Client -> MCP Server: edit_image tool
├── input_image_b64: base64 encoded image
├── prompt: "edit description"
└── MCP Server Process:
    ├── 1. base64 데이터 처리
    ├── 2. 임시 파일 생성
    ├── 3. 이미지 편집 (OpenAI API)
    ├── 4. GENERATED_IMAGES_PATH에 저장
    └── 5. 응답: 편집된 이미지 + 메타데이터
```

### 4. Directory Structure
```
Input Directory (INPUT_PATH):
├── photo.jpg                    # 원본 이미지
├── portrait.png                # 원본 이미지
└── mask.png                    # 마스크 이미지

Temp Directory (temp/):
├── temp_image_1234.png         # 임시 처리 파일들
└── [기타 임시 파일들]

Output Directory (GENERATED_IMAGES_PATH):
├── gptimage1_20250824_143022_000.png  # 원본 복사본
├── gptimage1_20250824_143022_001.png  # 편집된 이미지
├── gptimage1_20250824_143022_001.json # 메타데이터
└── [기타 결과 파일들]
```

## 주요 구성 요소

### 1. File-based Edit Tools
- **edit_image_from_file**: INPUT_PATH에서 파일명 기반 편집
- **edit_with_mask_from_file**: 마스크를 사용한 파일명 기반 편집

### 2. Direct Upload Tools  
- **edit_image**: Base64 데이터 직접 편집
- **edit_with_mask**: Base64 데이터와 마스크 편집

### 3. Utility Tools
- **move_temp_to_output**: 임시에서 출력 디렉토리로 파일 이동
- **validate_image**: 이미지 파일 유효성 검증
- **create_mask_from_alpha**: PNG 알파 채널에서 마스크 생성

### 4. Directory Configuration
```
project_root/
├── input_images/              # INPUT_PATH (원본 이미지)
│   ├── photo.jpg
│   └── mask.png
├── generated_images/          # GENERATED_IMAGES_PATH (출력 파일)
│   ├── gptimage1_*_000.png  # 원본 복사
│   ├── gptimage1_*_001.png  # 편집된 이미지
│   └── gptimage1_*_001.json # 메타데이터
└── temp/                      # 임시 파일 (자동 정리)
```

## API 사용 예시

### 1. File-based Edit (추천)
```json
{
  "method": "tools/call",
  "params": {
    "name": "edit_image_from_file",
    "arguments": {
      "input_image_name": "photo.jpg",
      "prompt": "Add a sunset background",
      "background": "transparent",
      "save_to_file": true
    }
  }
}
```

### 2. Mask-based File Edit (추천)
```json
{
  "method": "tools/call",
  "params": {
    "name": "edit_with_mask_from_file",
    "arguments": {
      "input_image_name": "portrait.jpg",
      "mask_image_name": "face_mask.png",
      "prompt": "Change hair color to blonde",
      "background": "transparent"
    }
  }
}
```

### 3. Direct Upload Edit
```json
{
  "method": "tools/call",
  "params": {
    "name": "edit_image",
    "arguments": {
      "input_image_b64": "iVBORw0KGgoAAAANSUhEUgAA...",
      "prompt": "Add a sunset background",
      "background": "transparent"
    }
  }
}
```

## 특징

### 1. 자동 파일 관리
- **임시 디렉토리**: 업로드된 파일의 일시적 저장
- **출력 디렉토리**: 편집된 결과의 영구 저장
- **자동 정리**: 선택적 파일 이동/복사

### 2. 유연한 파일명 처리
- 업로드시 파일명 지정 가능
- 자동 파일명 생성 (타임스탬프 기반)
- 파일 확장자 자동 감지

### 3. 오류 처리
- 파일 존재 확인
- 권한 오류 처리
- 디렉토리 자동 생성

## 설정

### Environment Variables
```bash
INPUT_PATH=./input_images                   # 원본 이미지 디렉토리
GENERATED_IMAGES_PATH=./generated_images     # 출력 디렉토리
SAVE_PARAMETERS=true                        # 메타데이터 저장
SAVE_ORIGINALS=true                         # 원본 복사 저장
```

### Default Paths
```python
INPUT_PATH = project_root/input_images
GENERATED_IMAGES_PATH = project_root/generated_images
TEMP_PATH = project_root/temp
```

### 사용 전 준비
1. **디렉토리 생성**: 자동으로 input_images/, generated_images/ 디렉토리 생성
2. **이미지 배치**: 편집할 이미지를 input_images/에 배치
3. **MCP 호출**: edit_image_from_file 또는 edit_with_mask_from_file 사용
4. **결과 확인**: generated_images/에서 편집 결과 확인

이제 MCP 서버는 INPUT_PATH에서 이미지를 읽어 편집하고, GENERATED_IMAGES_PATH에 결과를 저장하는 디렉토리 기반 이미지 편집 시스템입니다.