AI导哈

数据库查询助手

一个将自然语言转换为SQL查询的AI驱动数据库智能平台，具备自动化报告和邮件发送功能。

  • by Michdriod
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Michdriod/mcp-server-client

使用说明

QueryAI-智能数据库查询助手

🚀 企业级AI驱动的数据库查询平台 它通过自动报告和电子邮件传递将自然语言转换为SQL查询。内置于 Pydantic AI, FastMCP, 反应，以及 PostgreSQL 用于生产就绪的数据库智能。

🎯 我们建造了什么

查询ai 是我们从头开始成功开发的一个完整的人工智能数据库智能平台：

🎨 现代React前端

  • 美观、响应迅速的用户界面 使用React+Vite+Tailwind CSS构建
  • 交互式仪表板 具有实时分析和图表功能
  • 查询生成器界面 具有语法高亮显示和自动补全功能
  • 计划报告管理 使用可视化cron表达式生成器
  • 电子邮件配置 用于自动报告交付

🤖 AI驱动的后端引擎

  • 自然语言处理 -用简单的英语提问，得到SQL结果
  • 17 MCP工具 -使用FastMCP的完整模型上下文协议服务器
  • 智能查询生成 -由Groq的Llama 3.3 70B型号提供动力
  • 电子邮件自动化 -Gmail SMTP与HTML模板和CSV附件的集成
  • 高级缓存 -多层Redis缓存，响应时间低于秒

🔐 企业安全与合规

  • 基于角色的访问控制 -细粒度权限（表、列、行级别）
  • SQL注入保护 -高级查询验证和清理
  • 审计日志 -完整的查询历史和用户活动跟踪
  • 数据隐私 -安全处理敏感数据库信息

📊 高级分析和报告

  • 自动生成图表 -使用Chart.js实现动态可视化
  • 计划的报告 -基于Cron的电子邮件交付自动化
  • 多格式导出 -CSV、Excel、PDF和JSON导出功能
  • 性能监控 -查询执行指标和优化见解

🚀 生产就绪基础设施

  • 横向可扩展 -连接池，负载平衡就绪
  • Docker容器化 -使用docker compose进行多阶段构建
  • 健康监测 -全面的健康检查和Prometheus指标
  • 错误处理 -强大的错误处理和详细的日志记录

🏗️ 系统架构

查询ai 实现了一个专为企业工作负载设计的现代、可扩展的架构：

🌐 React Frontend (Port 8081)
         ↓ REST API
🔄 FastAPI Server (Port 8000)  
         ↓ MCP Protocol
🤖 AI Engine (Pydantic AI + Groq)
         ↓ FastMCP Server
📊 17 MCP Tools (Query, Export, Schedule, Analytics)
         ↓
🗄️  PostgreSQL Database + ⚡ Redis Cache
         ↓
📧 Email Service (Gmail SMTP) + 📅 Cron Scheduler

🔧 技术栈

  • 前端：React 18、Vite、顺风CSS、Chart.js、Axios
  • 后端：FastAPI、FastMCP、Pydantic AI、SQLAlchemy、AsyncPG
  • AI/ML：Groq API（Llama 3.3 70B），自然语言处理
  • 数据库：PostgreSQL 14+，带异步连接池
  • 缓存：Redis 6+采用多层缓存策略
  • 电子邮件：带有HTML模板和文件附件的Gmail SMTP
  • 调度：基于Cron的任务调度和下一次运行计算
  • 部署：Docker、Docker Compose、NGINX负载均衡器

📁 项目结构

查询ai 遵循干净、模块化的架构，明确分离关注点：

