snowflake-mcp-lambda

Data Chat MVP

技術的な知識がないユーザーがCSVファイルをアップロードし、チャットインターフェースを通じて自然言語でクエリを実行できるウェブアプリケーションです。

📊 プロジェクトの状況

現在のフェーズ：CSV アップロード MVP の実装

✅ 完了済み（バックエンド基盤の85%）

• P0 - 基盤：Git リポジトリ、pre-commit フック、CI パイプライン、Docker セットアップ ✅
• P1 - バックエンドのコア：FastAPI アプリ、設定管理、データベース基盤、ヘルスエンドポイント ✅
• P2 - 認証とセッション：ユーザー管理を含む Google OAuth の完全な統合 ✅
  • 設定を含む User SQLAlchemy モデル
  • JWT ベースのセッション管理
  • 認証エンドポイント（ログイン、コールバック、ログアウト、プロフィール、設定）
  • カバレッジ89.73%のテスト103件
• P3 - データ統合：LLM パイプラインとデータ処理インフラストラクチャ ✅
  • BYOK モデルとプロンプトエンジニアリングを備えた Gemini API サービス
  • CSV アップロードからの SQLite データに対応した Schema サービス
  • autorun に対応した NL→SQL 変換用チャットエンドポイント
  • SQL の検証とインジェクション防止
  • 新しいコンポーネントを対象としたカバレッジ95%以上のテスト55件
• P4 - フロントエンド認証：認証フロー全体 ✅
  • Google OAuth 統合を備えた React アプリ
  • 保護されたルートとユーザーコンテキスト
  • データコンポーネントに対応したダッシュボードのレイアウト

🎯 次の優先事項：CSV アップロード MVP（Prompt 11）

• バックエンド：CSV アップロードエンドポイント、ファイル処理、SQLite への変換
• フロントエンド：ファイルアップロードコンポーネント、スキーマプレビュー、チャットインターフェースとの統合
• 統合：アップロード → クエリ → 結果の一連のフロー

🔮 今後の機能（MVP 後）

• 複数のファイル形式：Excel、JSON、Parquet に対応
• データベース接続：PostgreSQL、MySQL、Snowflake との統合
• 高度な機能：クエリ履歴、お気に入り、データの可視化
• エンタープライズ：SSO、RBAC、コラボレーション機能

🚀 Docker ですぐに始める（推奨）

開発を最速で始める方法：

# 1. Clone and setup environment
git clone <your-repo-url>
cd snowflake-mcp-lambda
make setup  # Copies .env.example to .env

# 2. IMPORTANT: Edit .env with required values
# Required: GEMINI_API_KEY (for LLM functionality)
# Optional: GOOGLE_CLIENT_* (for auth), database passwords

# 3. Start everything with one command
make dev-setup
# This builds containers, starts services, and runs migrations

# 4. Access the application
# - Frontend: http://localhost:3000 (React app)
# - Backend API: http://localhost:8000 (FastAPI)
# - API Docs: http://localhost:8000/docs (Interactive API docs)

よく使う開発コマンド：

make help           # Show all available commands
make up             # Start services
make down           # Stop services
make logs           # View all logs
make test           # Run backend tests
make health         # Check service health
make wait-healthy   # Wait for all services to be ready
make clean          # Clean up containers/volumes

💡 主な機能

🎯 MVP のユーザーエクスペリエンス

1. CSV ファイルをアップロード - 進捗表示に対応したドラッグ＆ドロップインターフェース
2. スキーマプレビュー - 自動検出した列とデータ型を確認
3. チャットインターフェース - データについて自然言語で質問
4. SQL の生成 - Gemini LLM が質問を SQLite クエリに変換
5. 結果の表示 - 並べ替え、フィルタリング、エクスポートの各オプションを備えたインタラクティブなテーブル

🔒 セキュリティとプライバシー

• データを永続化しない - セッション終了後にファイルを削除
• 読み取り専用クエリ - SELECT 文のみ許可
• ユーザー提供の API キー - Gemini API キーはサーバー側に保存されません
• ファイルの検証 - サイズ制限、形式の検証、安全な処理

⚡ パフォーマンス

• 高速アップロード - 最大100MBのファイルに対応
• 効率的な処理 - スキーマ推論を用いてCSVをSQLiteに変換
• 高速なクエリ - インメモリ SQLite による高速なクエリ実行
• セッションベース - コア機能にデータベースへの依存なし

⚙️ 設定

必要な API キー

Gemini API（LLM 機能に必要）

1. Google AI Studio にアクセスします
2. 新しい API キーを作成します
3. .env ファイルに追加します：GEMINI_API_KEY=your-api-key

Google OAuth（MVP では任意）

