SQL Server Table Assistant - Modal Context Protocol

SQL Server 表格助手 - Modal Context Protocol

此应用程序使用自然语言与指定的 SQL Server 表格交互，并利用 Modal Context Protocol 作为大模型与数据源之间的通信层。

此项目基于 Aman Pachori 的 mcp-sql-server-natural-lang 仓库，并进行了修改，以专注于访问单个表格。

主要功能：

• 与表格对话：使用通俗英语与指定的 SQL Server 表格交流
• SQL 查询迭代：提供反馈以完善 SQL 查询，直到满足需求
• 清晰的表格结果：以格式良好的表格查看查询结果，提高可读性
• 查询历史记录：自动保存查询、迭代过程和结果，供日后参考
• 无代码表格操作：通过自然对话查询、插入、更新和删除数据
• 安全的有限访问：仅连接到一个表格，并使用受限凭据来增强安全性
• MCP 增强的准确性：通过 Modal Context Protocol 实现精准的表格交互
• 上下文感知对话：在多次查询之间保留上下文
• 自然语言解释：以通俗英语获取查询结果的说明
• Token 优化：通过智能缓存和上下文管理，尽量减少 API 使用量

什么是 MCP？

MCP（Modal Context Protocol）是一种标准化上下文与大模型绑定方式的方法，为将 AI 模型连接到不同数据源和工具提供了标准方式。

单表模式

此应用程序以“单表模式”运行，具有以下优势：

1. 增强安全性：访问范围仅限于单个表格，而非整个数据库
2. 权限更简单：用户只需拥有最低限度的权限（仅限指定表格）
3. 专注的体验：助手专门用于处理单个表格
4. 降低风险：防止意外访问其他表格中的敏感数据

Token 优化

此应用程序采用了多种策略，以尽量减少 Token 使用量并防止触发速率限制：

1. 智能架构摘要：不向模型发送完整的表格架构，而是生成简明摘要
2. 响应缓存：缓存相似的查询和说明，避免重复调用 API
3. 精简提示词设计：优化系统提示词和用户指令，使其更加简洁
4. 对话管理：仅将近期且相关的消息纳入上下文
5. 专用系统提示词：针对不同任务（架构、查询生成、说明）使用不同的提示词
6. 选择性结果传输：发送给模型前，先对大型结果集进行裁剪
7. Token 参数调优：对 max_tokens 等请求参数采用较为保守的设置

这些优化让应用程序即使面对大型表格和复杂查询，也能流畅运行，同时遵守 API 速率限制。

先决条件

开始之前，请确保具备以下条件：

• 已在计算机上安装 Python 3.12+
• 有效的 Azure OpenAI 部署，并已开通 API 访问权限
• SQL Server，其中包含你想要交互的表格
• 仅能访问该表格的受限用户凭据

开始使用

按照以下步骤启动并运行项目：

1. 克隆仓库

git clone https://github.com/yourusername/sql-server-table-assistant.git
cd sql-server-table-assistant

2. 安装依赖项

pip install -r requirements.txt

3. 设置环境变量

在项目根目录中创建一个 .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

运行表格助手

设置好环境和依赖项后，即可开始与表格助手交互。

运行客户端脚本

执行以下命令以启动助手：

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

交互式查询工作流

助手遵循以下交互式工作流：

1. 你用自然语言提出问题
2. 助手生成 SQL 查询
3. 你可以：
   • 执行查询（e）
   • 提供反馈以优化查询（f）
   • 取消（c）
4. 如果你提供反馈，助手会生成改进后的查询
5. 查询执行后，结果会以格式化表格的形式显示
6. 助手会用英文通俗地解释结果
7. 查询、迭代过程和结果的完整日志会自动保存

对话示例

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
=======================

查询日志记录

所有查询和结果都会自动以 JSON 文件的形式保存到 logs/queries/，以供日后参考。每条日志都包含：

• 原始自然语言查询
• 所有 SQL 迭代和反馈
• 最终执行的 SQL 查询
• 查询结果
• 时间戳

这样，你就可以跟踪查询随时间的演变，并保留所有数据库交互记录。

安全注意事项

此应用实现了多项安全功能：

1. 仅访问单个表：查询仅限于配置的表
2. 查询验证：所有 SQL 查询都会在执行前显示给用户审批
3. 事务安全：INSERT/UPDATE/DELETE 测试使用事务并在结束时回滚
4. 错误追踪：详细的错误日志有助于诊断问题，同时不会泄露敏感信息
5. 防止 SQL 注入：结构化查询生成可降低 SQL 注入风险

连接问题

如果遇到连接问题：

1. 确认服务器名称或 IP 地址正确
2. 确保 SQL Server 正在运行并接受远程连接
3. 检查防火墙设置，确保允许 SQL Server 流量通过
4. 确认 .env 文件中指定的 ODBC 驱动程序已安装
5. 使用 SSMS 或 sqlcmd 等其他工具测试连接

Token 使用问题排查

如果 Azure OpenAI 出现速率限制错误：

1. 稍后重试：速率限制通常与时间有关，等待 60 秒可能会解决问题
2. 提高配额：访问 https://aka.ms/oai/quotaincrease 申请提高速率限制
3. 升级套餐：免费账户可能需要升级到按需付费套餐
4. 使用 /refresh_schema 命令：重新生成架构摘要，这可能会减少 Token 使用量
5. 检查提示词长度：非常复杂的问题可能会增加 Token 使用量

许可证

本项目基于 MIT License 授权，详情请参阅 LICENSE 文件。

致谢

• 原始 MCP SQL Server 自然语言实现由 Aman Pachori 提供
• 使用 Modal Context Protocol (MCP) 构建