merge aigpt

docs/MCP_INTEGRATION_SUMMARY.md

@@ -0,0 +1,129 @@
+# ai.card MCP Server統合作業報告 (2025/01/06)
+
+## 作業概要
+ai.cardプロジェクトに独立したMCPサーバーを実装し、FastAPIベースのカードゲームAPIをMCPツールとして公開。
+
+## 実装内容
+
+### 1. 依存関係の解決
+**課題と対応:**
+- `atproto==0.0.46` → `atproto>=0.0.55` (Python 3.13対応)
+- `httpx` バージョン競合 → supabase一時無効化
+- `pydantic==2.5.0` → `pydantic>=2.7.0` (atproto要件)
+- PostgreSQL依存 → SQLiteベースに変更
+- `greenlet` 追加 (SQLAlchemy非同期処理)
+
+**最終的な依存関係:**
+```txt
+fastapi>=0.104.1
+uvicorn[standard]>=0.24.0
+pydantic>=2.7.0,<3.0.0
+sqlalchemy>=2.0.23
+greenlet>=3.0.0
+aiosqlite>=0.19.0
+fastapi-mcp==0.1.0
+atproto>=0.0.55
+# supabase>=2.3.0  # httpx競合のため無効化
+# asyncpg, psycopg2-binary  # コンパイル回避のため無効化
+```
+
+### 2. MCP Server実装
+**ファイル:** `api/app/mcp_server.py`
+
+**主要変更:**
+- `from mcp.server.fastmcp import FastMCP` (正しいインポート)
+- `FastMCP("aicard")` で初期化
+- 9個のMCPツール実装
+
+**公開ツール:**
+1. `get_user_cards` - ユーザーカード一覧
+2. `draw_card` - ガチャ実行  
+3. `get_card_details` - カード詳細情報
+4. `analyze_card_collection` - コレクション分析
+5. `get_unique_registry` - ユニークカード登録状況
+6. `sync_cards_atproto` - atproto同期（無効化中）
+7. `get_gacha_stats` - ガチャ統計
+
+### 3. データベース設定
+**SQLite使用:**
+- 場所: `~/.config/syui/ai/card/aicard.db`
+- 理由: 依存関係シンプル化、開発環境最適化
+- PostgreSQL移行: 将来的にDocker利用で対応
+
+### 4. 補助スクリプト
+- `setup_venv.sh` - 仮想環境セットアップ
+- `start_server.sh` - サーバー起動スクリプト
+- `docker-compose.dev.yml` - PostgreSQL開発環境
+
+## 既知の問題と対応
+
+### 解決済み
+- ✅ fastapi-mcp インポートエラー → 正しいパッケージ名に修正
+- ✅ get_db → get_session 関数名不一致
+- ✅ Optional型インポート漏れ
+- ✅ SQLAlchemy greenlet依存
+- ✅ データベース初期化エラー
+
+### 未解決（将来対応）
+- atproto SessionString APIの変更
+- supabase httpxバージョン競合
+- ガチャ確率計算の精度問題
+
+## 環境セットアップ手順
+
+### 1. 仮想環境構築
+```bash
+cd /Users/syui/ai/gpt/card
+./setup_venv.sh
+```
+
+### 2. データベース初期化
+```bash
+cd api
+~/.config/syui/ai/card/venv/bin/python init_db.py
+```
+
+### 3. サーバー起動
+```bash
+./start_server.sh
+# または
+cd api
+~/.config/syui/ai/card/venv/bin/python -m app.main
+```
+
+### 4. 動作確認
+```bash
+# ヘルスチェック
+curl http://localhost:8000/health
+
+# API仕様書
+open http://localhost:8000/docs
+
+# カード取得テスト
+curl -X POST "http://localhost:8000/draw_card?did=did:plc:test123"
+```
+
+## PostgreSQL移行（将来）
+
+### Docker開発環境
+```bash
+# PostgreSQLのみ起動
+docker-compose -f docker-compose.dev.yml up -d
+
+# 環境変数設定
+export DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/aicard"
+
+# APIサーバー起動
+./start_server.sh
+```
+
+### 本番環境
+- iOS/Webアプリ → PostgreSQL必須
+- Docker Composeで全サービス管理
+- Cloudflare Tunnel経由で公開
+
+## 成果
+- ai.card独立MCPサーバー稼働
+- SQLiteベースで依存関係問題解決
+- 自動リロード対応の開発環境構築
+- iOS/Web連携準備完了