214 lines
5.5 KiB
Markdown
214 lines
5.5 KiB
Markdown
# 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
|