MCP DB Integration

MCP服务器POC-SQL分析助手

一种模型上下文协议（MCP）服务器实现，提供具有自然语言处理和可视化的智能SQL查询功能。

概述

该项目结合了：

• MCP服务器 用于SQL操作和资源管理
• 经纪人代理 使用LLM驱动的查询编排（Ollama）
• Gradio用户界面 用于交互式聊天和数据可视化
• 多数据库支持 自动路由

特性

• 🤖 自然语言到SQL查询生成
• 🔄 智能服务器路由和数据库选择
• 📊 自动数据可视化（条形图、折线图、饼图等）
• 🛡️ SQL注入预防和查询验证
• 📚 内置SQL参考资源
• 🌐 SQL文档的Web资源获取
• 🔍 模式自省和元数据分析

先决条件

• Python 3.8+
• SQL Server SQL Server的ODBC驱动程序17
• 奥拉玛 使用兼容的模型运行（例如。， gpt-oss:20b)
• Node.js （v18+）-如果运行基于节点的MCP客户端

安装

1.克隆存储库

git clone 
cd mcp-server-poc

2.创建虚拟环境

# Windows
python -m venv venv
.\venv\Scripts\activate

# Linux/Mac
python -m venv venv
source venv/bin/activate

3.安装依赖项

pip install -r requirements.txt

4.安装SQL Server ODBC驱动程序

窗户：

• 下载并安装 用于SQL Server的Microsoft ODBC驱动程序17

Linux：

curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add -
curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list > /etc/apt/sources.list.d/mssql-release.list
apt-get update
ACCEPT_EULA=Y apt-get install -y msodbcsql17

5.安装和配置Olama

# Download Ollama from https://ollama.ai/download

# Pull a model
ollama pull gpt-oss:20b

# Ensure Ollama is running and accessible
ollama serve

配置

数据库配置

创建 db_config.json 在项目根目录中：

{
  "test_db": {
    "driver": "ODBC Driver 17 for SQL Server",
    "server": "your-server-name",
    "database": "your-database-name",
    "username": "your-username",
    "password": "your-password"
  },
  "sql-agent": {
    "driver": "ODBC Driver 17 for SQL Server",
    "server": "your-server-name",
    "database": "your-database-name",
    "username": "your-username",
    "password": "your-password"
  }
}

MCP服务器配置

这 mcp.json 文件已配置：

{
  "mcpServers": {
    "sql-agent": {
      "url": "http://127.0.0.1:8007/mcp"
    }
  }
}

Ollama配置

更新Ollama的基本URL client.py 如果需要（默认值： http://10.247.79.122:8080):

self.ollama = ChatOllama(
    base_url="http://localhost:11434",  # Update this
    model="gpt-oss:20b",
    temperature=0,
)

运行应用程序

选项1：使用Gradio UI运行（推荐）

1. 启动MCP服务器 （1号航站楼）：

python server.py

输出应显示：

✅ MCP Server running on http://127.0.0.1:8007/mcp

1. 启动Gradio用户界面 （2号航站楼）：

python app.py

输出应显示：

🔍 Discovering MCP Servers...
✅ Connected to server sql-agent with X tools
✓ Database: your-database-name

Running on local URL:  http://127.0.0.1:7860

1. 打开浏览器：导航到 http://127.0.0.1:7860

选项2：运行CLI客户端

1. 启动MCP服务器 （1号航站楼）：

python server.py

1. 运行CLI客户端 （2号航站楼）：

python client.py

1. 提出问题:

❓ Ask your data question: How many records are in the Employees table?
❓ Ask your data question: Show me top 10 customers by revenue

选项3：运行独立组件

测试数据库连接：

python db_connection.py

仅测试MCP服务器：

python server.py
# Server will be available at http://127.0.0.1:8007/mcp

用法示例

自然语言查询

"How many energy saving records exist?"
"List all tables in the database"
"Show me top 10 employees by salary"
"What is the total revenue by product category?"
"Get customer information where value is greater than 1000"

使用Gradio UI

1. 键入您的问题 在输入框中
2. 查看回复 与：

- 使用了SQL查询 - 自然语言答案 - 数据可视化（自动生成） - 原始数据预览

使用CLI

1. 使用以下命令启动代理 python client.py
2. 在提示处键入问题
3. 查看包含SQL、答案和数据的完整响应
4. 类型 exit 或 quit 关闭

项目结构

mcp-server-poc/
├── app.py                  # Gradio UI application
├── client.py               # Broker agent with Ollama
├── server.py               # MCP server implementation
├── db_connection.py        # Database utilities
├── graph_generator.py      # Smart visualization logic
├── mcp.json               # MCP server configuration
├── db_config.json         # Database credentials (gitignored)
├── requirements.txt       # Python dependencies
└── README.md             # This file

关键组件

MCP服务器(server.py)

• 提供工具： get_ssms_schema, validate_sql_syntax, execute_sql_query, build_sql_from_description
• 提供资源：SQL引用、文档获取
• 在8007端口上运行

经纪人代理(client.py)

• 使用Ollama LLM编排查询
• 路由到适当的数据库服务器
• 处理错误更正和验证
• 合成自然语言答案

Gradio用户界面(app.py)

• 交互式聊天界面
• 实时数据可视化
• SQL透明度
• 错误处理和显示

图形生成器(graph_generator.py)

• 自动图表类型检测
• 支持：条形图、折线图、散点图、饼图、直方图、表格
• 针对大型数据集进行了性能优化

安全

• ✅ 只允许SELECT查询
• ✅ 关键词黑名单：DROP、DELETE、UPDATE、INSERT等。
• ✅ 执行前的SQL语法验证
• ✅ 强制行限制（默认值：100行）
• ✅ Web获取限制（10000个字符）

故障排除

端口已在使用中

# Windows: Find and kill process
netstat -ano | findstr :8007
taskkill /PID 
 /F

# Linux/Mac
lsof -ti:8007 | xargs kill -9

数据库连接失败

• 验证SQL Server是否正在运行
• 检查 db_config.json 凭证
• 确保已安装ODBC驱动程序
• 测试连接 python db_connection.py

Ollama没有回应

# Restart Ollama
ollama serve

# Check if model is available
ollama list

# Pull model if needed
ollama pull gpt-oss:20b

架构未加载

• 确保数据库用户具有读取系统表的权限
• 检查是否 INFORMATION_SCHEMA 可访问的
• 验证中的数据库名称 db_config.json 匹配实际数据库

性能提示

1. 限制行数 对于大型数据集（在查询中使用TOP N）
2. 使用特定的表名 关于更快路由的问题
3. 启用数据库索引 对于经常查询的列
4. 调整奥利玛温度 为0以生成一致的SQL

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

\[添加您的许可证信息\]

致谢

• 内置于 FastMCP
• 由...驱动 奥拉玛
• UI与 度
• 可视化 Plotly

支持

对于问题和疑问：

• 在存储库中创建问题
• 检查现有文档
• 查看SQL Server日志以了解连接问题

______________________________________________________________________

快乐查询！ 🚀