# 저장소 클론
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. 실행

# Windows - 배치 파일
run.bat

# Windows - PowerShell
.\run.ps1

# 직접 실행
python main.py

3. Claude Desktop 연동

%APPDATA%\Claude\claude_desktop_config.json 파일 편집:

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

자세한 설정은 MCP Connector Guide 참조

📁 디렉토리 구조

입력 및 출력 디렉토리

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 파일:

# 필수
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 참조

📊 주요 기능

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

🔍 문제 해결

Server disconnected 오류

Python 경로 확인
.env 파일의 API 키 확인
requirements.txt 설치 확인

Method not found 오류

최신 코드 확인
Claude Desktop 재시작

파일을 찾을 수 없음

generated_images/ 디렉토리 확인
파일 권한 확인

자세한 문제 해결은 Setup Guide 참조

📚 문서

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

🔧 기술 사양

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

자세한 사양은 Technical Specifications 참조

📄 라이선스

MIT License

🤝 기여

Pull Request 환영합니다!

📞 지원

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

Made with ❤️ for Claude Desktop MCP ecosystem