SQL Sentinel MCP Server

SQL Sentinel MCP Server

一个可用于生产环境的 MCP（Model Context Protocol）服务，用于 SQL Server 监控、诊断和数据库操作。基于 .NET 9 和 Microsoft.Data.SqlClient 构建，支持原生 SQL Server 连接，无需 ODBC 驱动。

功能

• 会话管理 — 创建、启动、停止、删除和列出扩展事件会话
• 智能筛选 — 按应用程序、数据库、用户、持续时间、主机和文本模式筛选
• 查询指纹 — 规范化查询，并将仅字面值不同的相似查询分组
• 序列分析 — 跟踪执行顺序、时间间隔和累计持续时间
• 死锁检测 — 捕获并分析 XML 死锁报告，包含受害者和进程详情
• 阻塞分析 — 监控阻塞进程事件，包含等待资源和 SQL 文本
• 等待统计信息 — 直接查询 sys.dm_os_wait_stats，并按类型分类（CPU、I/O、锁、内存等）
• 健康检查 — 全面的服务器诊断：慢查询、死锁、阻塞、等待统计信息和洞察
• 实时流式传输 — 在指定时长内流式传输捕获的事件
• 生产环境安全 — 自动排除噪声（sp_reset_connection、SET 语句、跟踪查询）
• 数据库操作 — 列出表、描述架构、查询数据、插入、更新和删除表
• 针对 AI 优化 — 结构化 JSON 输出，并支持可选的 Markdown 格式

要求

• SQL Server 2012+，并启用扩展事件（默认启用）
• 所需权限：

  GRANT ALTER ANY EVENT SESSION TO [your_login];
  GRANT VIEW SERVER STATE TO [your_login];
  

• 如需检测被阻塞进程：

  EXEC sp_configure 'show advanced options', 1;
  RECONFIGURE;
  EXEC sp_configure 'blocked process threshold', 5;
  RECONFIGURE;
  

安装

选项 1：Docker（推荐）

无需 .NET SDK。适用于安装了 Docker 的任何系统。

docker pull ghcr.io/tkmawarire/sql-sentinel-mcp:latest

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "sql-sentinel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host",
               "-e", "SQL_SENTINEL_CONNECTION_STRING=Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=true",
               "ghcr.io/tkmawarire/sql-sentinel-mcp:latest"]
    }
  }
}

Claude Code

claude mcp add sql-sentinel \
  -e SQL_SENTINEL_CONNECTION_STRING="Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=true" \
  -- docker run -i --rm --network host \
  -e SQL_SENTINEL_CONNECTION_STRING \
  ghcr.io/tkmawarire/sql-sentinel-mcp:latest

网络访问：stdio 传输需要 -i 标志。使用 --network host，让容器能够连接主机上的 SQL Server。对于远程 SQL Server，请省略 --network host，并在连接字符串中使用可访问的主机名。

连接字符串：通过 -e 设置 SQL_SENTINEL_CONNECTION_STRING。所有工具均从此环境变量读取连接字符串。

选项 2：.NET 全局工具（NuGet）

需要 .NET 9 SDK 或更高版本。

dotnet tool install -g SQLSentinel.Mcp

{
  "mcpServers": {
    "sql-sentinel": {
      "command": "sql-sentinel-mcp",
      "env": {
        "SQL_SENTINEL_CONNECTION_STRING": "Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=true"
      }
    }
  }
}

选项 3：从源代码构建

git clone https://github.com/tkmawarire/sql-sentinel.git
cd sql-sentinel
dotnet build

直接运行：

dotnet run --project SqlServer.Profiler.Mcp/

或发布为独立的单文件二进制：

# Windows
dotnet publish SqlServer.Profiler.Mcp/ -c Release -r win-x64 --self-contained

# Linux
dotnet publish SqlServer.Profiler.Mcp/ -c Release -r linux-x64 --self-contained

# macOS (Apple Silicon)
dotnet publish SqlServer.Profiler.Mcp/ -c Release -r osx-arm64 --self-contained

# macOS (Intel)
dotnet publish SqlServer.Profiler.Mcp/ -c Release -r osx-x64 --self-contained

输出将位于 bin/Release/net9.0/{runtime}/publish/

连接字符串

所有工具均从 SQL_SENTINEL_CONNECTION_STRING 环境变量读取连接字符串。在启动服务前设置一次：

