print("message")                    # ❌ MCP JSON 프로토콜 방해
print("message", file=sys.stdout)   # ❌ MCP JSON 프로토콜 방해
sys.stdout.write("message")         # ❌ MCP JSON 프로토콜 방해

✅ 권장사항

print("message", file=sys.stderr)   # ✅ 로그용 출력
logging.info("message")             # ✅ 로깅 시스템 사용
logger.error("message")             # ✅ 로깅 시스템 사용

🌐 유니코드 지원 개선사항

문제 해결

기존 버전에서 한글 프롬프트 로깅 시 발생했던 글자 깨짐 현상을 완전히 해결했습니다:

이전 (깨진 로그):

2025-08-21 11:34:52,783 - imagen4-mcp-server - INFO - Starting image generation: ' غ     Ȱ   ִ   Ƹ  ٿ   ҳ ,            ǻ ǳ, Ȳ ݺ      ,  ٴ ٶ      鸮    Ӹ ī  ,  ڿ            ', Seed: 2088268492

현재 (올바른 로그):

2025-08-21 11:34:52,783 - imagen4-mcp-server - INFO - Starting image generation: '아름다운 석양이 산 너머로 지는 모습, 따뜻한 오렌지색, 황금빛 구름', Seed: 2088268492

개선 내용

UnicodeStreamHandler: Windows 콘솔에서 UTF-8 출력 지원
UnicodeFormatter: 로그 메시지의 유니코드 문자 안전 처리
ensure_unicode_string(): 모든 문자열을 UTF-8로 안전하게 변환
Windows 콘솔 설정: chcp 65001 및 PYTHONIOENCODING=utf-8 자동 설정

📦 설치

1. 의존성 설치

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 자격 증명을 설정:

GOOGLE_APPLICATION_CREDENTIALS=path/to/your/service-account-key.json
PROJECT_ID=your-gcp-project-id
LOCATION=us-central1
OUTPUT_PATH=./generated_images

🎮 사용법

서버 실행 (업데이트됨!)

MCP 안전 실행 (추천)

run_mcp_safe.bat

또는 Python으로 직접:

python run_mcp_safe.py

직접 실행 (유니코드 환경 설정)

# 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 파일을 사용하세요:

{
  "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 파라미터 파일로부터 이미지를 재생성합니다. 한글 메타데이터 완벽 보존!

🖼️ 미리보기 이미지 특징

변환 과정

원본: 2048x2048 PNG (약 8-15MB)
변환: 512x512 JPEG (약 50-200KB)
최적화: 품질 85, 최적화 활성화
인코딩: Base64 문자열

장점

95% 크기 감소: 빠른 전송 및 표시
즉시 사용: 웹 환경에서 바로 표시 가능
투명도 처리: PNG 투명도를 흰색 배경으로 변환
종횡비 유지: 원본 비율을 유지하면서 크기 조정

🌏 유니코드 로깅 기술적 세부사항

커스텀 로깅 핸들러

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')

문자열 안전 처리

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 모드로 재구성

🧪 테스트

한글 프롬프트 지원을 테스트하려면:

python test_mcp_compatibility.py  # MCP 호환성 테스트 (신규)
python test_main.py                # 기본 기능 테스트

이 스크립트는 다음을 확인합니다:

모든 클래스 및 함수 import
이미지 처리 기능
미리보기 생성 기능
유니코드 문자열 처리

한글 테스트 예시

# 한글 프롬프트 테스트
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 모든 환경에서 동작

🐛 문제 해결

일반적인 문제

한글 로깅이 깨져 보이는 경우

# Windows에서 run_unicode.bat 사용
run_unicode.bat

# 또는 수동으로 환경 설정
chcp 65001
set PYTHONIOENCODING=utf-8
python main.py

Pillow 설치 오류

pip install --upgrade pip
pip install Pillow

Google Cloud 인증 오류
- 서비스 계정 키 파일 경로 확인
- PROJECT_ID가 올바른지 확인
- Imagen API가 활성화되어 있는지 확인
메모리 부족
- 이미지 수를 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 프로토콜을 통해 효율적으로 활용하되, 이제 한글로도 자유롭게 사용할 수 있습니다! 🎨🇰🇷

README.md

Imagen4 MCP Server with Preview Images & Unicode Support

🚨 주의사항 - MCP 프로토콜 호환성

❌ 금지사항