card/docs/MCP_INTEGRATION_SUMMARY.md

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非同期処理)

最終的な依存関係:

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. 仮想環境構築

cd /Users/syui/ai/gpt/card
./setup_venv.sh

2. データベース初期化

cd api
~/.config/syui/ai/card/venv/bin/python init_db.py

3. サーバー起動

./start_server.sh
# または
cd api
~/.config/syui/ai/card/venv/bin/python -m app.main

4. 動作確認

# ヘルスチェック
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開発環境

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