mcp-sql-querystore

mcp-name: io.github.deepeshd87/mcp-sql-querystore

mcp-sql-querystore

只读 MCP 服务，向大模型 Agent 提供 SQL Server Query Store 诊断功能。

提供 6 种只读诊断工具，涵盖 Query Store、DMV 和执行计划。这些工具已在实时 SQL Server 实例上验证，并通过了单元测试和集成测试。不过，在连接到生产环境之前，仍请先在你自己的非生产实例上进行验证，尤其是在使用下方注意事项中未提及的 SQL Server 版本时。

快速开始

1. 配置只读登录名。 在你的实例上运行 provisioning/create_readonly_login.sql（先编辑名称）。此登录名的权限是只读保障的来源——请参阅下方的安全模型。

2. 安装。 在虚拟环境中运行 pip install -e .。主机上必须安装 ODBC Driver 18 for SQL Server。

3. 在仓库外保存密码。 将密码放入仓库无法访问的位置的纯文本文件中（不要放在项目文件夹下）：

   # Windows PowerShell，UTF-8，仅包含密码，不加引号或换行符
   New-Item -ItemType Directory -Force C:\Users\you\secrets | Out-Null
   Set-Content -NoNewline -Encoding utf8 C:\Users\you\secrets\mcp_sql.pwd 'your-password'
   

   也可以完全不使用密码，改用集成身份验证（MCP_SQL_TRUSTED=yes）——建议用于 CJIS/PCI 环境。所有选项请参阅下方的机密信息处理。

4. 配置 MCP 客户端。 将 claude_desktop_config.example.json 中的 sql-querystore 区块复制到你实际使用的 Claude Desktop 配置文件（Windows：%APPDATA%\Claude\claude_desktop_config.json），然后替换占位路径、服务名称和 MCP_SQL_PWD_FILE。仅在使用自签名证书或本地证书时将 MCP_SQL_TRUST_CERT=yes；连接到使用正规证书的实例时，请保持为 no。

5. 重启 MCP 客户端，并确认服务显示为正在运行。

切勿提交实际配置文件或密码文件。.gitignore 已排除 *.pwd、.env 和 claude_desktop_config.json。

安全模型（请先阅读）

只读保障来自SQL 登录名的权限，而非本仓库中的任何代码：

• 配置专用登录名，仅授予 VIEW DATABASE STATE（只有在使用服务器范围的 DMV 时才授予 VIEW SERVER STATE），不授予其他任何权限——不要授予 db_datareader，也不要授予用户表上的 SELECT 权限。请参阅 provisioning/create_readonly_login.sql。
• db.py 中的关键字检查和固定的仅含 SELECT 的查询文本属于纵深防御，而不是主要控制措施。
• 连接字符串中的 ApplicationIntent=ReadOnly 只会将连接路由到可用性组中的可读辅助副本。在独立实例上，它不会将会话设为只读。请勿依赖它来保障安全。
• 凭据绝不能写入代码。最简单的设置方式是使用 MCP_SQL_CONNECTION_STRING 环境变量，但在 CJIS/PCI 环境中，建议使用集成身份验证，或从文件/机密存储中读取密码——请参阅下方的机密信息处理部分。
• 每条查询都会通过审计日志记录器记录——请参阅下方的审计日志。在受监管环境中，请将该日志记录器配置为写入持久文件或 SIEM。

设置

主机上必须安装 ODBC Driver 18 for SQL Server。安装软件包后，通过环境变量配置连接（所有选项请参阅机密信息处理）。建议使用将密码保存在文件中的方式，而不是直接写入：

pip install -e .

# PowerShell — connection assembled from parts, password read from a file
$env:MCP_SQL_SERVER      = "yourhost\INSTANCE"
$env:MCP_SQL_DATABASE    = "master"
$env:MCP_SQL_UID         = "mcp_readonly"
$env:MCP_SQL_PWD_FILE    = "C:\path\to\your\secret.pwd"
$env:MCP_SQL_TRUST_CERT  = "no"   # "yes" only for a self-signed/local cert

python -m mcp_sql_querystore.server

或者使用集成身份验证，完全不保存密码（MCP_SQL_TRUSTED=yes）。简单场景也支持完整的 MCP_SQL_CONNECTION_STRING——请参阅机密信息处理。

在 MCP 客户端（例如 Claude Desktop）中将其注册为 stdio 服务，并调用 python -m mcp_sql_querystore.server；请参阅 claude_desktop_config.example.json。

工具

所有工具均为只读，并且都需要传入 database_name（sweep_regressions 除外，它可以扫描所有数据库）。每个工具都会返回 JSON；失败时则返回结构化错误字典，而不会抛出异常。

