flux1-edit/README.md

# FLUX.1 Edit MCP Server

FLUX.1 Kontext 모델을 이용한 이미지 편집 전용 MCP (Model Context Protocol) 서버입니다.

## 주요 기능

- **이미지 편집**: FLUX.1 Kontext API를 이용한 고품질 이미지 편집
- **시드 기반 재현성**: 동일한 시드로 일관된 편집 결과 보장
- **대용량 이미지 지원**: 최대 20MB 이미지 처리
- **MCP 통합**: Claude와 완전 통합된 이미지 편집 도구

## 설치 및 설정

### 빠른 설치 (권장)

**Windows 배치 파일 사용:**
```bash
# 의존성 자동 설치
install_dependencies.bat

# 서버 실행
run.bat
```

**PowerShell 스크립트 사용:**
```powershell
# 의존성 자동 설치
.\install_dependencies.ps1

# 서버 실행
.\run.ps1
```

### 수동 설치

1. **Python 가상 환경 생성**
```bash
python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac
```

2. **의존성 설치**
```bash
pip install -r requirements.txt
```

3. **환경변수 설정**
```bash
copy .env.example .env  # Windows
cp .env.example .env    # Linux/Mac
# .env 파일에서 FLUX_API_KEY 설정
```

4. **필요한 디렉터리 생성**
```bash
mkdir input_images generated_images temp
```

5. **서버 실행**
```bash
python main.py
```

## 문제 해결

### 일반적인 오류들

#### "ModuleNotFoundError: No module named 'aiohttp'"
```bash
# 문제 진단
troubleshoot.bat

# 또는 직접 설치
pip install aiohttp==3.11.7
```

#### 가상 환경 활성화 문제
```bash
# 가상 환경 재생성
rmdir /s venv
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```

#### PowerShell 실행 정책 오류
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### 문제 진단 도구

**자동 진단 실행:**
```bash
troubleshoot.bat
```

이 스크립트는 다음을 확인합니다:
- Python 설치
- pip 가용성
- 가상 환경 상태
- 필수 패키지 설치 상태
- 설정 파일 존재
- 로컬 모듈 import 가능성

### 수동 의존성 확인

```bash
python -c "
import aiohttp
import httpx  
import mcp
from PIL import Image
import dotenv
import pydantic
print('All dependencies are working!')
"
```

## 환경 요구사항

- Python 3.8 이상
- 안정적인 인터넷 연결 (FLUX API 통신용)
- FLUX API 키

## 사용 가능한 도구

### flux_edit_image
FLUX.1 Kontext로 이미지를 편집합니다.

**파라미터:**
- `input_image_b64`: Base64 인코딩된 입력 이미지
- `prompt`: 편집 설명
- `seed`: 재현성을 위한 시드값
- `aspect_ratio`: "1:1" | "16:9" 등 (기본: "1:1")
- `save_to_file`: 파일 저장 여부 (기본: True)

### validate_image
이미지 파일의 유효성을 검증합니다.

### move_temp_to_output
임시 파일을 출력 디렉터리로 이동합니다.

## 디렉터리 구조

```
flux1-edit/
├── main.py                    # 메인 실행 파일
├── requirements.txt           # Python 의존성
├── .env                      # 환경 설정 (FLUX_API_KEY)
├── .env.example              # 환경 설정 예제
├── install_dependencies.bat  # Windows 자동 설치
├── install_dependencies.ps1  # PowerShell 자동 설치
├── run.bat                   # Windows 실행 스크립트
├── run.ps1                   # PowerShell 실행 스크립트
├── troubleshoot.bat          # 문제 진단 도구
├── src/                      # 소스 코드
│   ├── connector/            # FLUX API 연결
│   ├── server/               # MCP 서버
│   └── utils/                # 유틸리티
├── input_images/             # 입력 이미지
├── generated_images/         # 출력 이미지
├── temp/                     # 임시 파일
└── tests/                    # 테스트 파일
```

## Claude 설정

MCP 서버를 Claude에 연결하려면:

1. Claude 설정에서 MCP 서버 추가
2. 서버 명령: `python D:\Project\flux1-edit\main.py`
3. 작업 디렉터리: `D:\Project\flux1-edit`

## API 제한사항

- 최대 이미지 크기: 20MB
- 출력 형식: PNG 고정
- 결과 URL 유효시간: 10분
- 편집 타임아웃: 5분

## 로그 및 디버깅

- 로그 파일: `flux1-edit.log`
- 로그 레벨: INFO (콘솔), DEBUG (파일)
- 오류 추적: 전체 스택 트레이스 포함

## 지원 및 문의

문제가 지속되는 경우:
1. `troubleshoot.bat` 실행하여 진단 정보 확인
2. `flux1-edit.log` 파일에서 자세한 오류 로그 확인
3. 가상 환경 재생성 후 재시도

## 라이선스

MIT License