# GPT-Edit - OpenAI Image Editing MCP Server

GPT-Edit는 OpenAI의 이미지 편집 API를 MCP(Model Context Protocol) 서버로 구현한 프로젝트입니다.
Claude Desktop과 연동하여 자연어로 이미지를 편집할 수 있습니다.

## 🚀 Quick Start

### 1. 설치
```bash
# 저장소 클론
git clone https://github.com/yourusername/gpt-edit.git
cd gpt-edit

# 의존성 설치
pip install -r requirements.txt

# 환경 변수 설정
copy .env.example .env
# .env 파일을 열어 OPENAI_API_KEY 설정
```

### 2. 실행
```bash
# Windows - 배치 파일
run.bat

# Windows - PowerShell
.\run.ps1

# 직접 실행
python main.py
```

### 3. Claude Desktop 연동
`%APPDATA%\Claude\claude_desktop_config.json` 파일 편집:
```json
{
  "mcpServers": {
    "gpt-edit": {
      "command": "python",
      "args": ["D:\\Project\\gpt-edit\\main.py"]
    }
  }
}
```

자세한 설정은 [MCP Connector Guide](MCP_CONNECTOR_GUIDE.md) 참조

## 📁 디렉토리 구조

### 입력 및 출력 디렉토리
- **INPUT_PATH**: `input_images/` - 편집할 원본 이미지 저장
- **GENERATED_IMAGES_PATH**: `generated_images/` - 편집 결과 저장

### 파일 구조 예시
```
input_images/                           # 원본 이미지 보관
├── photo.jpg
├── portrait.png
└── mask.png

generated_images/                       # 편집 결과물
├── gptimage1_20250824_143022_000.png   # 원본 복사본
├── gptimage1_20250824_143022_001.png   # 편집된 출력
└── gptimage1_20250824_143022_001.json  # 편집 파라미터
```

### 파일명 형식
- **Base Name**: `gptimage1_{yyyymmdd}_{hhmmss}`
- **원본**: `{base_name}_000.png` (INPUT_PATH에서 복사)
- **편집본**: `{base_name}_001.png`, `{base_name}_002.png`, ...
- **파라미터**: `{base_name}_001.json`, `{base_name}_002.json`, ...

## 🛠️ 사용 가능한 도구

### 1. edit_image_from_file (권장 ⭐)
INPUT_PATH에서 이미지를 읽어 편집하고 GENERATED_IMAGES_PATH에 저장합니다.
```
예: edit_image_from_file("photo.jpg", "Make the sky more dramatic")
사용법:
1. photo.jpg를 input_images/에 배치
2. 명령 실행
3. generated_images/에 결과 생성
```

### 2. edit_with_mask_from_file (권장 ⭐)
INPUT_PATH에서 이미지와 마스크를 읽어 선택적 편집을 수행합니다.
```
예: edit_with_mask_from_file("photo.jpg", "mask.png", "Replace the background")
사용법:
1. photo.jpg와 mask.png를 input_images/에 배치
2. 명령 실행
3. generated_images/에 결과 생성
```

### 3. edit_image
Base64 형식의 이미지를 받아 지정된 프롬프트로 편집합니다.
```
예: "Make the sky more dramatic" (image_data_b64 포함)
```

### 4. edit_with_mask
마스크를 사용하여 특정 영역만 편집합니다.
```
예: "Replace the background using mask" (image_data_b64 + mask_data_b64 포함)
```

### 4. batch_edit
여러 이미지를 한 번에 편집합니다. (최대 16개)
```
예: "Apply vintage filter to all images"
```

### 5. validate_image
이미지가 편집 가능한지 검증합니다.
```
예: "Check if image.png is valid for editing"
```

### 6. create_mask_from_alpha
PNG 알파 채널에서 마스크를 생성합니다.
```
예: "Create mask from transparent areas"
```

### 7. move_temp_to_output
temp 디렉토리에서 output 디렉토리로 파일을 이동합니다.
```
예: 수동 파일 관리
```

## ⚙️ 환경 변수 설정

`.env` 파일:
```bash
# 필수
OPENAI_API_KEY=sk-xxxxx

# 디렉토리 설정
INPUT_PATH=./input_images                  # 원본 이미지 디렉토리
GENERATED_IMAGES_PATH=./generated_images    # 결과 저장 디렉토리

# 선택사항
OPENAI_ORGANIZATION=org-xxxxx
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
```

전체 설정 옵션은 [Setup Guide](SETUP_GUIDE.md) 참조

## 📊 주요 기능

- ✅ **자동 이미지 최적화**: 4MB 이상 이미지 자동 압축
- ✅ **토큰 관리**: 프롬프트 길이 자동 조절
- ✅ **배치 처리**: 최대 16개 이미지 동시 편집
- ✅ **마스크 지원**: 특정 영역만 선택적 편집
- ✅ **파라미터 저장**: 모든 편집 내역 JSON으로 저장
- ✅ **투명 배경**: transparent/opaque 배경 선택

## 🔍 문제 해결

### Server disconnected 오류
1. Python 경로 확인
2. `.env` 파일의 API 키 확인
3. `requirements.txt` 설치 확인

### Method not found 오류
1. 최신 코드 확인
2. Claude Desktop 재시작

### 파일을 찾을 수 없음
1. `generated_images/` 디렉토리 확인
2. 파일 권한 확인

자세한 문제 해결은 [Setup Guide](SETUP_GUIDE.md#troubleshooting) 참조

## 📚 문서

- **[CLAUDE.md](CLAUDE.md)** - MCP 서버 개발 가이드 및 설계 원칙
- **[TECHNICAL_SPECS.md](TECHNICAL_SPECS.md)** - 기술 사양 및 API 상세 정보
- **[MCP_CONNECTOR_GUIDE.md](MCP_CONNECTOR_GUIDE.md)** - Claude Desktop 연동 가이드
- **[SETUP_GUIDE.md](SETUP_GUIDE.md)** - 상세 설치 및 설정 가이드

## 🔧 기술 사양

- **모델**: OpenAI GPT-Image-1
- **지원 크기**: 256x256, 512x512, 1024x1024, 1024x1536, 1536x1024
- **입력 형식**: PNG, JPEG, WebP, GIF, BMP
- **최대 크기**: 4MB (자동 최적화 지원)
- **토큰 제한**: 1000 토큰 (1024x1024 기준)

자세한 사양은 [Technical Specifications](TECHNICAL_SPECS.md) 참조

## 📄 라이선스

MIT License

## 🤝 기여

Pull Request 환영합니다!

## 📞 지원

Issues 탭에서 문제를 보고해주세요.

---

Made with ❤️ for Claude Desktop MCP ecosystem