• get_regressed_queries — 按查询比较近期时间窗口与较早的基准时间窗口，并标记性能下降幅度至少达到 regression_threshold 的查询。这是真正的基准与近期数据对比，而不是 CPU 占用最高查询列表。
• get_query_execution_plan — 返回指定 query_id 的编译计划，并附带精简的 JSON 摘要（缺失的索引、警告，包括隐式转换和键查找），以及可选的原始 XML。
• analyze_parameter_sniffing — 查找具有多个编译计划的查询，并按最慢计划与最快计划的平均时长比值排序，这是参数嗅探的典型特征。
• get_missing_index_impact — 扫描包含缺失索引建议的近期计划，从计划 XML 中解析影响分数，并汇总多个查询中的重复建议，再按影响分数和出现次数排序。
• get_wait_stats — 按等待类别汇总一个时间窗口内的查询等待时间，展示查询变慢的原因（CPU、阻塞/锁、IO、内存），而非哪些查询变慢。根据 Microsoft 指南，去除已刷新行与内存中行的重复项。
• sweep_regressions — 在所有已启用 Query Store 且处于联机状态的数据库中运行性能回退检测（也可指定 database_names 列表），并按数据库返回最严重的回退情况并排序。单个数据库发生故障不会中止扫描；其错误会被收集并报告。

示例提示词

将服务连接到 MCP 客户端后，你可以用自然语言调用这些工具。在提示词中指定目标数据库（sweep_regressions 除外，它可以扫描所有数据库）。将 YourDB 替换为你的数据库名称。

等待统计信息 — 查询变慢的原因

• “过去一周，YourDB 中排名靠前的等待类别有哪些？”
• “YourDB 是否在等待 CPU、内存或 IO？”
• “显示 YourDB 过去 24 小时的等待统计信息。”

执行计划

• “获取 YourDB 中 query_id 10 的执行计划并进行摘要。”
• “YourDB 中的 query_id 13 是否有缺失索引建议？”
• “YourDB 中 query 12 的计划是否有隐式转换警告？”

回退分析

• “检查 YourDB 过去 24 小时内是否有 CPU 性能回退。”
• “YourDB 中哪些查询的性能下降超过了 30%？”
• “查找 YourDB 中的持续时间回退，忽略执行次数少于 10 次的查询。”

参数嗅探

• “检查 YourDB 是否存在参数嗅探。”
• “YourDB 中哪些查询的计划不稳定？”

缺失索引

• “YourDB 最需要哪些缺失索引？”
• “按影响分数显示 YourDB 排名前 10 的索引建议。”

多数据库扫描（无需数据库名称）

• “扫描我的所有数据库，查找 CPU 性能回退。”
• “本周哪个数据库的性能回退最严重？”

组合调用 — 在一轮中串联多个工具

• “找出 YourDB 中最大的 CPU 性能回退，获取其计划，并告诉我可能的回退原因。”
• “YourDB 感觉很慢——帮我诊断一下。”（等待统计信息 → 性能回退 → 计划）
• “对 YourDB 进行全面的性能排查：等待统计信息、排名靠前的性能回退和缺失索引。”

已知问题 / 待办事项

• 版本差异。 Query Store 列名假设使用的是 SQL Server 2019+/2022 和 Azure SQL MI。如果目标环境为 2016/2017，请进行验证。
• 性能回退的计算方式。 当前逻辑使用按执行次数加权的平均值。你可能更倾向于基于百分位数进行比较（Query Store 不会直接存储百分位数，因此需要使用 *_stdev 列并作出假设）。
• 不按时间窗口筛选： analyze_parameter_sniffing 会汇总 Query Store 的全部历史数据；对于繁忙的数据库，可考虑像其他工具一样添加 recent_hours 筛选条件。
• 剩余的加固工作： 增加带退避机制的连接重试，以及针对混合使用 2016/2017/2019/2022 版本的数据库集群，按版本处理列名。

密钥处理

连接字符串按以下顺序解析，因此密码无需以明文形式存放在配置中：

1. MCP_SQL_CONNECTION_STRING — 完整字符串（最简单；向后兼容）。
2. MCP_SQL_CONNECTION_STRING_FILE — 存放完整字符串的文件路径 （Docker/K8s 密钥挂载方式）。
3. 根据各部分组装：MCP_SQL_SERVER（以及 MCP_SQL_DATABASE、MCP_SQL_DRIVER、 MCP_SQL_ENCRYPT、MCP_SQL_TRUST_CERT、MCP_SQL_EXTRA）。身份验证方式为：
   • 集成身份验证（CJIS/PCI 场景的首选方式——不存储密码）：MCP_SQL_TRUSTED=yes。
   • SQL 身份验证：MCP_SQL_UID 加上来自 MCP_SQL_PWD_FILE（由 保管库挂载的文件）、MCP_SQL_PWD_ENV（另一个环境变量的名称）或 MCP_SQL_PWD（直接提供；最不推荐）的密码。

超时设置：MCP_SQL_CONNECT_TIMEOUT（默认 10s）和 MCP_SQL_QUERY_TIMEOUT （默认 30s，设为 0 可禁用）。

审计日志

每次查询尝试都会通过 mcp_sql_querystore.audit 日志记录器记录：工具、 数据库、SQL 的 12 个字符哈希值（不记录 SQL 文本）、行数、耗时（毫秒） 和执行结果。绝不会记录连接字符串、SQL 文本和参数值。为该日志记录器配置处理器， 即可将审计跟踪记录发送到文件或 SIEM。

测试

单元测试（无需数据库，可安全地在 CI 中运行）：

pip install -e ".[test]"
pytest

集成测试（真实实例，可选择运行）：

# 设置可用的连接（上述任意形式），然后：
$env:SQL_TEST_DATABASE = "RAG"
$env:MCP_SQL_RUN_INTEGRATION = "1"
pytest tests/test_integration.py -v