export SQL_SENTINEL_CONNECTION_STRING="Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=false;Encrypt=true"

SQL 身份验证：

Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=false;Encrypt=true

Windows 身份验证：

Server=localhost;Database=master;Integrated Security=true;TrustServerCertificate=false;Encrypt=true

**注意：**仅在使用自签名证书的开发环境中使用 TrustServerCertificate=true。 在生产环境中，始终使用 TrustServerCertificate=false 和有效的 SSL 证书。

Azure SQL：

Server=yourserver.database.windows.net;Database=yourdb;User Id=user;Password=password;Encrypt=true

MCP 工具参考

会话生命周期

工具	描述
sqlsentinel_create_session	创建带筛选条件的扩展事件会话（未启动）
sqlsentinel_start_session	启动现有会话的事件捕获
sqlsentinel_stop_session	停止捕获；保留事件
sqlsentinel_drop_session	删除会话并丢弃所有事件
sqlsentinel_list_sessions	列出所有由 MCP 创建的会话及其状态和缓冲区用量
sqlsentinel_quick_capture	一步创建并启动会话

事件检索

工具	描述
sqlsentinel_get_events	检索捕获的事件，支持筛选、排序和去重
sqlsentinel_get_stats	按指纹、数据库、应用或登录名分组汇总统计数据
sqlsentinel_analyze_sequence	分析查询执行序列及其耗时和间隔
sqlsentinel_get_connection_info	列出数据库、应用、登录名、会话和阻塞信息
sqlsentinel_stream_events	在指定时长内实时捕获事件（1–300s）

诊断

工具	描述
sqlsentinel_get_deadlocks	检索死锁事件，包括受害者、进程、锁和 SQL 文本
sqlsentinel_get_blocking	检索被阻塞的进程事件，包括等待资源和 SQL 文本
sqlsentinel_get_wait_stats	按类型查询 sys.dm_os_wait_stats（无需会话）
sqlsentinel_health_check	综合报告：慢查询、死锁、阻塞、等待统计信息和洞察

权限

工具	描述
sqlsentinel_check_permissions	检查当前登录名的权限和阻塞进程阈值配置
sqlsentinel_grant_permissions	向登录名授予所需权限（需要 sysadmin）

数据库操作

工具	描述
sqlsentinel_list_tables	列出数据库中的所有用户表（包含架构名）
sqlsentinel_describe_table	详细的表架构：列、索引、约束和外键
sqlsentinel_create_table	通过 CREATE TABLE 语句创建新表
sqlsentinel_insert_data	通过 INSERT 语句插入数据
sqlsentinel_read_data	执行 SELECT 查询并返回结果
sqlsentinel_update_data	通过 UPDATE 语句更新数据
sqlsentinel_drop_table	通过 DROP TABLE 语句删除表

使用示例

快速调试会话

Agent: sqlsentinel_quick_capture(
    sessionName: "debug_api",
    applications: "MyWebApp",
    minDurationMs: 100
)

// User triggers the slow operation

Agent: sqlsentinel_get_events(
    sessionName: "debug_api",
    sortBy: "DurationDesc",
    limit: 20
)

Agent: sqlsentinel_drop_session(sessionName: "debug_api")

查找 N+1 查询

Agent: sqlsentinel_quick_capture(
    sessionName: "n_plus_one_check",
    databases: "OrdersDB"
)

// User loads a page

Agent: sqlsentinel_get_stats(
    sessionName: "n_plus_one_check",
    groupBy: "QueryFingerprint"
)

// Look for queries with high execution counts

跟踪特定操作

Agent: sqlsentinel_analyze_sequence(
    sessionName: "my_session",
    correlationId: "order-12345",
    responseFormat: "Markdown"
)

死锁检测

Agent: sqlsentinel_quick_capture(
    sessionName: "deadlock_monitor",
    eventTypes: "Deadlock"
)

// Wait for deadlocks to occur

Agent: sqlsentinel_get_deadlocks(
    sessionName: "deadlock_monitor",
    responseFormat: "Markdown"
)

阻塞分析

Agent: sqlsentinel_quick_capture(
    sessionName: "blocking_check",
    eventTypes: "BlockedProcess"
)

// Requires: sp_configure 'blocked process threshold', 5

Agent: sqlsentinel_get_blocking(
    sessionName: "blocking_check",
    responseFormat: "Markdown"
)

服务健康检查