QueryAI/
├── 🎨 frontend/               # React Frontend Application
│   ├── src/
│   │   ├── components/        # Reusable UI components
│   │   ├── pages/            # Main application pages
│   │   ├── services/         # API integration layer
│   │   ├── hooks/            # Custom React hooks
│   │   └── utils/            # Helper functions
│   ├── package.json          # Frontend dependencies
│   └── vite.config.js        # Vite build configuration
│
├── 🚀 server/                # Backend API & MCP Server
│   ├── db/                   # Database layer (SQLAlchemy async)
│   │   ├── models.py         # Database models with timezone fixes
│   │   └── connection.py     # Async connection pooling
│   ├── cache/               # Redis caching system
│   ├── auth/                # RBAC & security layer
│   ├── query/               # AI query processing
│   │   ├── query_executor.py # SQL execution engine
│   │   └── validator.py     # SQL validation & security
│   ├── tools/               # Data processing tools
│   │   ├── exporters.py     # Multi-format export (CSV, Excel, PDF)
│   │   ├── chart_generator.py # Dynamic chart generation
│   │   └── history.py       # Query history management
│   ├── scheduler/           # Email & scheduling system
│   │   ├── email_sender.py  # Gmail SMTP integration
│   │   └── report_scheduler.py # Cron-based scheduling
│   ├── monitoring/          # Health checks & logging
│   │   ├── health.py        # System health endpoints
│   │   └── logging.py       # Structured logging
│   ├── api_server.py        # FastAPI REST server
│   └── mcp_server.py        # FastMCP server (17 tools)
│
├── 🔧 client/               # Client interfaces & examples
│   ├── mcp_client.py        # Python API wrapper
│   ├── cli.py               # Rich CLI interface
│   └── examples/            # Complete usage examples
│
├── 🔗 shared/               # Shared configuration
│   └── config.py            # Environment & email config
│
├── 📋 Documentation
│   ├── CLIENT_GUIDE.md      # Comprehensive API docs
│   └── README.md            # This file
│
└── ⚙️ Configuration
    ├── .env                 # Environment variables
    ├── pyproject.toml       # Python dependencies
    ├── package.json         # Project metadata
    └── start_api.sh         # Server startup script

🚀 快速入门指南

获取 查询ai 通过我们简化的设置流程，在几分钟内即可启动并运行：

1.📋 先决条件

确保您的系统上安装了以下内容：

  • Python 3.12+ -最新Python实现最佳性能
  • Node.js 18+ -React前端需要
  • PostgreSQL 14+ -您的数据库引擎
  • Redis 6+ -用于闪电般快速的缓存
  • Groq API密钥 -免费访问 console.groq.com
  • Gmail应用密码 -用于电子邮件功能（可选）

2.⚡ 安装

用3个简单的命令克隆和设置QueryAI：

# 📥 Clone the repository
git clone https://github.com/Michdriod/mcp-server-client.git
cd mcp-server-client

# 🐍 Set up Python environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

# 📦 Install frontend dependencies
cd frontend
npm install
cd ..

3.🔧 配置

创建环境配置文件：

# 📝 Create .env file with your settings
cat > .env << EOF
# 🗄️ Database Configuration
DATABASE_URL=postgresql+asyncpg://postgres:michwaleh@localhost/Mcp
DATABASE_POOL_SIZE=20
DATABASE_MAX_OVERFLOW=40

# ⚡ Redis Configuration
REDIS_URL=redis://localhost:6379/0
REDIS_MAX_CONNECTIONS=50

# 🤖 AI Configuration
GROQ_API_KEY=your_groq_api_key_here
LLM_MODEL=groq:llama-3.3-70b-versatile

# 📧 Email Configuration (Optional - for scheduled reports)
EMAIL_FROM_NAME=Database Query Assistant
EMAIL_FROM_ADDRESS=your-email@gmail.com
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=true
EMAIL_USERNAME=your-email@gmail.com
EMAIL_PASSWORD=your-gmail-app-password
EOF

⚠️ 重要提示：

  • 替换 your_groq_api_key_here 使用您的实际Groq API密钥
  • 对于电子邮件功能，请使用Gmail应用程序密码（而不是常规密码）
  • 更新数据库凭据以匹配您的PostgreSQL设置

4.数据库设置

# Run the provided SQL script in pgAdmin or psql
# Creates 11 tables with sample data

5.🎬 启动QueryAI

以正确的顺序启动所有组件以获得最佳性能：

🔴 终端1：Redis服务器

redis-server

实现闪电般快速的查询缓存和会话管理

