SqlAugur

SqlAugur

一个 MCP 服务，为 AI 助手提供安全、只读的 SQL Server 数据库访问能力。每条查询都会使用 Microsoft 官方的 T-SQL 解析器解析为完整的 AST，而不是使用正则表达式，因此可在语法层面拦截注释注入、字符串字面量技巧和编码绕过。

┌──────────────┐          ┌───────────────────────────────────────────┐        ┌──────────────┐
│              │  stdio   │  SqlAugur                                 │        │              │
│  AI Client   │◄────────►│                                           │───────►│  SQL Server  │
│              │          │  ┌────────────┐  ┌──────────────────────┐ │        │              │
└──────────────┘          │  │  Query     │  │  Schema / Diagram /  │ │        └──────────────┘
                          │  │  Validator │  │  DBA Services        │ │
                          │  └────────────┘  └──────────────────────┘ │
                          │  ┌────────────────────────────────────┐   │
                          │  │  Rate Limiter                      │   │
                          │  └────────────────────────────────────┘   │
                          └───────────────────────────────────────────┘

快速开始

所有安装方式均按以下顺序操作：

1. 安装 SqlAugur
2. 将 appsettings.json 保存到正确位置
3. 将 SqlAugur 添加到 MCP 客户端配置中
4. 让助手调用 list_servers 进行验证

请从安装开始，查看具体命令和文件路径。

为什么采用这种方式

• AST 级查询验证 — 大多数 MCP 数据库服务会屏蔽关键词，或完全不进行验证。本项目使用 Microsoft 官方的 TSql180Parser 将每条查询解析为完整的语法树。注释注入、字符串字面量技巧和编码绕过会在语法层面被拦截，而不是依赖脆弱的正则表达式模式。

• 速率限制 — 令牌桶吞吐量限制和并发控制可防止失控的 AI 查询循环压垮生产环境中的 SQL Server。其他 MCP 数据库服务均不具备此功能。

• DBA 诊断工具 — 集成支持 First Responder Kit、DarlingData 和 sp_WhoIsActive，并通过参数屏蔽防止写入操作。这是一个全新的 MCP 能力类别。

• 响应大小优化 — DBA 工具默认排除冗长的列（XML 查询计划、死锁图、指标细分），并截断长字符串，可将响应大小缩减 90–99%。需要完整、未截断的输出时，可使用 verbose 和 includeQueryPlans 参数。

• 渐进式发现 — 最多提供 31 个工具，按工具集组织并按需加载。初始仅公开 6 个核心工具，从而缩小 AI 的上下文窗口并减少令牌用量。可根据需要发现并启用其他工具集。

功能

安全性

• 默认只读 — 仅允许 SELECT 和 CTE 查询
• 使用 ScriptDom 进行基于 AST 的查询验证（而非正则表达式）
• 屏蔽所有诊断存储过程的参数，以防止写入操作
• 并发和吞吐量速率限制

数据库工具

• 多服务支持 — 可命名连接到多个 SQL Server 实例
• 架构概览 — 简洁的 Markdown 架构图，包含主键、外键、约束和默认值
• 表文档 — 以 Markdown 格式描述列、索引、外键和约束
• ER 图生成 — 生成 PlantUML 和 Mermaid 图，并智能检测基数
• 架构探索 — 列出可编程对象、视图定义、扩展属性和依赖关系图
• 查询计划分析 — 估算或获取实际 XML 执行计划
• DBA 诊断 — 可选集成 First Responder Kit、DarlingData 和 sp_WhoIsActive，并自动优化响应大小
• 渐进式发现 — 动态工具集模式按需公开工具，减少初始上下文窗口的占用

安装

所有方法生成的 MCP 服务相同。请按以下顺序操作：安装、保存配置、连接客户端、验证。

NuGet 全局工具（推荐）

1. 安装（前提条件：.NET 10.0 运行时）

dotnet tool install -g SqlAugur

2. 保存配置文件

# Linux/macOS
mkdir -p ~/.config/sqlaugur
# Edit ~/.config/sqlaugur/appsettings.json with your server connections

# Windows (PowerShell)
mkdir "$env:APPDATA\sqlaugur" -Force
# Edit %APPDATA%\sqlaugur\appsettings.json with your server connections

要保存在该位置的 appsettings.json 示例：

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    }
  }
}

3. 添加到 MCP 客户端

{
  "mcpServers": {
    "sqlaugur": {
      "command": "sqlaugur"
    }
  }
}

更新方式：dotnet tool update -g SqlAugur

Docker / Podman

