# 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連携準備完了