Agent: sqlsentinel_health_check(
    sessionName: "my_session",
    slowQueryThresholdMs: 1000,
    responseFormat: "Markdown"
)

数据库操作

Agent: sqlsentinel_list_tables()

Agent: sqlsentinel_describe_table(
    name: "dbo.Products"
)

Agent: sqlsentinel_read_data(
    sql: "SELECT TOP 10 * FROM dbo.Products ORDER BY CreatedDate DESC"
)

等待统计信息（无需会话）

Agent: sqlsentinel_get_wait_stats(
    topN: 20,
    responseFormat: "Markdown"
)

查询指纹

查询会经过规范化，以便将相似查询归为一组：

-- These become one fingerprint:
SELECT * FROM Users WHERE id = 123
SELECT * FROM Users WHERE id = 456

-- Fingerprint: abc123:SELECT * FROM Users WHERE id = ?
-- Execution count: 2

噪声过滤

默认排除的模式（当 excludeNoise=true 时）：

• sp_reset_connection — 连接池重置
• SET TRANSACTION ISOLATION LEVEL — 会话设置
• SET NOCOUNT、SET ANSI_* — 客户端配置
• sp_trace_*、fn_trace_* — 跟踪系统查询

支持的事件类型

SqlBatchCompleted、RpcCompleted、SqlStatementCompleted、SpStatementCompleted、Attention、ErrorReported、Deadlock、BlockedProcess、LoginEvent、SchemaChange、Recompile、AutoStats

项目结构

sql-profiler-mcp/
├── .github/
│   └── workflows/
│       ├── docker.yml                     # Build & push multi-arch Docker images
│       └── publish-mcp-registry.yml       # Publish NuGet + MCP registry
├── .mcp/
│   └── server.json                        # MCP manifest (NuGet + OCI packages)
├── SqlServer.Profiler.Mcp/                # Main MCP server (stdio transport)
│   ├── SqlServer.Profiler.Mcp.csproj
│   ├── Program.cs                         # Entry point, DI setup, MCP config
│   ├── Models/
│   │   ├── ProfilerModels.cs              # Records, enums, data models
│   │   └── DbOperationResult.cs           # Result model for CRUD operations
│   ├── Services/
│   │   ├── ProfilerService.cs             # Core Extended Events logic
│   │   ├── QueryFingerprintService.cs     # SQL normalization & fingerprinting
│   │   ├── WaitStatsService.cs            # DMV-based wait stats analysis
│   │   ├── SessionConfigStore.cs          # In-memory session config storage
│   │   └── EventStreamingService.cs       # Real-time event streaming
│   ├── Utilities/
│   │   └── SqlInputValidator.cs           # SQL input validation & escaping
│   └── Tools/
│       ├── SessionManagementTools.cs      # Session lifecycle tools (6)
│       ├── EventRetrievalTools.cs         # Event retrieval tools (5)
│       ├── DiagnosticTools.cs             # Diagnostic tools (4)
│       ├── PermissionTools.cs             # Permission tools (2)
│       └── DatabaseTools.cs               # Database CRUD tools (7)
├── SqlServer.Profiler.Mcp.Api/            # Debug REST API (Swagger on port 5100)
│   ├── SqlServer.Profiler.Mcp.Api.csproj
│   ├── Program.cs
│   ├── Controllers/
│   │   └── ProfilerController.cs
│   ├── Models/
│   │   └── RequestModels.cs
│   └── appsettings.json
├── SqlServer.Profiler.Mcp.Cli/            # Debug CLI (REPL + script mode)
│   ├── SqlServer.Profiler.Mcp.Cli.csproj
│   └── Program.cs
├── SqlServer.Profiler.Mcp.Tests/          # xUnit tests for core MCP library (228 tests)
│   └── ...
├── SqlServer.Profiler.Mcp.Api.Tests/      # xUnit tests for API project (29 tests)
│   └── ...
├── Dockerfile                             # Multi-stage build (bookworm-slim)
├── .dockerignore
├── SqlServer.Profiler.Mcp.slnx           # Solution file
├── CLAUDE.md
├── CONTRIBUTING.md
└── README.md

开发

先决条件

• .NET 9 SDK
• SQL Server 2012+ 实例（本地、Docker 或远程）
• Docker（可选，用于容器构建）

克隆并构建

git clone https://github.com/tkmawarire/sql-sentinel.git
cd sql-sentinel
dotnet restore
dotnet build

