hs-sql-agent

Высокопроизводительный MCP-сервер для безопасного доступа к SQL и корпоративного управления.

hs-sql-agent подключает MCP-клиенты к SQLite, PostgreSQL, MySQL, SQL Server, Oracle и Firebird через HTTP MCP-эндпоинт и встроенную админ-панель.

Зачем нужен hs-sql-agent?

Вместо выполнения неограниченного SQL, сгенерированного LLM, сервер разбирает поддерживаемый SQL в структурированные определения, проверяет их и пересобирает итоговый запрос через компилятор SQL, специфичный для конкретного провайдера.

• Шесть провайдеров баз данных — SQLite, PostgreSQL, MySQL, SQL Server, Oracle и Firebird.

• Управляемый доступ — Привязка ключей к базам данных, белые списки таблиц, CORS, ограничения частоты запросов и политики выполнения.

• Безопасные DML — Транзакционный пробный запуск с последующей MCP-элиситацией для явного одобрения человеком.

• Админ-панель — Управление базами данных, ключами, ролями, пользовательскими инструментами, журналами аудита и политиками выполнения.

• Готовность к корпоративному использованию — OIDC SSO, TOTP MFA, хранение аудита, метрики Prometheus, OTLP и доставка через webhook/SIEM.

• Семантические метаданные — Синонимы таблиц и столбцов, связи и ограниченные метаданные метрик для обнаружения схемы.

Поддержка SQL намеренно ограничена: неподдерживаемый синтаксис отклоняется, а не молча меняет свой смысл. См. Справочник по MCP-инструментам для описания поддерживаемого контракта SQL.

Related MCP server: safedb-mcp

Быстрый старт

cp .env.example .env
# Set HMAC_KEY and JWT_KEY to unique secrets of at least 32 bytes.
docker compose up -d

Откройте админ-панель по адресу http://localhost:8080. Варианты конфигурации и рекомендации по развертыванию в продакшене описаны в Wiki.

Использование с MCP-клиентом

Создайте MCP-ключ в админ-панели. Диалог создания ключа отображает секрет в открытом виде один раз и генерирует конфигурацию для Claude Desktop, Cursor и универсальных Streamable HTTP-клиентов.

Установите MCP_PUBLIC_ENDPOINT на внешне доступный MCP-URL, включая /mcp. Требования к совместимости клиентов, онбордингу и элицитации DML см. в онбординге MCP-клиентов.

NuGet для существующих .NET API

Встраивайте MCP SQL Agent и опциональный админ-интерфейс в приложение ASP.NET Core:

dotnet add package HsSqlAgent.Server

builder.Services.AddHsSqlAgent(options => { ... });
app.UseHsSqlAgent();                    // API only
// app.UseHsSqlAgent().ServeAdminUi();  // API and Admin UI

См. руководство по пакету NuGet для деталей конфигурации и развертывания.

Как работает выполнение SQL

1. Аутентификация MCP-ключа и применение его области действия (база данных, таблицы, политики).

2. Разбор поддерживаемого SQL в структурированное определение.

3. Проверка определения и компиляция для настроенного провайдера базы данных.

4. Выполнение запросов в пределах настроенных лимитов.

5. Для DML — dry-run в транзакции и требование одобрения человеком через MCP Elicitation перед коммитом.

Пользовательские SQL-инструменты проходят через тот же парсер, проверку, политику доступа и лимиты выполнения, что и встроенные инструменты. Правила жизненного цикла, параметров и публикации описаны в руководстве по админ-панели.

Документация

Поток выполнения SQL

Запрос на одобрение DML

Так выглядит шаг одобрения с участием человека во время execute_dml_sql:

Участие в разработке

См. CONTRIBUTING.md и руководство по разработке.

Лицензия

Apache License 2.0