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