hs-sql-agent

hs-sql-agent

Transforme SQL confiável em ferramentas MCP governadas para agentes de IA.

hs-sql-agent é uma fábrica de ferramentas SQL-para-MCP e fronteira de execução SQL governada de código aberto. Defina SQL parametrizado na Interface de Administração, publique-o como uma ferramenta MCP tipada e deixe que agentes de IA forneçam apenas os argumentos — sem escrever um novo método em C# ou reimplantar seu servidor MCP para cada operação de banco de dados.

Toda ferramenta publicada ainda passa pelo mesmo compilador SQL com falha segura, política por chave de banco/tabela, limites de execução, trilha de auditoria e controles de aprovação de DML Seguro. Ferramentas SQL brutas permanecem disponíveis para casos em que um agente realmente precisa de consultas ad-hoc flexíveis.

Ele suporta PostgreSQL, MySQL, SQL Server, Oracle, SQLite e Firebird e pode ser executado como o servidor completo de primeira parte com sua Interface de Administração ou ser incorporado a um aplicativo ASP.NET Core existente.

Publique SQL como uma ferramenta MCP

Em vez de ensinar o modelo a regenerar a mesma consulta toda vez, defina a forma do SQL uma única vez:

SELECT id, total, status
FROM orders
WHERE customer_id = {{ customerId }}
  AND status = {{ status }}

Declare customerId e status em Runtime → Ferramentas Personalizadas, teste o rascunho e publique-o. O hs-sql-agent expõe a definição publicada aos clientes MCP como uma ferramenta nomeada com um esquema de entrada JSON gerado.

O agente vê um contrato conceitualmente como:

get_customer_orders(
  customerId: number,
  status: string
)

O modelo SQL permanece definido pelo engenheiro. Os espaços reservados são apenas parâmetros de valor; identificadores e fragmentos SQL arbitrários não podem ser injetados por meio deles.

As ferramentas personalizadas publicadas podem ser ferramentas de Consulta ou DML. Ferramentas de consulta usam o mesmo compilador tipado e o caminho de política de acesso que a execução SQL integrada. Ferramentas DML usam o mesmo protocolo de pré-visualização → aprovação → revalidação → confirmação, incluindo transações atômicas de múltiplas instruções.

Por que o hs-sql-agent?

• Ferramentas Personalizadas SQL-para-MCP — Transforme modelos SQL revisados por engenheiros em ferramentas MCP descobríveis com parâmetros tipados, descrições, ciclo de vida de rascunho/teste/publicação, revisões, reversão e vínculo de banco de dados.
• Compilador SQL com falha segura — Sintaxe não suportada ou não comprovada é rejeitada em vez de ser silenciosamente reescrita com semântica diferente.
• Núcleo do compilador F# fechado — O SQL entra em uma AST de união discriminada fechada e avança por estágios de compilador parsed → bound → canonical → validated → executable infalsificáveis.
• Seis provedores de banco de dados — PostgreSQL, MySQL, SQL Server, Oracle, SQLite e Firebird com validação e redução cientes do provedor.
• DML Seguro — Pré-visualização de impacto somente leitura, desafio de aprovação de uso único, revalidação do conjunto de linhas no momento da confirmação e aprovação humana explícita por meio de Elicitação MCP ou um provedor de aprovação.
• Acesso governado — Vínculo de banco por chave, lista de permissões de tabelas, limites de taxa, limites de execução, funções, políticas e registros de auditoria.
• Hospedagem flexível — Execute o servidor empacotado e a Interface de Administração, use o host ASP.NET Core padrão ou componha integrações avançadas a partir de capacidades modulares.
• Observabilidade de produção — Métricas Prometheus, OpenTelemetry/OTLP, retenção de auditoria e entrega via webhook/SIEM.

O suporte a SQL é intencionalmente limitado por semântica comprovada. Consulte a Referência de Suporte SQL para o contrato atual.

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 a Interface de Administração em http://localhost:8080.

Para configurações de produção e opções de implantação, use a Referência de Configuração e o Guia de Implantação.

Uso com um cliente MCP

Defina MCP_PUBLIC_ENDPOINT para a URL MCP acessível externamente, incluindo /mcp, antes de emitir chaves de produção.

Em seguida, abra Runtime → Chaves MCP na Interface de Administração e emita uma chave. O diálogo único de Salvar e conectar gera configuração pronta para colar para Claude Desktop, Cursor, Visual Studio Code e clientes Streamable HTTP genéricos.

O segredo em texto simples é mostrado apenas uma vez. Consulte Integração de Cliente MCP para configuração do cliente, compatibilidade e requisitos de Elicitação DML.

Uso a partir do .NET

Para a mesma composição completa do host Docker oficial, instale HsSqlAgent.Hosting:

dotnet add package HsSqlAgent.Hosting

using HsSqlAgent.Hosting;

var builder = WebApplication.CreateBuilder(args);
builder.AddHsSqlAgentStandardHost();

var app = builder.Build();
app.UseHsSqlAgentStandardHost();

await app.RunAsync();

Use HsSqlAgent.Server diretamente apenas quando precisar de autenticação personalizada, ordenação de middleware, provedores de aprovação, interface ou composição de capacidades.

Consulte o Guia de Integração ASP.NET Core e o README do pacote HsSqlAgent.Hosting para o contrato completo de integração.

Como a execução SQL funciona

1. Autentique a chave MCP e estabeleça seu escopo de banco de dados, tabela, ferramenta e política de execução.
2. Para Ferramentas Personalizadas, resolva a definição publicada e renderize os parâmetros de valor declarados no modelo SQL definido pelo engenheiro.
3. Analise o SQL no modelo de compilador fechado e vincule a semântica da fonte.
4. Normalize e valide sintaxe, semântica, capacidades e política.
5. Renderize apenas um tipestado executável em SQL e parâmetros específicos do provedor.
6. Execute dentro dos limites de execução configurados.

O núcleo do compilador é livre de drivers de provedor: análise, validação, normalização, prova de capacidade, redução e renderização são mantidas separadas dos drivers de banco de dados e da execução em tempo de execução.

Para DML, o hs-sql-agent primeiro constrói uma pré-visualização de impacto somente leitura, vincula a aprovação ao plano validado e ao conjunto de linhas correspondente, exige aprovação humana explícita e revalida dentro da transação de confirmação antes de aplicar a mutação.

Ferramentas SQL personalizadas passam pelo mesmo compilador, política de acesso e limites de execução que as ferramentas integradas.

Fluxo de Execução SQL

Prompt de Aprovação DML

Documentação

O site de documentação é a fonte da verdade para orientação detalhada de configuração, integração, capacidade SQL, segurança e operações:

• Página Inicial da Documentação
• Início Rápido
• Ferramentas Personalizadas
• Integração ASP.NET Core
• Referência de Suporte SQL
• Visão Geral de Segurança

Contribuindo

Consulte CONTRIBUTING.md e o Fluxo de Arquitetura e Contribuição.

Licença

Licença Apache 2.0