HsSqlAgent.Server 1.10.0

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher. 
dotnet add package HsSqlAgent.Server --version 1.10.0
                    


                    

                
NuGet\Install-Package HsSqlAgent.Server -Version 1.10.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="HsSqlAgent.Server" Version="1.10.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="HsSqlAgent.Server" Version="1.10.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="HsSqlAgent.Server" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add HsSqlAgent.Server --version 1.10.0
                    


                    

                
#r "nuget: HsSqlAgent.Server, 1.10.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package HsSqlAgent.Server@1.10.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=HsSqlAgent.Server&version=1.10.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=HsSqlAgent.Server&version=1.10.0
                    


                            Install as a Cake Tool

hs-sql-agent

The high-performance MCP server for instant SQL interaction and secure enterprise governance. <img src="miscellaneous\coverImage.png" />

License: Apache 2.0 Docker CodeQL Advanced Tests Deploy on Zeabur

hs-sql-agent is an HTTP MCP server for relational databases (SQLite, PostgreSQL, MySQL, SQL Server, Oracle, Firebird) with a built-in Admin Panel for governance.

🤔 Why hs-sql-agent?

Most "Chat with your Data" tools ask the LLM to write raw SQL — a recipe for hallucinations, dialect confusion, and injection risks. hs-sql-agent takes a structured approach: the AI can write SQL, the server parses it into structured definitions, validates the result, and rebuilds the final query through the SQL builder before execution. Zero hallucinated syntax, zero direct string injection into the database.

  • Structured SQL Pipeline — The AI can write SQL, but the server parses it into structured definitions, validates it, and rebuilds the final query through the SQL builder before execution.
  • Universal DB Support — One agent for SQLite, PostgreSQL, MySQL, SQL Server, Oracle, and Firebird. The same MCP endpoint switches engines transparently.
  • Enterprise Governance — Built-in Admin Web UI, key-level connection mapping, table whitelisting, per-key CORS, rate limiting, and full audit logs.
  • Semantic Layer — Map cryptic legacy column names to business-friendly labels so the LLM understands your schema.

Where to use it

Use case Description
Cursor / Claude Desktop Let devs query dev/test DBs in natural language from their AI IDE.
Multi-DB agents One MCP server per database, each secured with its own API key. The agent aggregates multiple MCP connections to seamlessly orchestrate workflows across PostgreSQL, MySQL, and Oracle.
Enterprise chatbots Connect internal AI agents to ERP/CRM systems with table-level permission isolation.
Legacy modernization Bridge modern AI to decades-old databases via the semantic layer.

🚀 Quick Start

cp .env.example .env      # set HMAC_KEY and JWT_KEY (32+ bytes)
docker compose up -d       # http://localhost:8080

📦 NuGet for Existing .NET APIs

Already have an ASP.NET Core API? Embed the full MCP SQL Agent + Admin UI in minutes:

dotnet add package HsSqlAgent.Server

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

The Admin UI is embedded in the DLL — no external files to deploy. See the NuGet Package guide for details.

📖 Documentation

Detailed docs are on the Wiki:

Topic Link
🚀 Getting Started Getting-Started
✨ Features Features
📘 MCP Tools MCP-Tools-Reference
🖥️ Admin Panel Admin-Panel
⚙️ Configuration Configuration
🐳 Deployment Deployment
🏠 Development Development
📡 API Reference API-Reference
❓ FAQ FAQ

SQL Execution Flow

flowchart TD
    LLM["LLM / MCP Client"] -->|Call tool with SQL| MCP["HsSqlAgent MCP Server"]
    MCP --> AUTH["Access key auth<br/>allowed tools + DB binding + table whitelist"]
    AUTH --> ROUTE{"Tool"}

    ROUTE -->|execute_query_sql(sql)| QPARSE["Parse SELECT SQL<br/>SqlDefinitionParser.ParseQuery"]
    QPARSE --> QDEF["QueryDefinition"]
    QDEF --> QVALID["DefinitionValidator<br/>+ table whitelist checks"]
    QVALID --> QBUILD["SQL builder / strategy compile"]
    QBUILD --> QEXEC["Execute SELECT"]
    QEXEC --> QRESULT["Rows / JSON result"]

    ROUTE -->|execute_dml_sql(sql)| DPARSE["Parse DML SQL<br/>SqlDefinitionParser.ParseDml"]
    DPARSE --> DDEF["DmlDefinition"]
    DDEF --> DVALID["DefinitionValidator<br/>+ table whitelist checks"]
    DVALID --> DRYRUN["Dry-run inside uncommitted transaction"]
    DRYRUN --> ELICIT["MCP Elicitation<br/>user approves in client UI"]
    ELICIT --> DECIDE{"User response"}
    DECIDE -->|Accept| DEXEC["Commit transaction"]
    DECIDE -->|Decline / Cancel| DROLLBACK["Rollback transaction"]

    QRESULT --> AUDIT["Async audit log"]
    DEXEC --> AUDIT
    DROLLBACK --> AUDIT

DML Approval Prompt

This is what the human-in-the-loop approval step looks like during execute_dml_sql:

<img src="miscellaneous/dml-approval-prompt.png" width="550" style="border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);" />

🤝 Contributing

See CONTRIBUTING.md and the Development wiki page.

📜 License

Apache License 2.0

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.10.0 46 7/4/2026
1.9.1 97 6/29/2026
1.9.0 93 6/28/2026
1.8.3 109 6/26/2026
1.8.2-alpha 99 6/2/2026
1.8.1-alpha 99 5/30/2026
1.8.0-alpha 99 5/30/2026