371 lines
13 KiB
Markdown
371 lines
13 KiB
Markdown
# Imagen4 MCP Server with Preview Images & Unicode Support
|
|
|
|
Google Imagen 4를 사용한 AI 이미지 생성 MCP 서버입니다. 하나의 `main.py` 파일로 모든 기능이 통합되어 있으며, **한글 프롬프트를 완벽 지원**합니다.
|
|
|
|
## 🚨 주의사항 - MCP 프로토콜 호환성
|
|
|
|
> **중요**: 이 서버는 MCP (Model Context Protocol)를 사용합니다. MCP는 stdout을 통해 JSON 메시지를 주고받으므로, 서버 코드에서 **절대로 stdout에 직접 출력하면 안됩니다**.
|
|
|
|
### ❌ 금지사항
|
|
```python
|
|
print("message") # ❌ MCP JSON 프로토콜 방해
|
|
print("message", file=sys.stdout) # ❌ MCP JSON 프로토콜 방해
|
|
sys.stdout.write("message") # ❌ MCP JSON 프로토콜 방해
|
|
```
|
|
|
|
### ✅ 권장사항
|
|
```python
|
|
print("message", file=sys.stderr) # ✅ 로그용 출력
|
|
logging.info("message") # ✅ 로깅 시스템 사용
|
|
logger.error("message") # ✅ 로깅 시스템 사용
|
|
```
|
|
|
|
### 최신 수정사항 (2025-08-26)
|
|
- **UTF-8 테스트 출력 비활성화**: `[UTF8-TEST]` 메시지가 MCP JSON 파싱을 방해하던 문제 수정
|
|
- **MCP 안전 실행**: `run_mcp_safe.py` 및 `run_mcp_safe.bat` 추가
|
|
- **호환성 테스트**: `test_mcp_compatibility.py` 추가
|
|
|
|
**개발 시 반드시 `CLAUDE.md` 파일의 개발 가이드라인을 참조하세요!**
|
|
|
|
- **고품질 이미지 생성**: 2048x2048 PNG 이미지 생성
|
|
- **미리보기 이미지**: 512x512 JPEG 미리보기를 base64로 제공
|
|
- **한글 프롬프트 지원**: 유니코드 로깅으로 한글 프롬프트 완벽 지원
|
|
- **파일 저장**: 원본 PNG + 메타데이터 JSON 저장 (UTF-8 인코딩)
|
|
- **재생성**: JSON 파일로부터 동일한 설정으로 재생성
|
|
- **랜덤 시드**: 재현 가능한 결과를 위한 시드 생성
|
|
|
|
## 🌐 유니코드 지원 개선사항
|
|
|
|
### 문제 해결
|
|
기존 버전에서 한글 프롬프트 로깅 시 발생했던 글자 깨짐 현상을 완전히 해결했습니다:
|
|
|
|
**이전 (깨진 로그):**
|
|
```
|
|
2025-08-21 11:34:52,783 - imagen4-mcp-server - INFO - Starting image generation: ' غ Ȱ ִ Ƹ ٿ ҳ , ǻ dz, Ȳ ݺ , ٴ ٶ 鸮 Ӹ ī , ڿ ', Seed: 2088268492
|
|
```
|
|
|
|
**현재 (올바른 로그):**
|
|
```
|
|
2025-08-21 11:34:52,783 - imagen4-mcp-server - INFO - Starting image generation: '아름다운 석양이 산 너머로 지는 모습, 따뜻한 오렌지색, 황금빛 구름', Seed: 2088268492
|
|
```
|
|
|
|
### 개선 내용
|
|
1. **UnicodeStreamHandler**: Windows 콘솔에서 UTF-8 출력 지원
|
|
2. **UnicodeFormatter**: 로그 메시지의 유니코드 문자 안전 처리
|
|
3. **ensure_unicode_string()**: 모든 문자열을 UTF-8로 안전하게 변환
|
|
4. **Windows 콘솔 설정**: `chcp 65001` 및 `PYTHONIOENCODING=utf-8` 자동 설정
|
|
|
|
## 📦 설치
|
|
|
|
### 1. 의존성 설치
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
필요한 패키지:
|
|
- `google-genai>=0.2.0` - Google Imagen 4 API
|
|
- `mcp>=1.0.0` - MCP 프로토콜
|
|
- `python-dotenv>=1.0.0` - 환경변수 관리
|
|
- `Pillow>=10.0.0` - 이미지 처리
|
|
|
|
### 2. 환경 설정
|
|
|
|
`.env` 파일을 생성하고 Google Cloud 자격 증명을 설정:
|
|
|
|
```env
|
|
GOOGLE_APPLICATION_CREDENTIALS=path/to/your/service-account-key.json
|
|
PROJECT_ID=your-gcp-project-id
|
|
LOCATION=us-central1
|
|
OUTPUT_PATH=./generated_images
|
|
```
|
|
|
|
## 🎮 사용법
|
|
|
|
### 서버 실행 (업데이트됨!)
|
|
|
|
#### MCP 안전 실행 (추천)
|
|
```bash
|
|
run_mcp_safe.bat
|
|
```
|
|
|
|
또는 Python으로 직접:
|
|
```bash
|
|
python run_mcp_safe.py
|
|
```
|
|
|
|
#### 직접 실행 (유니코드 환경 설정)
|
|
```bash
|
|
# Windows
|
|
chcp 65001
|
|
set PYTHONIOENCODING=utf-8
|
|
set PYTHONUTF8=1
|
|
python main.py
|
|
|
|
# Linux/Mac
|
|
export PYTHONIOENCODING=utf-8
|
|
python main.py
|
|
```
|
|
|
|
### Claude Desktop 설정
|
|
|
|
Claude Desktop 설정에 다음 내용을 추가하거나, `claude_desktop_config_mcp_safe.json` 파일을 사용하세요:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"imagen4": {
|
|
"command": "python",
|
|
"args": ["run_mcp_safe.py"],
|
|
"cwd": "D:\\Project\\imagen4",
|
|
"env": {
|
|
"PYTHONPATH": "D:\\Project\\imagen4",
|
|
"PYTHONIOENCODING": "utf-8",
|
|
"PYTHONUTF8": "1",
|
|
"LC_ALL": "C.UTF-8"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
> **중요**: MCP 호환성을 위해 `run_mcp_safe.py`를 사용하세요!
|
|
|
|
## 🛠️ 사용 가능한 도구
|
|
|
|
### 1. generate_image
|
|
고품질 이미지를 생성하고 미리보기를 제공합니다. **한글 프롬프트 완벽 지원!**
|
|
|
|
**파라미터:**
|
|
- `prompt` (필수): 이미지 생성 프롬프트 (한글/영어 모두 지원)
|
|
- `seed` (필수): 재현 가능한 결과를 위한 시드 값
|
|
- `negative_prompt` (선택): 제외할 요소 지정 (한글/영어 모두 지원)
|
|
- `number_of_images` (선택): 생성할 이미지 수 (1-2)
|
|
- `aspect_ratio` (선택): 종횡비 ("1:1", "9:16", "16:9", "3:4", "4:3")
|
|
- `save_to_file` (선택): 파일 저장 여부
|
|
|
|
**한글 프롬프트 예시:**
|
|
```
|
|
프롬프트: "아름다운 벚꽃이 만개한 봄날의 공원, 따뜻한 햇살이 나무들 사이로 스며드는 모습, 파스텔 톤의 분홍색과 초록색"
|
|
```
|
|
|
|
**응답 예시:**
|
|
```
|
|
✅ Images have been successfully generated!
|
|
|
|
🖼️ Preview Images Generated: 1 images (512x512 JPEG)
|
|
Preview 1 (base64 JPEG): /9j/4AAQSkZJRgABAQAAAQABAAD/2wBD...(67234 chars)
|
|
|
|
📁 Files saved:
|
|
- ./generated_images/imagen4_20250821_143052_seed_1234567890.png
|
|
- ./generated_images/imagen4_20250821_143052_seed_1234567890.json
|
|
|
|
⚙️ Generation Parameters:
|
|
- prompt: 아름다운 벚꽃이 만개한 봄날의 공원, 따뜻한 햇살이 나무들 사이로...
|
|
- seed: 1234567890
|
|
- aspect_ratio: 1:1
|
|
- number_of_images: 1
|
|
```
|
|
|
|
### 2. generate_random_seed
|
|
이미지 생성용 랜덤 시드를 생성합니다.
|
|
|
|
### 3. regenerate_from_json
|
|
저장된 JSON 파라미터 파일로부터 이미지를 재생성합니다. **한글 메타데이터 완벽 보존!**
|
|
|
|
## 🖼️ 미리보기 이미지 특징
|
|
|
|
### 변환 과정
|
|
1. **원본**: 2048x2048 PNG (약 8-15MB)
|
|
2. **변환**: 512x512 JPEG (약 50-200KB)
|
|
3. **최적화**: 품질 85, 최적화 활성화
|
|
4. **인코딩**: Base64 문자열
|
|
|
|
### 장점
|
|
- **95% 크기 감소**: 빠른 전송 및 표시
|
|
- **즉시 사용**: 웹 환경에서 바로 표시 가능
|
|
- **투명도 처리**: PNG 투명도를 흰색 배경으로 변환
|
|
- **종횡비 유지**: 원본 비율을 유지하면서 크기 조정
|
|
|
|
## 🌏 유니코드 로깅 기술적 세부사항
|
|
|
|
### 커스텀 로깅 핸들러
|
|
```python
|
|
class UnicodeStreamHandler(logging.StreamHandler):
|
|
"""Windows에서 UTF-8 출력을 보장하는 커스텀 핸들러"""
|
|
|
|
def __init__(self, stream=None):
|
|
super().__init__(stream)
|
|
# Windows 콘솔을 UTF-8로 재설정
|
|
if hasattr(self.stream, 'reconfigure'):
|
|
self.stream.reconfigure(encoding='utf-8', errors='replace')
|
|
```
|
|
|
|
### 문자열 안전 처리
|
|
```python
|
|
def ensure_unicode_string(value):
|
|
"""모든 문자열을 UTF-8 유니코드로 안전하게 변환"""
|
|
if isinstance(value, bytes):
|
|
return value.decode('utf-8', errors='replace')
|
|
elif isinstance(value, str):
|
|
return value
|
|
else:
|
|
return str(value)
|
|
```
|
|
|
|
### Windows 환경 자동 설정
|
|
- **코드페이지**: `chcp 65001` (UTF-8)
|
|
- **Python 환경변수**: `PYTHONIOENCODING=utf-8`, `PYTHONUTF8=1`
|
|
- **스트림 재설정**: stderr을 UTF-8 모드로 재구성
|
|
|
|
## 🧪 테스트
|
|
|
|
한글 프롬프트 지원을 테스트하려면:
|
|
|
|
```bash
|
|
python test_mcp_compatibility.py # MCP 호환성 테스트 (신규)
|
|
python test_main.py # 기본 기능 테스트
|
|
```
|
|
|
|
이 스크립트는 다음을 확인합니다:
|
|
- 모든 클래스 및 함수 import
|
|
- 이미지 처리 기능
|
|
- 미리보기 생성 기능
|
|
- 유니코드 문자열 처리
|
|
|
|
### 한글 테스트 예시
|
|
```python
|
|
# 한글 프롬프트 테스트
|
|
korean_prompt = "아름다운 한국의 전통 한옥, 단풍이 물든 가을 정원"
|
|
result = await client.generate_image({
|
|
"prompt": korean_prompt,
|
|
"seed": 12345
|
|
})
|
|
```
|
|
|
|
## 📁 프로젝트 구조
|
|
|
|
```
|
|
imagen4/
|
|
├── main.py # 통합된 메인 서버 파일 (유니코드 지원)
|
|
├── run.bat # 기본 Windows 실행 파일
|
|
├── run_unicode.bat # 유니코드 지원 Windows 실행 파일 (NEW!)
|
|
├── test_main.py # 테스트 스크립트
|
|
├── claude_desktop_config.json # Claude Desktop 설정
|
|
├── requirements.txt # 의존성 목록
|
|
├── .env # 환경 변수 (사용자가 생성)
|
|
├── generated_images/ # 생성된 이미지 저장소
|
|
└── src/
|
|
├── connector/ # Google API 연결 모듈
|
|
│ ├── __init__.py
|
|
│ ├── config.py
|
|
│ ├── imagen4_client.py # 유니코드 지원 개선
|
|
│ └── utils.py
|
|
└── server/ # 서버 핸들러
|
|
├── enhanced_handlers.py # 유니코드 지원 개선
|
|
└── ...
|
|
```
|
|
|
|
## 🔧 기술적 세부사항
|
|
|
|
### 이미지 처리
|
|
- **PIL (Pillow)** 사용으로 안정적인 이미지 변환
|
|
- **LANCZOS 리샘플링**으로 고품질 크기 조정
|
|
- **투명도 자동 처리**: RGBA → RGB 변환 시 흰색 배경 적용
|
|
- **중앙 정렬**: 목표 크기보다 작은 이미지는 중앙에 배치
|
|
|
|
### MCP 프로토콜
|
|
- **버전 3.1.0**: 미리보기 이미지 + 유니코드 지원
|
|
- **비동기 처리**: asyncio 기반 안정적인 비동기 작업
|
|
- **오류 처리**: 상세한 로깅 및 사용자 친화적 오류 메시지
|
|
- **타임아웃**: 6분 타임아웃으로 안전한 작업 보장
|
|
- **유니코드 로깅**: 한글 프롬프트 완벽 표시
|
|
|
|
### 유니코드 처리
|
|
- **UTF-8 강제**: 모든 텍스트 입출력을 UTF-8로 처리
|
|
- **에러 복구**: 인코딩 오류 시 'replace' 모드로 복구
|
|
- **크로스 플랫폼**: Windows/Linux/Mac 모든 환경에서 동작
|
|
|
|
## 🐛 문제 해결
|
|
|
|
### 일반적인 문제
|
|
|
|
1. **한글 로깅이 깨져 보이는 경우**
|
|
```bash
|
|
# Windows에서 run_unicode.bat 사용
|
|
run_unicode.bat
|
|
|
|
# 또는 수동으로 환경 설정
|
|
chcp 65001
|
|
set PYTHONIOENCODING=utf-8
|
|
python main.py
|
|
```
|
|
|
|
2. **Pillow 설치 오류**
|
|
```bash
|
|
pip install --upgrade pip
|
|
pip install Pillow
|
|
```
|
|
|
|
3. **Google Cloud 인증 오류**
|
|
- 서비스 계정 키 파일 경로 확인
|
|
- PROJECT_ID가 올바른지 확인
|
|
- Imagen API가 활성화되어 있는지 확인
|
|
|
|
4. **메모리 부족**
|
|
- 이미지 수를 1개로 제한
|
|
- 시스템 메모리 확인 (최소 8GB 권장)
|
|
|
|
### 로그 확인
|
|
|
|
서버 실행 시 자세한 로그가 stderr로 출력됩니다:
|
|
- 이미지 생성 진행 상황 (한글 프롬프트 포함)
|
|
- 미리보기 생성 과정
|
|
- 파일 저장 상태
|
|
- 오류 및 경고 메시지
|
|
|
|
**올바른 한글 로그 예시:**
|
|
```
|
|
2025-08-21 11:34:52,783 - imagen4-mcp-server - INFO - Starting image generation: '아름다운 석양이 산 너머로 지는 모습...', Seed: 2088268492
|
|
2025-08-21 11:34:52,783 - src.connector.imagen4_client - INFO - Starting image generation - Prompt: '아름다운 석양이 산 너머로...', Seed: 2088268492
|
|
```
|
|
|
|
## 🌟 새로운 기능 (v3.1.0)
|
|
|
|
### ✨ 유니코드 완벽 지원
|
|
- **한글 프롬프트**: 로깅에서 완벽하게 표시
|
|
- **국제화 지원**: 일본어, 중국어, 아랍어 등 모든 유니코드 문자
|
|
- **Windows 호환성**: Windows 콘솔에서 완벽한 UTF-8 표시
|
|
|
|
### 🔧 개선된 로깅
|
|
- **UnicodeStreamHandler**: 커스텀 로깅 핸들러
|
|
- **안전한 문자열 처리**: 인코딩 오류 방지
|
|
- **크로스 플랫폼**: 모든 OS에서 일관된 동작
|
|
|
|
### 📦 배치 파일 업그레이드
|
|
- **run_unicode.bat**: UTF-8 환경 자동 설정
|
|
- **환경변수 자동 설정**: PYTHONIOENCODING, PYTHONUTF8
|
|
- **콘솔 설정**: chcp 65001 자동 실행
|
|
|
|
## 📄 라이센스
|
|
|
|
MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.
|
|
|
|
## 🎯 요약
|
|
|
|
이 개선된 버전의 `main.py`는 다음과 같은 이점을 제공합니다:
|
|
|
|
- **완벽한 한글 지원**: 프롬프트와 로깅에서 한글 완벽 표시
|
|
- **단순성**: 하나의 파일로 모든 기능 제공
|
|
- **효율성**: 512x512 JPEG 미리보기로 빠른 응답
|
|
- **호환성**: 기존 MCP 클라이언트와 완벽 호환
|
|
- **국제화**: 모든 유니코드 문자 지원
|
|
- **확장성**: 필요에 따라 쉽게 기능 추가 가능
|
|
|
|
**이제 한글 프롬프트로 아름다운 이미지를 생성해보세요!**
|
|
|
|
```
|
|
프롬프트: "한국의 아름다운 설악산, 단풍이 물든 가을 풍경, 맑은 하늘과 구름"
|
|
```
|
|
|
|
Google Imagen 4의 강력한 이미지 생성 기능을 MCP 프로토콜을 통해 효율적으로 활용하되, 이제 **한글로도 자유롭게** 사용할 수 있습니다! 🎨🇰🇷
|