1. 运行 SqlAugur 容器

# Volume-mount a config file
docker run -i --rm \
  -v /path/to/appsettings.json:/app/appsettings.json:ro,Z \
  ghcr.io/mbentham/sqlaugur:latest

# Or use environment variables (no config file needed)
docker run -i --rm \
  -e SqlAugur__Servers__production__ConnectionString="Server=host.docker.internal;Database=master;..." \
  ghcr.io/mbentham/sqlaugur:latest

注意： 要连接主机上的 SQL Server，请使用 host.docker.internal（Docker Desktop）或 --network=host（Linux）。将 docker 替换为 podman 即可，所有命令都相同。启用了 SELinux 的系统（Fedora、RHEL）必须在卷挂载中使用 :Z 标志；macOS/Windows 上的 Docker Desktop 用户可以省略该标志。

如果挂载配置文件，请将其保存为 /path/to/appsettings.json，并挂载到 /app/appsettings.json。

2. 添加到 MCP 客户端

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-v", "/path/to/appsettings.json:/app/appsettings.json:ro,Z",
        "ghcr.io/mbentham/sqlaugur:latest"]
    }
  }
}

services:
  sqlaugur:
    image: ghcr.io/mbentham/sqlaugur:latest
    stdin_open: true
    volumes:
      - ./appsettings.json:/app/appsettings.json:ro,Z

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["compose", "run", "-i", "--rm", "sqlaugur"]
    }
  }
}

从源代码构建

1. 构建（前提条件：.NET 10.0 SDK）

git clone [email protected]:mbentham/SqlAugur.git
cd SqlAugur
dotnet publish SqlAugur -c Release -o SqlAugur/publish

2. 保存配置文件

# Linux/macOS
cp SqlAugur/appsettings.example.json SqlAugur/publish/appsettings.json
# Edit SqlAugur/publish/appsettings.json with your server connections

# Windows (PowerShell)
Copy-Item SqlAugur\appsettings.example.json SqlAugur\publish\appsettings.json
# Edit SqlAugur\publish\appsettings.json with your server connections

3. 添加到 MCP 客户端

{
  "mcpServers": {
    "sqlaugur": {
      "command": "dotnet",
      "args": ["/absolute/path/to/SqlAugur/publish/SqlAugur.dll"]
    }
  }
}

验证 MCP 连接（以大模型为先）

重启 MCP 客户端后，向助手提问：

• Call list_servers
• Call list_databases for server "production"

预期结果：

• list_servers 返回你配置的服务名称（例如 production）
• list_databases 返回数据库的 JSON 数组，而不是连接或身份验证错误

如果验证失败：

1. 确认 MCP 配置运行了预期命令（sqlaugur、docker run ... 或 dotnet /path/to/SqlAugur.dll）
2. 确认 appsettings.json 已保存在安装方式所要求的位置：
   • 本地工具：~/.config/sqlaugur/appsettings.json（Linux/macOS）或 %APPDATA%\sqlaugur\appsettings.json（Windows）
   • 容器：挂载到 /app/appsettings.json
   • 源代码构建：与发布的 DLL 位于同一目录（SqlAugur/publish/appsettings.json）
3. 确认工具调用使用了已配置的服务键（例如 production）
4. 确认连接字符串中的 SQL 连接和身份验证

配置

服务会从多个来源加载配置。优先级较高的来源会覆盖优先级较低的来源：

1. 命令行参数
2. 环境变量 — 使用 __ 作为分节符（例如，SqlAugur__Servers__production__ConnectionString=...）
3. 当前工作目录 — 运行命令所在目录中的 appsettings.json
4. 用户配置目录 — Linux 上的 ~/.config/sqlaugur/appsettings.json，Windows 上的 %APPDATA%\sqlaugur\appsettings.json
5. Azure Key Vault — 设置 AzureKeyVaultUri 时（见下文）
6. 应用程序目录 — DLL 所在目录中的 appsettings.json

配置示例（Windows 身份验证 — 推荐）：

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    },
    "MaxRows": 1000,
    "CommandTimeoutSeconds": 30,
    "MaxConcurrentQueries": 5,
    "MaxQueriesPerMinute": 60,
    "EnableFirstResponderKit": false,
    "EnableDarlingData": false,
    "EnableWhoIsActive": false,
    "EnableDynamicToolsets": false
  }
}

安全提示： appsettings.json 已加入 gitignore，以防意外提交凭据。有关推荐的身份验证方式，包括 Windows 身份验证、Azure 托管标识和安全凭据存储选项，请参阅 SECURITY.md。

