MCP Sql

🚀 MCP数据库助手

MCP数据库助手是一款由人工智能驱动的多数据库助手，它基于OpenAI的GPT模型和模型上下文协议（MCP）构建。该项目展示了如何创建一个智能数据库查询接口，该接口能够理解自然语言请求，并在具备完整模式感知的情况下，跨MySQL、Oracle和SQLite数据库执行SQL查询。

🚀 快速开始

前提条件

• Python 3.12+（在 .python-version 中指定）
• OpenAI API密钥：可从 OpenAI平台 获取
• 数据库：满足以下其中一个即可：
  • SQLite数据库文件（.db）
  • 可访问数据库的MySQL服务器
  • 具有正确连接字符串的Oracle数据库

安装步骤

1. 安装uv（若尚未安装）

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

替代方法（通过pip）：

pip install uv

2. 克隆并设置项目

git clone https://github.com/sharansahu/mcp-sql
cd mcp-sql

# 创建虚拟环境并安装依赖项
uv sync

3. 环境配置

在项目根目录创建一个 .env 文件，并进行数据库配置：

对于SQLite：

# OpenAI配置
OPENAI_API_KEY=your_openai_api_key_here

# 数据库配置
DB_TYPE=sqlite
DB_PATH=./dod_synthetic.db

对于MySQL：

# OpenAI配置  
OPENAI_API_KEY=your_openai_api_key_here

# 数据库配置
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=your_database_name
DB_USER=your_username
DB_PASSWORD=your_password

对于Oracle：

# OpenAI配置
OPENAI_API_KEY=your_openai_api_key_here

# 数据库配置
DB_TYPE=oracle
DB_USER=your_username
DB_PASSWORD=your_password
DB_DSN=hostname:port/service_name

使用方法

网页界面（推荐）

1. 启动Flask应用程序：

   uv run python mcp_client.py
   

2. 访问网页界面： 打开浏览器并访问：http://localhost:10000
3. 开始查询：
   • 输入关于数据库的自然语言问题
   • 示例："Show me all tables in the database"
   • 示例："Find personnel who worked on tank maintenance in the last 90 days"
   • 示例："What's the structure of the users table?"

✨ 主要特性

• 🤖 人工智能驱动的SQL助手 - 使用OpenAI GPT - 4o将自然语言转换为SQL查询
• 🔧 模型上下文协议集成 - 实现无缝的工具调用和上下文管理
• 🗄️ 多数据库支持 - 支持MySQL、Oracle和SQLite数据库
• 🌐 现代网页界面 - 简洁、响应式的聊天界面，支持实时查询处理
• 📊 模式发现 - 自动探索和验证数据库结构
• 🔍 智能搜索 - 通过关键字查找表和列
• 💾 会话管理 - 在浏览器会话期间持久保存聊天历史记录
• ⚡ 实时处理 - 异步处理以实现快速查询执行
• 🛡️ 安全查询执行 - 受保护的SQL执行，具备错误处理功能
• 🔄 双API支持 - 提供多种端点格式，以满足不同前端需求

📚 详细文档

示例查询

该AI助手可以处理各种类型的数据库查询：

模式探索

• "What tables are available in this database?"
• "Describe the structure of the personnel table"
• "Search for tables related to maintenance"
• "Show me the schema for all tables"

数据分析

• "How many records are in each table?"
• "Show me the first 5 personnel records"
• "Find all equipment of type 'tank'"
• "What are the column names in the orders table?"

复杂查询

• "Show personnel who performed maintenance on tanks in the last 90 days"
• "What's the average number of maintenance tasks per person?"
• "List equipment that hasn't been maintained recently"
• "Find the top 10 customers by order value"

数据库工具

MCP服务器提供了几个强大的数据库交互工具：

• get_schema() - 获取包含示例数据的完整数据库模式
• list_tables() - 列出所有可用的表
• describe_table(table_name) - 获取详细的表信息，包括列和示例数据
• search_tables(keyword) - 通过关键字查找表/列
• query_data(sql) - 安全地执行SQL查询

API端点

Flask应用程序提供了几个REST API端点：

• GET / - 提供主网页界面
• POST /api/query - 处理自然语言查询（返回详细状态）
• POST /api/chat - 替代查询端点（返回简化响应）
• POST /api/clear - 清除聊天会话历史记录
• GET /api/history - 检索聊天历史记录
• GET /health - 健康检查端点

工作原理

1. 数据库类型检测 - 系统根据 DB_TYPE 环境变量加载适当的MCP服务器
2. 用户输入 - 通过网页界面输入自然语言查询
3. 模式发现 - AI使用MCP工具探索数据库结构
4. 查询生成 - AI根据模式和数据库类型生成适当的SQL
5. 安全执行 - 执行SQL查询并进行适当的错误处理
6. 结果格式化 - 格式化结果并返回给用户
7. 会话管理 - 维护对话历史记录以提供上下文

特定数据库功能

SQLite

• 基于文件的数据库支持
• 完整的模式内省
• 示例数据预览

MySQL

• 连接池
• 支持UTF - 8并具有适当的排序规则
• 主键检测
• 行计数和示例数据

Oracle

• 大小写敏感的表/列处理（大写）
• 基于ROWNUM的分页
• 主键约束检测
• 用户模式感知

🔧 技术细节

故障排除

常见问题

“Invalid DB_TYPE”错误

• 确保 DB_TYPE 设置为 sqlite、mysql 或 oracle 之一
• 检查 .env 文件格式是否正确

“No module named 'openai'”

uv sync  # 重新安装依赖项

“OPENAI_API_KEY not found”

• 确保 .env 文件存在并包含API密钥
• 检查API密钥是否有效且有足够的信用额度

数据库连接错误

• SQLite：验证 DB_PATH 是否指向数据库文件
• MySQL：检查 DB_HOST、DB_PORT、DB_NAME、DB_USER 和 DB_PASSWORD
• Oracle：验证 DB_USER、DB_PASSWORD 和 DB_DSN 格式

网页界面无法加载

• 检查Flask是否在正确的端口（10000）上运行
• 验证静态文件是否在 static/ 目录中

特定数据库问题

MySQL连接问题：

• 确保MySQL服务器正在运行
• 验证用户是否具有适当的权限
• 如果远程连接，检查防火墙设置

Oracle连接问题：

• 验证是否安装了Oracle Instant Client
• 检查TNS名称配置
• 确保DSN中的服务名称正确

调试模式

使用额外的日志运行：

FLASK_DEBUG=True uv run python mcp_client.py

安全考虑

• 切勿提交包含真实凭据的 .env 文件
• 在生产环境中使用环境变量或安全保险库
• 实施适当的数据库用户权限
• 考虑SQL注入保护（MCP工具内置）
• 在生产环境中使用HTTPS

部署

本地开发

当前设置针对使用Flask开发服务器的本地开发进行了优化。

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。