hs-sql-agent

보안 SQL 액세스와 엔터프라이즈 거버넌스를 위한 고성능 MCP 서버입니다.

hs-sql-agent는 HTTP MCP 엔드포인트와 내장 Admin Panel을 통해 MCP 클라이언트를 SQLite, PostgreSQL, MySQL, SQL Server, Oracle, Firebird에 연결합니다.

왜 hs-sql-agent인가?

제한 없는 LLM 생성 SQL을 실행하는 대신, 서버는 지원되는 SQL을 구조화된 정의로 파싱하고 검증한 후, 공급자별 SQL 컴파일러를 통해 최종 문을 재구성합니다.

• 6가지 데이터베이스 공급자 — SQLite, PostgreSQL, MySQL, SQL Server, Oracle, Firebird.

• 거버넌스 액세스 — 키별 데이터베이스 바인딩, 테이블 화이트리스트, CORS, 속도 제한, 실행 정책.

• 안전한 DML — 트랜잭션 드라이런 후 MCP Elicitation을 통한 명시적 인간 승인.

• Admin Panel — 데이터베이스, 키, 역할, 사용자 정의 도구, 감사 기록, 런타임 정책 관리.

• 엔터프라이즈 준비 — OIDC SSO, TOTP MFA, 감사 보존, Prometheus 메트릭, OTLP, 웹훅/SIEM 전달.

• 시맨틱 메타데이터 — 테이블 및 컬럼 동의어, 관계, 스키마 검색을 위한 범위 지정 메트릭 메타데이터.

SQL 지원은 의도적으로 제한됩니다. 지원되지 않는 구문은 의미를 조용히 바꾸는 대신 거부됩니다. 지원되는 SQL 계약은 MCP Tools Reference를 참조하세요.

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

Admin Panel을 http://localhost:8080에서 엽니다. 구성 옵션과 프로덕션 배포 지침은 Wiki에 문서화되어 있습니다.

MCP 클라이언트와 함께 사용

Admin Panel에서 MCP 키를 생성합니다. 키 대화상자는 일반 텍스트 비밀을 한 번만 표시하고 Claude Desktop, Cursor, 일반 Streamable HTTP 클라이언트용 구성을 생성합니다.

MCP_PUBLIC_ENDPOINT를 외부에서 접근 가능한 MCP URL(/mcp 포함)로 설정합니다. 클라이언트 호환성, 온보딩, DML Elicitation 요구 사항은 MCP client onboarding을 참조하세요.

기존 .NET API용 NuGet

ASP.NET Core 애플리케이션에 MCP SQL Agent와 선택적 Admin UI를 포함합니다:

dotnet add package HsSqlAgent.Server

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

구성 및 배포 세부 사항은 NuGet Package guide를 참조하세요.

SQL 실행 방식

1. MCP 키를 인증하고 해당 데이터베이스, 테이블, 정책 범위를 적용합니다.

2. 지원되는 SQL을 구조화된 정의로 파싱합니다.

3. 정의를 검증하고 구성된 데이터베이스 공급자용으로 컴파일합니다.

4. 구성된 제한 내에서 쿼리를 실행합니다.

5. DML의 경우 트랜잭션에서 드라이런하고 커밋 전에 MCP Elicitation을 통해 인간 승인을 요구합니다.

사용자 정의 SQL 도구는 기본 제공 도구와 동일한 파서, 검증, 액세스 정책, 실행 제한을 통과합니다. 수명 주기, 매개변수, 게시 규칙은 Admin Panel guide에 문서화되어 있습니다.

문서

SQL 실행 흐름

DML 승인 프롬프트

execute_dml_sql 중 인간 개입 승인 단계는 다음과 같습니다:

기여

CONTRIBUTING.md 및 개발 가이드를 참조하세요.

라이선스

Apache License 2.0