SqlToAi

SqlToAi

SqlToAi 是一款用于 Microsoft SQL Server 的本地 Model Context Protocol (MCP) 服务。 它为 MCP 客户端提供工具，用于检查架构、执行 SQL，以及比较查询结果和性能。该服务通过 stdio 运行，使用 .NET 10 构建。

功能

• 检查表、视图、例程、触发器、键、索引和对象引用。
• 将数据库架构导出为相互链接的 Markdown 文件，供离线阅读。
• 执行参数化查询和本地 .sql 脚本，包括 GO 批次。
• 测量 CPU 时间、耗时、读取次数和执行计划警告；将基准查询与候选查询进行比较，并检查缺失索引建议。
• 配置数据库访问级别，从仅架构访问到读写访问。
• 对字符串查询结果进行掩码处理，或将其替换为可逆的内存令牌；添加来自 SQL Server 或元数据数据库的表和列说明。

请参阅工具参考，了解参数和行为。

无需启动 MCP 服务即可导出架构：

.\SqlToAi.exe export-schema --database primary/DemoDB --output C:\Doku\Database

输出目录必须不存在或为空。导出内容包含架构详情和 SQL 定义，不包含业务记录、元数据说明或匿名化指示信息。失败时会返回非零退出代码，并保留已写入的文件。有关文件布局和重试行为，请参阅架构导出。

开始使用

对于下载的 Windows x64 软件包，请按照手动设置软件包说明操作（可执行文件旁附有该文件，名为 README.md）。选择 ZIP 文件进行解压并自行启动可执行文件，或选择 MCPB，将同一可执行文件安装为客户端启动项。两种方式都包含运行所需的全部内容，无需单独安装 .NET 运行时。在任一方式启动服务之前，都必须根据提供的模板手动创建 %LOCALAPPDATA%\SqlToAi\appsettings.json；安装软件包不会创建此文件。更新会保留单独的用户设置和日志，但从旧版单服务设置升级属于破坏性变更：首次启动新版之前，必须手动将旧配置节和提供程序设置移至具名服务下，为数据库授权指定数据库，并重命名环境变量。不会自动迁移；请遵循升级说明。

你需要 .NET 10 SDK、可连接的 SQL Server，以及具备所用工具所需权限的数据库登录名。

构建

dotnet build SqlToAi.slnx -c Release

Windows 可执行文件和配置会写入 src/SqlToAi/bin/Release/net10.0/。

配置数据库访问

启动 SqlToAi 之前，必须根据随附模板手动创建 %LOCALAPPDATA%\SqlToAi\appsettings.json。主模板未配置数据库授权或可用凭据；请谨慎设置服务器、凭据和访问列表。单独的 DemoDB 示例包含虚构的本地演示凭据和 ReadWrite 访问权限。仅在本地测试数据库中手动选择该示例；宿主不会自动加载它。

对于 Windows 身份验证和字符串掩码，请按以下内容配置 Databases 和 Servers 节，并替换为你的数据库和服务器：

"Databases": {
  "CacheTtlSeconds": 300,
  "ReadWrite": [],
  "ReadWriteAnonymized": [],
  "ReadOnly": [],
  "ReadOnlyAnonymized": ["primary/ReportingDB"],
  "SchemaOnly": []
},
"Servers": {
  "primary": {
    "Server": "localhost\\MSSQLSERVER2022",
    "IntegratedSecurity": true,
    "ConnectTimeoutSeconds": 30
  }
}

这些配置节应位于现有的 SqlToAi 对象内。请将 Anonymizer.Enabled 保持为 true。未列入访问列表的数据库会被拒绝访问。除应用程序访问列表外，还应使用权限受限的 SQL Server 登录名。

请参阅配置，了解手动设置、SQL 身份验证、逐字段环境变量覆盖、元数据和日志记录。

连接 MCP 客户端

在客户端的 MCP 配置中添加 stdio 服务条目，并使用可执行文件的绝对路径。具体配置位置取决于客户端。

{
  "mcpServers": {
    "sql-to-ai": {
      "command": "C:\\Path\\To\\SqlToAi\\src\\SqlToAi\\bin\\Release\\net10.0\\SqlToAi.exe",
      "args": []
    }
  }
}

从命令行检查工具

Set-Location src/SqlToAi/bin/Release/net10.0
.\SqlToAi.exe query --help
.\SqlToAi.exe query sql_list_databases --server primary
.\SqlToAi.exe query sql_execute_query --database primary/ReportingDB --query "SELECT TOP 5 name FROM sys.tables"

工具结果包含 Markdown 或 JSON。成功的 CLI 调用会将数据写入标准输出； 通知和错误会写入标准错误。调用失败时退出代码为 1。有关导出和部署，请参阅 开发和 CLI 用法。

防护和限制

只读执行使用 SQL 语句验证和回滚事务。 ReadWrite 允许进行更改，并返回原始字符串结果；ReadWriteAnonymized 允许 进行更改，同时对查询和脚本结果应用配置的字符串遮蔽或令牌化。这些应用层检查 是对 SQL Server 权限的补充；它们不能取代权限。

对于 ReadOnlyAnonymized 和 ReadWriteAnonymized 数据库，字符串遮蔽会应用于查询 和脚本结果。数值、日期、架构定义、查询比较差异 样本以及执行计划内容仍可能可见。令牌在运行中的服务内可逆。这并不保证所有敏感数据都已 移除。

查询比较会检查架构、行数和不同集合之间的差异。它 无法确定行的顺序或重复项的数量。基准测试结果 反映所测量的执行情况，并不保证生产环境中的性能会有所提升。

应用程序和错误诊断功能仍处于启用状态。使用前请查看安全边界 和日志设置。

文档和开发

• 文档索引
• 配置和操作
• 安全和数据处理
• 工具参考
• 架构
• 构建、测试、CLI 和部署
• 支持和贡献指南
• 安全问题报告

使用 dotnet test SqlToAi.slnx 运行 xUnit v3 测试套件。

许可证

MIT。