SQL Server表助手-模态上下文协议
此应用程序允许您使用自然语言与特定的SQL Server表进行交互，利用模态上下文协议作为LLM和数据源之间的通信层。
主要特点：
- 与您的餐桌交谈：使用简明英语与特定的SQL Server表聊天
- SQL查询迭代：提供反馈以优化SQL查询，直到它们满足您的需求
- 漂亮的表格结果：在格式良好的表中查看查询结果，以提高可读性
- 查询历史记录：自动保存查询、迭代和结果以供将来参考
- 无代码表操作：通过自然对话查询、插入、更新和删除数据
- 安全、受限访问：仅连接到一个具有受限凭据的表，以增强安全性
- MCP增强精度：通过模态上下文协议实现精确的表交互
- 情境感知对话：跨多个查询维护上下文
- 自然语言解释：获取查询结果的简明英文解释
- 令牌优化：智能缓存和上下文管理，最大限度地减少API的使用
什么是MCP？
MCP（模态上下文协议）是一种标准化上下文如何绑定到LLM的方法，提供了一种将AI模型连接到不同数据源和工具的标准方法。
单桌模式
此应用程序以“单表模式”运行，具有以下优点：
- 增强的安全性：访问仅限于单个表，而不是整个数据库
- 更简单的权限：用户需要最小权限（仅针对特定表）
- 专注体验这位助理专门处理一张桌子
- 降低风险：防止意外访问其他表中的敏感数据
令牌优化
此应用程序实现了多种策略，以最大限度地减少令牌使用并防止速率限制：
- 智能模式摘要：创建了一个简洁的摘要，而不是将整个表模式发送到模型
- 响应缓存：缓存类似的查询和解释，以避免重复的API调用
- 最小提示设计：系统提示和用户说明经过优化，简洁明了
- 会话管理：上下文中只包含最近的相关信息
- 专用系统提示：不同任务的不同提示（模式、查询生成、解释）
- 选择性结果传输：大型结果集在发送到模型之前会被修剪
- 令牌参数调整：像max_tokens这样的请求参数设置保守
这些优化使应用程序即使在使用大型表和复杂查询时也能顺利运行，同时保持在API速率限制范围内。
先决条件
在开始之前，请确保您具备以下条件：
- Python 3.12+ 安装在您的计算机上
- A有效 Azure OpenAI部署 具有API访问权限
- SQL Server 使用您想要与之交互的表
- 有限的用户凭据 只能访问该表
入门指南
按照以下步骤启动并运行项目：
1.克隆存储库
git clone https://github.com/yourusername/sql-server-table-assistant.git
cd sql-server-table-assistant2.安装依赖项
pip install -r requirements.txt3.设置环境变量
创建一个 .env 在项目的根目录下创建文件，并添加以下内容：
# Azure OpenAI Configuration (required)
AZURE_OPENAI_API_KEY=your_azure_openai_api_key
AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com
AZURE_OPENAI_API_VERSION=2023-05-15
AZURE_OPENAI_DEPLOYMENT_ID=your-deployment-name
# SQL Server Configuration
MSSQL_SERVER=localhost
MSSQL_DATABASE=your_database_name
MSSQL_USERNAME=your_username
MSSQL_PASSWORD=your_password
MSSQL_DRIVER={ODBC Driver 18 for SQL Server}
# Table Configuration
MSSQL_TABLE_SCHEMA=dbo
MSSQL_TABLE_NAME=your_table_name运行表格助手
设置好环境和依赖关系后，您就可以与Table Assistant进行交互了。
运行客户端脚本
执行以下命令以启动助手：
python mcp-ssms-client.py脚本启动后，它将提示您表名和可用命令。然后，您可以用简单的英语键入您的请求。例如：
Table Assistant is ready. You are working with table: dbo.Employees
Type your questions about the table in natural language, and I'll translate them to SQL.
Special commands:
/diagnose - Run diagnostics
/refresh_schema - Refresh table schema
/history - View query history
Enter your Query: Show me all employees with a salary over $50,000交互式查询工作流
助理遵循交互式工作流程：
- 你用自然语言提问
- 助手生成SQL查询
- 你可以：
- 执行查询（e） - 提供反馈以完善它（f） - 取消（c）
- 如果您提供反馈，助手将生成一个改进的查询
- 执行后，结果将显示在格式化的表中
- 助理对结果进行了简明的英语解释
- 查询、迭代和结果的完整日志会自动保存
对话示例
Enter your Query: Show me the highest paid employee in each department
===== GENERATED SQL QUERY =====
SELECT
Department,
EmployeeName,
Salary
FROM (
SELECT
Department,
EmployeeName,
Salary,
ROW_NUMBER() OVER (PARTITION BY Department ORDER BY Salary DESC) as RankBySalary
FROM dbo.Employees
) RankedEmployees
WHERE RankBySalary = 1
ORDER BY Department
===============================
Do you want to (e)xecute this query, provide (f)eedback to refine it, or (c)ancel? (e/f/c): f
Enter your feedback for improving the SQL query: Include the employee's hire date as well
SQL query generated (iteration 2).
===== GENERATED SQL QUERY =====
SELECT
Department,
EmployeeName,
Salary,
HireDate
FROM (
SELECT
Department,
EmployeeName,
Salary,
HireDate,
ROW_NUMBER() OVER (PARTITION BY Department ORDER BY Salary DESC) as RankBySalary
FROM dbo.Employees
) RankedEmployees
WHERE RankBySalary = 1
ORDER BY Department
===============================
Do you want to (e)xecute this query, provide (f)eedback to refine it, or (c)ancel? (e/f/c): e
===== QUERY RESULTS =====
Query executed successfully. 5 rows returned.
+------------+---------------+----------+------------+
| Department | EmployeeName | Salary | HireDate |
+============+===============+==========+============+
| Finance | Jane Smith | 95000.00 | 2018-03-15 |
| HR | Tim Johnson | 75000.00 | 2020-01-10 |
| IT | Mary Williams | 98000.00 | 2017-05-22 |
| Marketing | Bob Miller | 82000.00 | 2019-07-08 |
| Sales | John Davis | 92000.00 | 2016-11-14 |
+------------+---------------+----------+------------+
==========================
Query log saved successfully to logs/queries/query_20230901_152412.json
===== RESULT EXPLANATION =====
The results show the highest paid employee in each department along with their hire date. There are 5 departments in total:
- In Finance, Jane Smith has the highest salary at $95,000 and was hired on March 15, 2018.
- In HR, Tim Johnson earns the most at $75,000 and joined on January 10, 2020.
- In IT, Mary Williams is the top earner with $98,000 and has been with the company since May 22, 2017.
- In Marketing, Bob Miller makes $82,000 and started on July 8, 2019.
- In Sales, John Davis has the highest salary at $92,000 and was hired on November 14, 2016.
Mary Williams from IT has the highest overall salary among all the top-earning employees across departments.
==============================诊断和特殊命令
该应用程序包括几个特殊命令：
/diagnose-运行全面的表访问诊断/refresh_schema-刷新表架构/history-查看当前会话中执行的所有查询的列表
查询历史
查询历史功能可帮助您跟踪会话期间执行的所有查询：
===== QUERY HISTORY =====
1. [2023-09-01 15:24:12] Show me all employees with a salary over $50,000
SQL: SELECT EmployeeName, Department, Salary FROM dbo.Employees WHERE Salary > 50000 ORDER...
Iterations: 1, Success: True
2. [2023-09-01 15:32:45] Show me the highest paid employee in each department
SQL: SELECT Department, EmployeeName, Salary, HireDate FROM (SELECT Department, EmployeeName...
Iterations: 2, Success: True
=======================查询日志记录
所有查询和结果都会自动保存到 logs/queries/ 作为JSON文件供将来参考。每个日志包括：
- 原始自然语言查询
- 所有SQL迭代和反馈
- 执行的最后一个SQL查询
- 查询结果
- 时间戳
这允许您跟踪查询如何随时间演变，并维护所有数据库交互的记录。
安全考虑
此应用程序实现了几个安全功能：
- 单表访问：查询仅限于配置的表
- 查询验证：所有SQL查询在执行前都会显示以供用户批准
- 交易安全：INSERT/UPDATE/DELETE测试使用具有回滚功能的事务
- 误差溯源：详细的错误日志有助于诊断问题，而不会暴露敏感信息
- SQL注入预防：结构化查询生成降低了SQL注入的风险
连接问题
如果您遇到连接问题：
- 验证您的服务器名称或IP地址是否正确
- 确保SQL Server正在运行并接受远程连接
- 检查防火墙设置以允许SQL Server流量
- 验证是否安装了.env文件中指定的ODBC驱动程序
- 测试与其他工具（如Contoso或sqlcmd）的连接
令牌使用故障排除
如果您在Azure OpenAI中遇到速率限制错误：
- 请稍候，然后重试：速率限制通常基于时间，因此等待60秒可能会解决问题
- 增加你的配额: 访问https://aka.ms/oai/quotaincrease要求更高的利率限制
- 升级您的等级：免费帐户可能需要升级为按需付费
- 使用/refresh_schema命令：这将重新生成架构摘要，这可能会减少令牌的使用
- 检查提示长度：非常复杂的问题可能会引发更多的代币使用
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
致谢
- 原始MCP SQL Server自然语言实现 阿曼 帕乔里
- 内置于 模态上下文协议（MCP）