工具

该服务提供 31 个工具，分为多个工具集。六个核心工具始终可用。其他工具集会在启动时加载（静态模式），或按需加载（动态模式）。

核心工具

每个工具包都通过配置标志单独启用，并且要求在目标 SQL Server 上安装相应的存储过程。

所有 DBA 工具默认都会优化响应大小——排除 XML 查询计划列，并截断较长的字符串值，以确保响应不超出 AI 上下文窗口限制。每个工具都支持以下可选参数：

部分工具还有其他参数：includeXmlReports（BlitzLock、HealthParser、HumanEventsBlockViewer）、compact（sp_WhoIsActive）、verboseMetrics（QuickieStore）。

当 EnableDynamicToolsets 为 true 时，启动时只会加载核心工具。三个元工具可让 AI 按需发现并启用其他工具集，从而减少初始上下文窗口的使用量：

示例流程：

1. AI 调用 list_toolsets — 发现 first_responder_kit 的状态为“可用”（已配置但尚未启用）
2. AI 调用 get_toolset_tools("first_responder_kit") — 查看这 7 个工具及其参数
3. AI 调用 enable_toolset("first_responder_kit") — 这 7 个工具现已注册并可用
4. AI 调用 sp_blitz — 照常运行健康检查

在静态模式（EnableDynamicToolsets: false）下，所有已启用的工具集都会在启动时加载，且不会注册发现工具。无论使用哪种模式，Schema Exploration 和 Diagrams 工具集始终会加载。

已知限制： 渐进式发现依赖 MCP notifications/tools/list_changed 通知，告知客户端有新工具已注册。Claude Code 目前尚未处理此通知（anthropics/claude-code#4118），因此动态启用的工具集不会显示。使用 Claude Code 时，请使用静态模式（EnableDynamicToolsets: false）。

安全性

查询验证

每个查询都会使用 Microsoft 官方的 TSql180Parser 解析为抽象语法树（AST），并且必须通过以下规则：

• 仅允许单条语句 — 拒绝多条语句
• 仅允许 SELECT — 禁止 INSERT、UPDATE、DELETE、DROP、EXEC、CREATE、ALTER 及所有其他语句类型
• 禁止 SELECT INTO — 防止通过 SELECT 创建表
• 禁止访问外部数据 — 禁止 OPENROWSET（包括 BULK、Cosmos DB 和内部变体）、OPENQUERY、OPENDATASOURCE、OPENXML
• 禁止链接服务器 — 拒绝四段式名称引用
• 禁止 MAXRECURSION 提示 — 防止覆盖默认递归限制
• 允许跨数据库查询 — 按设计允许使用三段式名称；安全边界是服务器，而非数据库。若要限制为单个数据库，请限制登录名的权限。

由于验证针对解析后的 AST 执行，因此能够正确处理字符串匹配方式无法应对的边缘情况：注释中的关键字、字符串字面量、嵌套块注释和编码技巧。

参数拦截

诊断存储过程通过白名单中的过程名称执行，并拦截可能导致写入的参数：

• First Responder Kit — 拦截所有 @Output* 参数（防止将结果写入服务器表）
• DarlingData — 拦截日志和输出参数（防止创建表和保留数据）
• sp_WhoIsActive — 拦截 @destination_table、@return_schema、@schema、@help

速率限制

所有工具执行都会受到并发限制（MaxConcurrentQueries，默认值为 5）和吞吐量限制（MaxQueriesPerMinute，默认值为 60）。超出限制的请求会被拒绝，并返回重试提示。

连接安全

尽可能使用 Windows Authentication 或 Azure Managed Identity，以避免在配置文件中存储凭据。必须使用 SQL Authentication 时，请使用环境变量覆盖项在运行时注入凭据。有关凭据存储和连接字符串加密等详细指南，请参阅 SECURITY.md。

已知风险

• 本项目依赖 Microsoft 官方的 MCP C# SDK（ModelContextProtocol NuGet 包，版本为 1.3.0）。由于 MCP 框架负责处理所有协议 I/O，其中的任何漏洞都会直接影响本应用的安全边界。请关注该包的更新，并在新版本发布后升级。
• SQL Server 查询返回的数据可能包含针对 AI 的恶意提示词注入。这是使用 AI 时普遍存在的风险，本项目无法缓解。请遵循 AI 安全最佳实践，并仅连接到可信的数据源。

贡献

欢迎贡献。有关架构详情、开发环境设置、测试说明以及添加新工具的指南，请参阅 CONTRIBUTING.md。

许可证

MIT