snowflake-mcp-lambda

Data Chat MVP

一个 Web 应用，让非技术用户能够上传 CSV 文件，并通过聊天界面使用自然语言查询数据。

📊 项目状态

当前阶段：CSV 上传 MVP 实施

✅ 已完成（后端基础架构完成 85%）

• P0 - 基础：Git 仓库、pre-commit hooks、CI 流水线、Docker 设置 ✅
• P1 - 后端核心：FastAPI 应用、配置管理、数据库基础、健康检查端点 ✅
• P2 - 身份验证与会话：完整的 Google OAuth 集成与用户管理 ✅
  • 包含偏好设置的 User SQLAlchemy 模型
  • 基于 JWT 的会话管理
  • 身份验证端点（登录、回调、登出、个人资料、偏好设置）
  • 103 项测试，覆盖率为 89.73%
• P3 - 数据集成：LLM 流水线和数据处理基础设施 ✅
  • Gemini API 服务，支持 BYOK 模式和提示词工程
  • Schema 服务已准备好处理从 CSV 上传的数据，并使用 SQLite
  • 支持自动运行的自然语言转 SQL 聊天端点
  • SQL 验证和注入防护
  • 新组件有 55 项测试，覆盖率超过 95%
• P4 - 前端身份验证：完整的身份验证流程 ✅
  • 集成 Google OAuth 的 React 应用
  • 受保护的路由和用户上下文
  • 已准备好用于数据组件的仪表板布局

🎯 下一优先事项：CSV 上传 MVP（Prompt 11）

• 后端：CSV 上传端点、文件处理、转换为 SQLite
• 前端：文件上传组件、Schema 预览、聊天界面集成
• 集成：完成上传 → 查询 → 结果流程

🔮 未来功能（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. Schema 预览 - 自动检测列和数据类型，并提供确认
3. 聊天界面 - 使用自然语言询问有关数据的问题
4. 生成 SQL - Gemini LLM 将问题转换为 SQLite 查询
5. 显示结果 - 支持排序、筛选和导出的交互式表格

🔒 安全与隐私

• 不持久化数据 - 会话结束后删除文件
• 只读查询 - 仅允许 SELECT 语句
• 用户提供 API 密钥 - Gemini API 密钥不会存储在服务器端
• 文件验证 - 限制文件大小、验证格式并安全处理

⚡ 性能

• 快速上传 - 支持最大 100MB 的文件
• 高效处理 - CSV → SQLite 转换并推断 Schema
• 快速查询 - 使用内存中的 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 Client 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
• 数据处理：使用 pandas + SQLite 处理 CSV 文件
• 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 - 使用严格模式进行类型检查
• 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，形成令人沮丧的调试循环。我们的解决方案：

• 即时反馈 - AI 可立即获取错误，而不必等待 CI 失败
• 相同环境 - 本地通过的检查，在 CI 中也能通过
• 更快迭代 - 在同一轮对话中修复问题
• 无需切换上下文 - AI 无需人工介入即可解决问题

面向 AI 助手的友好特性

• 清晰的文档 - docs/planning/ 中包含全面的规划文档
• 可直接执行的提示词 - PROJECT_STATUS.md 中列出了具体的实施任务
• 模块化架构 - 清晰划分关注点，便于有针对性地修改
• 全面的测试 - 确保修改不会破坏现有功能

这种方法能让 AI 助手从虽有帮助但有时令人沮丧的伙伴，转变为真正可靠的开发伙伴。

---

通过自然语言对话，将 CSV 数据转化为洞见。无需设置数据库——只需上传文件，即可开始提问！