hs-sql-agent
Servidor MCP C# SQL Agent com entrada de SQL bruto, validação estrita de AST e Admin UI incorporada. Elimina alucinações de LLM e riscos de segurança em 6 grandes bancos de dados.
Documentação
hs-sql-agent
Um servidor MCP de alta performance para acesso seguro a SQL e governança empresarial.
hs-sql-agent conecta clientes MCP a SQLite, PostgreSQL, MySQL, SQL Server, Oracle e Firebird por meio de um endpoint MCP HTTP e um Painel Administrativo integrado.
Por que hs-sql-agent?
Em vez de executar SQL gerado por LLM sem restrições, o servidor analisa o SQL suportado em definições estruturadas, valida-o e reconstrói a instrução final por meio de um compilador SQL específico do provedor.
- Seis provedores de banco de dados — SQLite, PostgreSQL, MySQL, SQL Server, Oracle e Firebird.
- Acesso governado — Vinculação de banco de dados por chave, lista de permissões de tabelas, CORS, limites de taxa e políticas de execução.
- DML seguro — Teste de execução transacional seguido de Elicitação MCP para aprovação humana explícita.
- Painel Administrativo — Gerencie bancos de dados, chaves, papéis, ferramentas personalizadas, registros de auditoria e políticas de execução.
- Pronto para empresas — SSO OIDC, MFA TOTP, retenção de auditoria, métricas Prometheus, OTLP e entrega via webhook/SIEM.
- Metadados semânticos — Sinônimos de tabelas e colunas, relacionamentos e metadados de métricas com escopo para descoberta de esquema.
O suporte a SQL é intencionalmente limitado: sintaxe não suportada é rejeitada em vez de ter seu significado alterado silenciosamente. Consulte a Referência de Ferramentas MCP para o contrato de SQL suportado.
Início Rápido
cp .env.example .env
# Set HMAC_KEY and JWT_KEY to unique secrets of at least 32 bytes.
docker compose up -d
Abra o Painel Administrativo em http://localhost:8080. Opções de configuração e orientações de implantação em produção estão documentadas na Wiki.
Uso com um cliente MCP
Crie uma chave MCP no Painel Administrativo. O diálogo de chave exibe o segredo em texto puro apenas uma vez e gera configuração para Claude Desktop, Cursor e clientes genéricos Streamable HTTP.
Defina MCP_PUBLIC_ENDPOINT para a URL MCP acessível externamente, incluindo /mcp. Para compatibilidade de clientes, integração e requisitos de Elicitação de DML, consulte Integração de clientes MCP.
NuGet para APIs .NET existentes
Embuta o Agente SQL MCP e a UI Administrativa opcional em um aplicativo ASP.NET Core:
dotnet add package HsSqlAgent.Server
builder.Services.AddHsSqlAgent(options => { ... });
app.UseHsSqlAgent(); // API only
// app.UseHsSqlAgent().ServeAdminUi(); // API and Admin UI
Consulte o Guia de Pacotes NuGet para detalhes de configuração e implantação.
Como a execução de SQL funciona
- Autentique a chave MCP e aplique seu escopo de banco de dados, tabelas e políticas.
- Analise o SQL suportado em uma definição estruturada.
- Valide a definição e compile-a para o provedor de banco de dados configurado.
- Execute consultas dentro dos limites configurados.
- Para DML, execute um teste em transação e exija aprovação humana por meio de Elicitação MCP antes do commit.
Ferramentas SQL personalizadas passam pelo mesmo analisador, validação, política de acesso e limites de execução que as ferramentas integradas. Regras de ciclo de vida, parâmetros e publicação estão documentadas no Guia do Painel Administrativo.
Documentação
| Tópico | Documentação |
|---|---|
| Introdução | Introdução |
| Configuração | Configuração |
| Painel Administrativo | Painel Administrativo |
| Ferramentas MCP e suporte a SQL | Referência de Ferramentas MCP |
| Segurança, OIDC e MFA | Governança de Segurança |
| Implantação e observabilidade | Implantação · Implantação Distribuída |
| API | Referência de API |
| Solução de problemas | Solução de problemas |
| Desenvolvimento | Desenvolvimento |
Fluxo de Execução de SQL
Prompt de Aprovação de DML
Esta é a aparência da etapa de aprovação humana no circuito durante execute_dml_sql:
Contribuindo
Consulte CONTRIBUTING.md e o Guia de Desenvolvimento.