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 (추천)

{
  "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 (추천)

{
  "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

{
  "method": "tools/call",
  "params": {
    "name": "edit_image",
    "arguments": {
      "input_image_b64": "iVBORw0KGgoAAAANSUhEUgAA...",
      "prompt": "Add a sunset background",
      "background": "transparent"
    }
  }
}

특징

1. 자동 파일 관리

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

2. 유연한 파일명 처리

• 업로드시 파일명 지정 가능
• 자동 파일명 생성 (타임스탬프 기반)
• 파일 확장자 자동 감지

3. 오류 처리

• 파일 존재 확인
• 권한 오류 처리
• 디렉토리 자동 생성

설정

Environment Variables

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

Default Paths

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에 결과를 저장하는 디렉토리 기반 이미지 편집 시스템입니다.