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, Lock, Memory и т.д.)

• Проверка работоспособности — комплексная диагностика сервера: медленные запросы, взаимоблокировки, блокировки, статистика ожиданий и аналитика

• Потоковая передача в реальном времени — трансляция захваченных событий в течение заданного времени

• Безопасен для продакшена — автоматическое исключение шума (sp_reset_connection, операторы SET, трассировочные запросы)

• Операции с базами данных — список таблиц, описание схем, запросы данных, вставка, обновление и удаление таблиц

• Оптимизировано для ИИ — структурированный вывод JSON с опциональным форматированием Markdown

Related MCP server: mysql-mcp-server

Требования

• 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

Сетевой доступ: флаг -i обязателен для stdio-транспорта. Используйте --network host, чтобы контейнер мог подключиться к SQL Server на вашей хост-машине. Для удаленного SQL Server опустите --network host и используйте доступное имя узла в строке подключения.

Строка подключения: задайте SQL_SENTINEL_CONNECTION_STRING через -e. Все инструменты читают строку подключения из этой переменной окружения.

Вариант 2: глобальный инструмент .NET (NuGet)

Требуется .NET 9 SDK или новее.

dotnet tool install -g Neofenyx.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

Жизненный цикл сеанса

Получение событий

Диагностика

Разрешения

Операции с базами данных

Примеры использования

Быстрый отладочный сеанс

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/

Сервер взаимодействует через stdio по протоколу MCP. Подключите его к MCP-клиенту (Claude Desktop, Claude Code и т.д.) для интерактивного использования.

Использование отладочного API

Проект API предоставляет REST-обертку для всех инструментов MCP с 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

• Автоматическое обнаружение инструментов — инструменты MCP обнаруживаются в сборке через WithToolsFromAssembly()

• Префикс сеансов XE — всем созданным сеансам присваивается префикс mcp_sentinel_

• Две формы событий — стандартные события (query, login, recompile) с типизированными полями и события с XML-нагрузкой (deadlock, blocking), разбираемые из XML расширенных событий

Добавление нового инструмента MCP

1. Создайте метод public static в соответствующем файле в Tools/ (или создайте новый файл)

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. Убедитесь, что сеанс РАБОТАЕТ (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