🟠 终端2：后端API服务器

chmod +x start_api.sh
./start_api.sh

✅ 成功指标：

🚀 Starting Database Query Assistant API Server...
✅ Environment variables loaded
✅ Redis is running - caching enabled
✅ MCP client connected and ready
INFO: Uvicorn running on http://0.0.0.0:8000

🟢 终端3：反应前端

cd frontend
npm run dev

✅ 成功指标：

VITE v5.4.21  ready in 234 ms
➜  Local:   http://localhost:8081/
➜  Network: use --host to expose

🎉 访问您的QueryAI仪表板

打开浏览器并导航到：

🎯 你会看到什么

QueryAI仪表板功能：

  • 📊 分析仪表盘 -实时数据库洞察和指标
  • 🔍 查询接口 -自然语言到SQL的转换器
  • 📅 计划的报告 -设置自动电子邮件报告
  • 💾 保存的查询 -管理您最喜欢的查询
  • 📈 查询历史 -跟踪所有数据库交互
  • ⚙️ 设置 -配置电子邮件和系统首选项

🛠️ 替代访问方法

CLI界面：

# Quick query
python client/cli.py query "Show me the top 5 customers"

# Interactive mode
python client/cli.py interactive

Python API：

# Run example script
python client/examples/basic_query.py

🏗️ 发展历程

查询ai 是通过多个阶段的系统化迭代开发过程构建的：

✅ 第一阶段：基础和建筑 （完成）

  • 🏗️ 项目结构：干净、模块化的架构，关注点明确分离
  • 🗄️ 数据库层：SQLAlchemy异步ORM，带连接池
  • ⚡ 缓存层：Redis多层缓存，响应时间低于秒
  • 🔐 安全模块：RBAC、SQL注入保护、查询验证
  • 📊 数据库模式：11个具有优化索引和关系的表

✅ 第二阶段：人工智能驱动的查询引擎 （完成）

  • 🤖 FastMCP服务器：17个用于数据库操作的智能工具
  • 🧠 人工智能集成：Pydantic AI+Groq LLM用于自然语言处理
  • ⚡ 查询执行：高级超时处理、分页和结果优化
  • 📈 图表生成：与Chart.js集成的动态可视化
  • 📝 查询管理：历史跟踪、保存/加载功能
  • 🔍 智能搜索：语义查询匹配和建议

✅ 第3阶段：电子邮件自动化和日程安排 （完成）

  • 📧 Gmail SMTP集成：带附件的专业HTML电子邮件模板
  • ⏰ Cron调度：智能cron表达式解析和下次运行计算
  • 📊 多格式导出：CSV、Excel、PDF、JSON，可定制模板
  • 🎯 电子邮件调试：全面的日志记录和错误处理
  • 🔄 报表自动化：自动生成和交付报告
  • ✅ 状态跟踪：实时电子邮件发送确认

✅ 第四阶段：现代React前端 （完成）

  • 🎨 漂亮的UI：React 18+Vite+顺风CSS响应式设计
  • 📊 交互式仪表板：使用Chart.js可视化进行实时分析
  • 🔍 查询生成器：具有语法高亮显示的高级查询界面
  • 📅 日程管理器：可视化cron表达式生成器和报表管理
  • 💾 查询库：保存了带有搜索和分类的查询
  • ⚙️ 配置面板：电子邮件设置和系统首选项

✅ 第5阶段：客户端接口和API （完成）

  • 🐍 Python API客户端：适用于所有17个MCP工具的完全异步API包装器
  • 🖥️ 丰富的CLI：漂亮的命令行界面，有9个命令
  • 📚 示例脚本：5个完整的使用示例和教程
  • 📖 文档：全面的API参考资料和客户指南
  • 🔧 开发者工具：测试实用程序和调试助手

✅ 第6阶段：生产准备 （完成）

  • 🐳 Docker支持：使用docker compose编排的多阶段构建
  • ⚖️ 负载均衡：具有速率限制的NGINX配置
  • 📊 监控：健康检查、结构化日志记录、Prometheus指标
  • 🛡️ 安全：生产就绪的安全强化和最佳实践
  • 🚀 部署：自动化部署脚本和CI/CD管道
  • 🔧 维护：数据库迁移、备份策略和恢复过程