1. Google Cloud Console にアクセスします
2. OAuth 2.0 クライアント ID の認証情報を作成します
3. リダイレクト URI を追加します：http://localhost:8000/api/v1/auth/callback
4. .env に GOOGLE_CLIENT_ID と GOOGLE_CLIENT_SECRET を追加します

環境変数

.env.example を .env にコピーし、値を入力します：

# Required for core functionality
GEMINI_API_KEY=your-gemini-api-key

# Optional for authentication (can use without login)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Auto-generated secure secrets
JWT_SECRET_KEY=your-secure-secret-key
POSTGRES_PASSWORD=your-db-password

🏗️ アーキテクチャ

技術スタック

• バックエンド：FastAPI（Python）+ 依存関係管理用の Poetry
• フロントエンド：React + Vite + TypeScript + Tailwind CSS
• データ処理：CSV ファイル処理用の pandas + SQLite
• LLM 統合：自然言語クエリ用の Google Gemini API
• 認証：JWT Cookie を使用した Google OAuth（任意）
• 開発：ローカル開発用の Docker Compose

ファイル処理パイプライン

CSV Upload → Schema Detection → SQLite Conversion → Query Interface
     ↓              ↓                   ↓               ↓
File validation  Column types    In-memory DB    Natural language
Size limits      Data preview    Fast queries    SQL generation
Error handling   User confirm    Session scope   Results display

🧪 テストと開発

コミット前の品質チェック

コミット前のフックでは、すぐにフィードバックを得られるよう、CI と同じチェックを実行します。

• Ruff - 高速な Python のリンティングとフォーマット
• MyPy - strict モードによる型チェック
• Pytest - カバレッジ 85% 以上を要件とする全テストスイート
• セキュリティ - 基本的な脆弱性スキャン

# Setup development environment
./scripts/setup-dev.sh

# All commits now run full CI checks locally
# (30-60 seconds per commit, but zero CI failures)

テストカバレッジ

• バックエンド：包括的な単体テストと統合テストにより、カバレッジ 91% 以上
• フロントエンド：vitest によるコンポーネントテストと、cypress による E2E テスト
• ファイル処理：さまざまな CSV 形式とエンコーディングのエッジケース
• LLM 連携：信頼性の高いテストを実現する Gemini レスポンスのモック

📋 開発状況

実装の進捗

詳細な状況と次のステップについては、docs/planning/PROJECT_STATUS.md を参照してください

開発者と AI アシスタント向けの主要なファイル：

• docs/planning/PROJECT_STATUS.md - 現在の状況とすぐに実行できるプロンプト
• docs/planning/spec_v2.md - 機能要件とアーキテクチャの全容
• DEVELOPMENT.md - 開発環境のセットアップとトラブルシューティングのガイド
• CLAUDE.md - AI コーディングアシスタント向けのプロジェクトコンテキスト

現在の優先事項：CSV アップロード MVP

次の主要なマイルストーンは、以下を可能にする CSV ファイルのアップロード機能の実装です。

1. データベースの認証情報なしで CSV ファイルをアップロードする
2. 検出されたスキーマをプレビューして検証する
3. チャットを通じて自然言語でアップロードしたデータをクエリする
4. 結果をエクスポートし、セッションデータを管理する

これにより、ユーザーが提供するファイルだけで完全に動作する、デモ対応のアプリケーションが完成します。

🤖 AI 支援開発に関するメモ

このプロジェクトは、AI 支援開発をシームレスに行えるよう設計されています。

包括的なコミット前フックを導入する理由

AI アシスタントは CI のログに直接アクセスできません。CI が失敗すると、人間がエラーメッセージを手動で AI にコピーして戻す必要があり、デバッグのやり取りが煩雑になります。この問題を次の方法で解決します。

• 即時フィードバック - CI の失敗後ではなく、AI がすぐにエラーを把握できます
• 同じ環境 - ローカルで通るチェックは CI でも通ります
• 迅速な反復 - 同じ会話の中で問題を修正できます
• コンテキストの切り替え不要 - 人間の介入なしに AI が問題を解決できます

AI アシスタントに便利な機能

• 分かりやすいドキュメント - docs/planning/ に包括的な計画ドキュメントがあります
• すぐに実行できるプロンプト - PROJECT_STATUS.md に具体的な実装タスクがあります
• モジュール型アーキテクチャ - 変更に集中できる、明確な関心事の分離
• 包括的なテスト - 変更によって既存の機能が壊れないという安心感が得られます

このアプローチにより、AI アシスタントは便利でありながら、ときに扱いづらい存在から、真に信頼できる開発パートナーへと変わります。

---

自然言語で会話しながら、CSV データからインサイトを引き出しましょう。データベースのセットアップは不要です。アップロードして、質問するだけです！