在本地运行 MCP 服务

dotnet run --project SqlServer.Profiler.Mcp/

服务使用 MCP 协议通过 stdio 通信。将其连接到 MCP 客户端（Claude Desktop、Claude Code 等）即可进行交互式使用。

使用调试 API

API 项目为所有 MCP 工具提供 REST 封装，并提供 Swagger UI 以便手动测试。

dotnet run --project SqlServer.Profiler.Mcp.Api/

• Swagger UI：http://localhost:5100/
• 通过环境变量 SQL_SENTINEL_CONNECTION_STRING 配置连接字符串

使用调试 CLI

CLI 项目提供交互式 REPL 和脚本模式，可直接测试工具。

# Interactive REPL mode
dotnet run --project SqlServer.Profiler.Mcp.Cli/

# List all available tools
dotnet run --project SqlServer.Profiler.Mcp.Cli/ list

# Get help for a specific tool
dotnet run --project SqlServer.Profiler.Mcp.Cli/ help sqlsentinel_quick_capture

# Execute a single tool
dotnet run --project SqlServer.Profiler.Mcp.Cli/ call sqlsentinel_list_sessions

运行前设置 SQL_SENTINEL_CONNECTION_STRING 环境变量。

Docker 构建

docker build -t sql-sentinel-mcp:test .
docker run -i --rm --network host sql-sentinel-mcp:test

架构

关键模式

• 通过 Microsoft.Extensions.Hosting 实现依赖注入
• stdio 传输 — stdout 专用于 MCP 协议；所有日志都写入 stderr
• 工具自动发现 — 通过 WithToolsFromAssembly() 从程序集发现 MCP 工具
• XE 会话前缀 — 所有创建的会话都以 mcp_sentinel_ 为前缀
• 两种事件形态 — 标准事件（查询、登录、重新编译）包含类型化字段；XML 负载事件（死锁、阻塞）则从 Extended Events XML 中解析

添加新的 MCP 工具

1. 在 Tools/ 下的适当文件中创建一个 public static 方法（或创建新文件）
2. 使用 [McpServerTool(Name = "sqlsentinel_your_tool")] 和 [Description("...")] 修饰该方法
3. 使用 [Description("...")] 属性添加参数——这些参数会成为工具的输入架构
4. 通过方法参数注入服务（例如 IProfilerService、IWaitStatsService）
5. 返回字符串（JSON 或 Markdown）——框架会处理 MCP 响应封装

[McpServerTool(Name = "sqlsentinel_example")]
[Description("Description shown to AI agents")]
public static async Task<string> Example(
    IProfilerService profilerService,
    [Description("Optional filter")] string? filter = null)
{
    var connectionString = ConnectionStringResolver.Resolve();
    // Implementation
    return JsonSerializer.Serialize(result);
}

故障排除

创建会话时出现“Permission denied”

GRANT ALTER ANY EVENT SESSION TO [your_login];
GRANT VIEW SERVER STATE TO [your_login];

“Login failed”

• 检查连接字符串凭据
• 对于 Windows 身份验证，确保进程以正确的用户身份运行
• 对于 Azure SQL，确保防火墙允许你的 IP

未捕获到事件

1. 确认会话处于 RUNNING 状态（sqlsentinel_list_sessions）
2. 检查筛选条件是否过于严格
3. 确认目标数据库/应用正在生成查询
4. 检查 minDurationMs 是否筛掉了所有内容

没有死锁事件

• 确保会话创建时设置了 eventTypes: "Deadlock"
• 会话运行期间必须实际发生死锁

没有阻塞事件

• 确保已配置 blocked process threshold：sp_configure 'blocked process threshold', 5
• 确保会话创建时设置了 eventTypes: "BlockedProcess"
• 阻塞必须超过配置的阈值（秒）

读取事件超时

包含大量事件的大型环形缓冲区可能需要较长时间解析。可以使用：

• 时间筛选器缩小时间范围
• 如有需要，在代码中增加命令超时时间

安全说明

• SQL_SENTINEL_CONNECTION_STRING 环境变量包含凭据——请妥善保护
• 不要让会话在生产环境中无限期运行
• 查询文本可能包含敏感数据
• 仅授予所需的最低权限

贡献

请参阅 CONTRIBUTING.md，了解提交问题和拉取请求的指南。

许可证

MIT