DEVELOPMENT_LOG.md

# ImageGenMCP 開発ログ

## プロジェクト概要
- **目的**: ClaudeCode用の画像生成MCPサーバー
- **技術スタック**: Gradio 5.31.0, Gemini 2.0 Flash Preview, FastAPI
- **デプロイ先**: Hugging Face Spaces

## 開発マイルストーン

### 2025-06-01 - プロジェクト初期化と基本実装

#### 完了項目
1. **プロジェクト構造の確立**
   - `app.py` - メインアプリケーション
   - `requirements.txt` - 依存関係
   - `README.md` - Hugging Face Spaces仕様準拠
   - `.gitignore` - Git設定
   - `app.yaml` - HF Spaces設定
   - `mcp_client.py` - MCPクライアントサンプル

2. **Gemini 2.0 Flash統合**
   - モデル名: `gemini-2.0-flash-preview-image-generation`
   - 画像生成機能の実装
   - 参考画像サポート
   - エラーハンドリングとログ出力

3. **UI崩れ問題の解決**
   - **問題**: FastAPIとGradioの統合でUI崩れが発生
   - **試行錯誤**:
     - FastAPI root_path設定
     - gr.mount_gradio_app()の使用
     - パスマウント最適化
   - **最終解決策**: Gradioの内部FastAPIアプリに直接ルートを追加するシンプルな構成

#### 技術的な学び
- Hugging Face SpacesでのFastAPI/Gradio統合は複雑になりがち
- Gradio 5.31.0は内部でFastAPIを使用しており、`demo.app`でアクセス可能
- `demo.queue()`と`demo.launch()`のシンプルな構成が最も安定

#### 現在のステータス
- ✅ 基本的なUI表示が正常動作
- ✅ 画像生成機能の実装完了
- ✅ MCPエンドポイントの定義完了
- ⏳ 実際の画像生成テスト待ち
- ⏳ MCPエンドポイントの動作確認待ち

## APIエンドポイント仕様

### MCPエンドポイント
- `POST /api/mcp/list_tools` - ツール一覧取得
- `POST /api/mcp/call_tool` - 画像生成実行
- `GET /api/health` - ヘルスチェック

### リクエスト/レスポンス形式
```json
// リクエスト (call_tool)
{
    "name": "generate_image",
    "arguments": {
        "prompt": "生成したい画像の説明"
    }
}

// レスポンス
{
    "success": true,
    "message": "画像生成に成功しました！",
    "image_base64": "base64エンコードされた画像データ"
}
```

## 次のステップ
1. 画像生成機能の実地テスト
2. MCPエンドポイントの動作確認
3. ClaudeCodeからの統合テスト
4. パフォーマンス最適化
5. エラーハンドリングの強化

## 既知の問題と対策

### 1. Gemini API レスポンスモダリティエラー (解決済み)
- **問題**: `response_modalities=["IMAGE"]`のみだとエラー
- **原因**: モデルは`IMAGE`と`TEXT`の両方を要求
- **解決**: `response_modalities=["IMAGE", "TEXT"]`に変更

### 2. 画像生成の不安定性 (部分的解決)
- **症状**: 1回目は成功するが、2回目以降は画像データが含まれない
- **対策実施**: 
  - レスポンスのパーツを全て検査するように改善
  - テキストコンテンツも収集してエラー理由を把握
  - システムインストラクションを追加して画像生成を強制
- **推測される原因**:
  - レート制限
  - コンテンツフィルタリング
  - プロンプトの内容による拒否

### 3. MCPエンドポイント認識問題 (調査中)
- **症状**: `/api/health`, `/api/mcp/*`エンドポイントがGradio UIを返す
- **原因**: Gradio 5.31.0内部FastAPIでのルート追加が正しく動作していない
- **対策検討**:
  - FastAPIとGradioを完全分離
  - プロキシ型アーキテクチャ
  - Gradio External APIの利用

## 環境設定メモ
- Hugging Face Spaces Secrets:
  - `GEMINI_API_KEY` - Gemini APIキー（必須）

## トラブルシューティング記録
1. **UI崩れ問題** (解決済み)
   - 症状: 画像アイコンのみ表示、UIコンポーネントが表示されない
   - 原因: FastAPIとGradioのパス競合
   - 解決: シンプルな統合方式に変更

---
最終更新: 2025-06-01