From 0c7c0b32878c20f771c5da2b5232a696e8432ae8 Mon Sep 17 00:00:00 2001 From: ened Date: Mon, 25 Aug 2025 23:50:31 +0900 Subject: [PATCH] update claude memory --- CLAUDE.md | 319 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 288 insertions(+), 31 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index dd2f8d1..67ceb1d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,15 +1,139 @@ -# CLAUDE.md - 개발 가이드 +# CLAUDE.md - Imagen4 MCP 서버 개발 가이드 -## 🚨 인코딩 문제 방지 (Windows cp949 오류) +## 프로젝트 개요 -### 증상 +Google Imagen4 API를 활용한 MCP(Model Context Protocol) 서버 구현체입니다. 모듈화된 아키텍처로 설계되어 있으며 한글 프롬프트와 UTF-8 인코딩을 완벽 지원합니다. + +### 주요 특징 +- Google Imagen4 API 연동을 통한 고품질 이미지 생성 (2048x2048 PNG) +- MCP 프로토콜 완전 지원으로 Claude Desktop과 원활한 연동 +- 512x512 JPEG 미리보기 이미지를 base64로 제공하여 빠른 확인 가능 +- Windows 환경에서 한글 프롬프트 완벽 지원 (UTF-8 강제 설정) +- 비동기 태스크 처리 및 백그라운드 워커 풀 지원 +- 향상된 에러 처리 및 재시도 로직 +- 메타데이터 JSON 저장으로 이미지 재생성 지원 + +## 프로젝트 구조 + +``` +imagen4/ +├── main.py # 통합 실행 파일 (서버 진입점) +├── requirements.txt # 의존성 패키지 +├── .env # 환경변수 설정 (사용자 생성 필요) +├── run_utf8.bat # UTF-8 환경 서버 실행 스크립트 +├── test_main.py # 기본 기능 테스트 +├── claude_desktop_config.json # Claude Desktop MCP 설정 +├── generated_images/ # 이미지 생성 결과 저장소 +│ ├── *.png # 원본 이미지 (2048x2048) +│ └── *.json # 생성 메타데이터 +└── src/ + ├── connector/ # Google Imagen4 API 연결 + │ ├── config.py # 환경변수 및 설정 관리 + │ ├── imagen4_client.py # API 클라이언트 (412라인) + │ └── utils.py # 유틸리티 함수 + ├── server/ # MCP 서버 구현 + │ ├── models.py # 데이터 모델 및 도구 정의 (132라인) + │ ├── mcp_server.py # MCP 서버 메인 클래스 + │ ├── handlers.py # 도구 핸들러 로직 (308라인) + │ └── enhanced_handlers.py # 향상된 핸들러 (344라인) + ├── async_task/ # 비동기 작업 관리 + │ ├── models.py # 태스크 모델 + │ ├── task_manager.py # 태스크 매니저 (324라인) + │ └── worker_pool.py # 워커 풀 (258라인) + └── utils/ # 유틸리티 모듈 + ├── error_recovery.py # 에러 복구 및 재시도 (237라인) + ├── image_utils.py # 이미지 처리 (107라인) + └── token_utils.py # 토큰 관리 (200라인) +``` + +## 설치 및 실행 + +### 1. 의존성 설치 +```bash +pip install -r requirements.txt +``` + +**필수 패키지:** +- `google-genai>=0.2.0` - Google Imagen4 API +- `mcp>=1.0.0` - MCP 프로토콜 +- `python-dotenv>=1.0.0` - 환경변수 관리 +- `Pillow>=10.0.0` - 이미지 처리 +- `pytest>=7.0.0` - 테스트 프레임워크 + +### 2. 환경 설정 + +`.env` 파일 생성: +```env +GOOGLE_APPLICATION_CREDENTIALS=path/to/your/service-account-key.json +PROJECT_ID=your-gcp-project-id +LOCATION=us-central1 +OUTPUT_PATH=./generated_images +``` + +### 3. 서버 실행 + +**Windows (권장):** +```bash +run_utf8.bat +``` + +**수동 실행:** +```bash +# Windows +chcp 65001 +set PYTHONIOENCODING=utf-8 +set PYTHONUTF8=1 +python main.py + +# Linux/Mac +export PYTHONIOENCODING=utf-8 +python main.py +``` + +### 4. Claude Desktop 연동 + +`claude_desktop_config.json` 내용을 Claude Desktop 설정에 추가: +```json +{ + "mcpServers": { + "imagen4": { + "command": "python", + "args": ["main.py"], + "cwd": "D:\\Project\\imagen4", + "env": { + "PYTHONPATH": "D:\\Project\\imagen4" + } + } + } +} +``` + +## 핵심 기능 + +### 1. 이미지 생성 (generate_image) +- **입력**: 한글/영어 프롬프트, 시드값, 설정 옵션 +- **출력**: 2048x2048 PNG + 512x512 JPEG 미리보기 (base64) +- **지원 비율**: 1:1, 9:16, 16:9, 3:4, 4:3 +- **최대 생성**: 2개 이미지 동시 생성 + +### 2. 랜덤 시드 생성 (generate_random_seed) +- 재현 가능한 이미지 생성을 위한 시드값 제공 + +### 3. JSON 기반 재생성 (regenerate_from_json) +- 저장된 메타데이터로 동일한 설정의 이미지 재생성 + +## UTF-8 인코딩 지원 + +### Windows cp949 오류 방지 + +**증상:** ``` 'cp949' codec can't encode character '\U0001f4ad' in position 0: illegal multibyte sequence ``` -### 해결책 +**해결책:** -**1. Python 파일 상단 필수 코드** +**1. 자동 UTF-8 설정 (main.py 상단)** ```python #!/usr/bin/env python3 # -*- coding: utf-8 -*- @@ -20,16 +144,14 @@ import sys # UTF-8 강제 설정 os.environ['PYTHONIOENCODING'] = 'utf-8' os.environ['PYTHONUTF8'] = '1' +os.environ['LC_ALL'] = 'C.UTF-8' -# Windows UTF-8 설정 +# Windows UTF-8 콘솔 설정 if sys.platform.startswith('win'): - import codecs + os.system('chcp 65001 >nul 2>&1') if hasattr(sys.stdout, 'reconfigure'): sys.stdout.reconfigure(encoding='utf-8', errors='replace') sys.stderr.reconfigure(encoding='utf-8', errors='replace') - else: - sys.stdout = codecs.getwriter('utf-8')(sys.stdout.detach(), errors='replace') - sys.stderr = codecs.getwriter('utf-8')(sys.stderr.detach(), errors='replace') ``` **2. 실행 스크립트 (run_utf8.bat)** @@ -38,36 +160,171 @@ if sys.platform.startswith('win'): chcp 65001 >nul 2>&1 set PYTHONIOENCODING=utf-8 set PYTHONUTF8=1 -python -X utf8 main.py +set LC_ALL=C.UTF-8 +python main.py pause ``` **3. 코딩 규칙** -- ❌ 이모지 사용 금지: `🚀✅❌💡📊⚠️` -- ✅ 텍스트 라벨 사용: `[START][SUCCESS][ERROR][TIP][STATS][WARNING]` +- 텍스트 라벨 사용: `[SUCCESS]`, `[ERROR]`, `[WARNING]` - 파일 I/O 시 `encoding='utf-8'` 필수 명시 +- 모든 문자열 처리에 `ensure_unicode_string()` 함수 활용 -**4. 긴급 해결** +## 테스트 + +### 기본 테스트 실행 ```bash -chcp 65001 -set PYTHONIOENCODING=utf-8 -set PYTHONUTF8=1 -python -X utf8 your_script.py +python test_main.py ``` -### 체크리스트 -- [ ] Python 파일 상단에 UTF-8 설정 추가 -- [ ] 이모지를 텍스트로 교체 -- [ ] run_utf8.bat 스크립트 생성 -- [ ] Windows에서 테스트 실행 +### 단위 테스트 +```bash +# 커넥터 테스트 +pytest tests/test_connector.py + +# 서버 테스트 +pytest tests/test_server.py + +# 전체 테스트 +pytest tests/ +``` + +## 개발 가이드 + +### 1. 새로운 도구 추가 + +**models.py에 도구 정의 추가:** +```python +@staticmethod +def get_new_tool() -> Tool: + return Tool( + name="new_tool", + description="새로운 도구 설명", + inputSchema={ + "type": "object", + "properties": { + "param": {"type": "string", "description": "매개변수"} + }, + "required": ["param"] + } + ) +``` + +**handlers.py에 핸들러 구현:** +```python +async def handle_new_tool(self, args: Dict[str, Any]) -> List[TextContent]: + param = args.get("param") + # 도구 로직 구현 + return [TextContent(type="text", text="결과")] +``` + +### 2. 에러 처리 패턴 + +```python +from src.utils.error_recovery import with_retry, RetryConfig +from src.connector.imagen4_client import classify_api_error + +@with_retry(RetryConfig(max_attempts=3)) +async def api_call(): + try: + result = await some_api_call() + return result + except Exception as e: + error_type, message = classify_api_error(e) + logger.error(f"API Error [{error_type.value}]: {message}") + raise +``` + +### 3. 로깅 설정 + +```python +import logging +from src.connector.imagen4_client import ensure_unicode_string + +logger = logging.getLogger(__name__) + +# 안전한 유니코드 로깅 +prompt = ensure_unicode_string(user_input) +logger.info(f"Processing prompt: {prompt}") +``` + +## 주요 클래스 및 함수 + +### src.connector.imagen4_client +- `Imagen4Client`: Google API 클라이언트 메인 클래스 +- `classify_api_error()`: API 오류 분류 및 처리 +- `ensure_unicode_string()`: UTF-8 문자열 안전 변환 + +### src.server.handlers +- `ToolHandlers`: MCP 도구 핸들러 컬렉션 +- `sanitize_args_for_logging()`: 로깅용 인수 정리 + +### src.async_task.task_manager +- `TaskManager`: 비동기 작업 관리 (최대 10분 타임아웃) +- `WorkerPool`: 멀티 워커 지원 + +### src.utils.image_utils +- `create_preview_image_b64()`: JPEG 미리보기 생성 +- `get_image_info()`: 이미지 메타데이터 추출 + +## 문제 해결 + +### 일반적인 오류 + +**1. Google Cloud 인증 오류** +```bash +# 서비스 계정 키 경로 확인 +echo $GOOGLE_APPLICATION_CREDENTIALS +# 프로젝트 ID 확인 +echo $PROJECT_ID +# Imagen API 활성화 확인 +``` + +**2. 메모리 부족** +- 이미지 생성 개수를 1개로 제한 +- 시스템 메모리 8GB 이상 권장 + +**3. 한글 로깅 깨짐** +```bash +# run_utf8.bat 사용 또는 +chcp 65001 +set PYTHONIOENCODING=utf-8 +python main.py +``` + +**4. MCP 연결 실패** +- Claude Desktop 재시작 +- `claude_desktop_config.json` 경로 확인 +- 서버 로그에서 오류 메시지 확인 + +### 로그 모니터링 + +서버 실행 시 상세 로그가 출력됩니다: +``` +[UTF8-TEST] Test UTF-8: 한글 테스트 ✓ +INFO - Imagen4 MCP Server starting... +INFO - Starting image generation: '아름다운 풍경...', Seed: 123456 +INFO - Image generated successfully +``` + +## 성능 및 제한사항 + +### API 제한 +- Google Imagen4 API 할당량 준수 +- 동시 요청 수 제한 (워커 풀 관리) +- 이미지 크기: 최대 2048x2048 + +### 메모리 사용 +- PNG 원본: 8-15MB per image +- JPEG 미리보기: 50-200KB per image +- 메타데이터: <1KB per image + +### 타임아웃 +- 이미지 생성: 360초 (6분) +- 백그라운드 작업: 600초 (10분) --- -## 📝 추가 가이드 작성 예정 -- API 연동 가이드 -- 로깅 설정 가이드 -- 배포 및 운영 가이드 -- 에러 처리 가이드 - ---- -*마지막 업데이트: 2024년 8월 24일* +**마지막 업데이트:** 2025년 8월 25일 +**프로젝트 버전:** 현재 안정 버전 사용 중 +**지원:** 한글 프롬프트 완벽 지원, Windows/Linux/Mac 크로스 플랫폼