客户端接口

2.CLI（丰富）

用于高级用户和自动化的命令行界面。

# Query database
python client/cli.py query "Show top 5 customers"

# Interactive mode
python client/cli.py interactive

# Export data
python client/cli.py export "Show all customers" --format excel

# Manage schedules
python client/cli.py schedule list
python client/cli.py schedule create --name "Daily Report" --query "..." --cron "0 9 * * *" --email user@example.com

# View history
python client/cli.py history --days 30

# Get statistics
python client/cli.py stats

3.Python API

自定义应用程序的编程访问。

import asyncio
from client.mcp_client import QueryAssistantClient

async def main():
    async with QueryAssistantClient() as client:
        # Execute query
        result = await client.query_database(
            "Show me the top 5 customers by order value",
            user_id=1
        )
        
        # Export data
        export = await client.export_query_results(
            user_id=1,
            query="Show all customers",
            format="excel"
        )
        
        # Create schedule
        schedule = await client.create_scheduled_report(
            user_id=1,
            name="Daily Report",
            query="Show today's sales",
            schedule="0 9 * * *",
            email="user@example.com",
            format="excel"
        )

asyncio.run(main())

请参阅： CLIENT_GUIDE.md 获取完整的API文档

例子

位于 client/examples/:

  • basic_query.py -简单查询执行
  • batch_queries.py -高效地执行多个查询
  • schedule_reports.py -创建和管理时间表
  • export_data.py -以多种格式导出
  • advanced_usage.py -完整的工作流程示例
python client/examples/basic_query.py

配置选项

数据库

  • DATABASE_URL：PostgreSQL连接字符串
  • DATABASE_POOL_SIZE：连接池大小（默认值：20）
  • DATABASE_MAX_OVERFLOW：最大溢出连接数（默认值：40）

瑞迪斯

  • REDIS_URL：Redis连接字符串
  • QUERY_CACHE_TTL_SECONDS：查询缓存TTL（默认值：300）

格罗克

  • GROQ_API_KEY：用于LLM推理的Groq API密钥
  • 推荐型号： llama-3.3-70b-versatile （复杂查询）
  • 备选方案： llama-3.1-8b-instant （简单查询，更快）

安全

  • QUERY_TIMEOUT_SECONDS：查询执行超时（默认值：30）
  • MAX_QUERY_RESULTS：返回的最大行数（默认值：1000）
  • RATE_LIMIT_PER_USER_PER_HOUR：每个用户的请求数（默认值：100）

发展

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (coming soon)
pytest

# Format code
black .

# Lint
ruff check .

许可证

MIT许可证-请参阅 许可证

贡献

欢迎投稿！请先阅读我们的投稿指南。

🎯 QueryAI-完整的解决方案

查询ai 代表了一个功能齐全、可投入生产的数据库智能平台，该平台结合了：

✨ 人工智能驱动的查询生成 -将自然语言转换为优化的SQL
🎨 现代React前端 -美观、响应迅速的用户界面
📧 自动电子邮件报告 -使用专业模板按计划交付
🔐 企业安全 -基于角色的访问控制和审计日志记录
⚡ 高性能 -多层缓存和连接池
🚀 可扩展体系结构 -容器就绪，支持负载平衡

📊 按数字

  • 17 MCP工具 -完整的数据库操作工具包
  • 11个数据库表 -综合数据模型
  • 5+导出格式 -灵活的数据交付选项
  • 亚秒级响应 -闪电般快速的查询执行
  • 100%测试覆盖率 -生产就绪可靠性

内置于❤️ 使用尖端技术：

🤖 Pydantic AI • ⚡ FastMCP • 🧠 格罗克 • ⚛️ 反应 • 🐘 PostgreSQL • 🔴 瑞迪斯

⭐ 如果QueryAI帮助您构建更好的数据库解决方案，请标记此存储库！

相关 MCP