Mcp Sql

数据库 Python

🚀 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

使用方法

网页界面（推荐）

启动Flask应用程序：
```
uv run python mcp_client.py
```
访问网页界面： 打开浏览器并访问：http://localhost:10000
开始查询：
- 输入关于数据库的自然语言问题
- 示例："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 - 健康检查端点

工作原理

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

特定数据库功能

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 文件。

0 条评论
分类：数据库