mcp-server-client

QueryAI - 智能数据库查询助手

🚀 企业级 AI 驱动的数据库查询平台，可将自然语言转换为 SQL 查询，并自动生成报告和发送邮件。采用 Pydantic AI、FastMCP、React 和 PostgreSQL 构建，提供可用于生产环境的数据库智能服务。

🎯 我们构建的产品

QueryAI 是一个完整的 AI 驱动的数据库智能平台，我们已从零开始成功构建：

🎨 现代化 React 前端

• 美观且响应迅速的 UI，采用 React + Vite + Tailwind CSS 构建
• 交互式仪表板，提供实时分析和图表
• 查询构建器界面，支持语法高亮和自动补全
• 定时报告管理，配有可视化 cron 表达式构建器
• 用于自动发送报告的邮件配置

🤖 AI 驱动的后端引擎

• 自然语言处理——使用日常英语提问，获取 SQL 结果
• 17 个 MCP 工具——使用 FastMCP 构建的完整 Model Context Protocol 服务
• 智能查询生成——由 Groq 的 Llama 3.3 70B 模型驱动
• 邮件自动化——集成 Gmail SMTP，支持 HTML 模板和 CSV 附件
• 高级缓存——多层 Redis 缓存，实现亚秒级响应

🔐 企业级安全与合规

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

📊 高级分析与报告

• 自动生成图表——使用 Chart.js 创建动态可视化内容
• 定时报告——基于 cron 的自动化，并通过邮件发送
• 多格式导出——支持导出 CSV、Excel、PDF 和 JSON
• 性能监控——查询执行指标和优化建议

🚀 可用于生产环境的基础设施

• 水平扩展——支持连接池，已具备负载均衡扩展条件
• Docker 容器化——使用 docker-compose 进行多阶段构建
• 运行状况监控——全面的运行状况检查和 Prometheus 指标
• 错误处理——稳健的错误处理，并提供详细日志

🏗️ 系统架构

QueryAI 采用现代化、可扩展的架构，专为企业级工作负载设计：

🌐 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、Tailwind CSS、Chart.js、Axios
• 后端：FastAPI、FastMCP、Pydantic AI、SQLAlchemy、AsyncPG
• AI/ML：Groq API（Llama 3.3 70B）、自然语言处理
• 数据库：PostgreSQL 14+，支持异步连接池
• 缓存：Redis 6+，采用多层缓存策略
• 邮件：Gmail SMTP，支持 HTML 模板和文件附件
• 调度：基于 cron 的任务调度，并计算下次运行时间
• 部署：Docker、Docker Compose、NGINX 负载均衡器

📁 项目结构

QueryAI 采用清晰的模块化架构，职责划分明确：

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

🚀 快速入门指南

按照精简的设置流程，只需几分钟即可启动并运行 QueryAI：

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 protected]
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=true
[email protected]
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：React 前端

cd frontend
npm run dev

✅ 成功标志：

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

---

🎉 访问 QueryAI 控制面板

打开浏览器并访问：

• 🎨 QueryAI 控制面板：http://localhost:8081
• 📚 API 文档：http://localhost:8000/docs
• 💚 健康检查：http://localhost:8000/health

---

🎯 你将看到的内容

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

🏗️ 开发历程

QueryAI 经历了多个阶段，以系统化、迭代式的流程构建而成：

✅ 阶段 1：基础与架构（已完成）

• 🏗️ 项目结构：简洁、模块化的架构，职责划分明确
• 🗄️ 数据库层：采用连接池的 SQLAlchemy 异步 ORM
• ⚡ 缓存层：Redis 多级缓存，实现亚秒级响应
• 🔐 安全模块：RBAC、SQL 注入防护和查询验证
• 📊 数据库架构：包含优化索引和关系的 11 张表

✅ 阶段 2：AI 驱动的查询引擎（已完成）

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

✅ 阶段 3：邮件自动化与调度（已完成）

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

✅ 阶段 4：现代 React 前端（已完成）

• 🎨 精美 UI：采用 React 18 + Vite + Tailwind 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（Rich）

为高级用户和自动化场景提供的命令行界面。

# 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 [email protected]

# 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="[email protected]",
            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

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

Groq

• GROQ_API_KEY：用于大模型推理的 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 License - 详见 LICENSE

贡献

欢迎贡献！请先阅读我们的贡献指南。

---

---

🎯 QueryAI - 完整解决方案

QueryAI 是一个功能齐全、可用于生产环境的数据库智能平台，结合了：

✨ AI 驱动的查询生成 - 将自然语言转换为优化后的 SQL
🎨 现代化 React 前端 - 美观、响应迅速的用户界面
📧 自动化邮件报告 - 使用专业模板定时发送
🔐 企业级安全性 - 基于角色的访问控制和审计日志
⚡ 高性能 - 多级缓存和连接池
🚀 可扩展架构 - 支持容器部署和负载均衡

📊 数据一览

• 17 个 MCP 工具 - 完整的数据库操作工具集
• 11 张数据库表 - 全面的数据模型
• 5 种以上的导出格式 - 灵活的数据交付选项
• 亚秒级响应 - 闪电般快速的查询执行
• 100% 测试覆盖率 - 可用于生产环境的可靠性

---

采用前沿技术倾心打造：

🤖 Pydantic AI • ⚡ FastMCP • 🧠 Groq • ⚛️ React • 🐘 PostgreSQL • 🔴 Redis

---

⭐ 如果 QueryAI 帮助你构建了更好的数据库解决方案，请为此仓库点亮星标！