Hs Sql Agent

The high-performance MCP server for instant SQL interaction and secure enterprise governance.

License: Apache 2.0 Docker NuGet 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
🖥️ Admin Panel	Admin-Panel
🔐 Security Governance	Security-Governance
🛠️ Troubleshooting	Troubleshooting
⚙️ Configuration	Configuration
🐳 Deployment	Deployment
🌐 Distributed Deployment	Distributed-Deployment
📘 MCP Tools	MCP-Tools-Reference
📡 API Reference	API-Reference
🏠 Development	Development

SQL Execution Flow

%%{init: { 'theme': 'neutral' }}%%
flowchart TD
    LLM(["Client :: LLM / MCP Client"])
    MCP["Server :: HsSqlAgent"]
    AUTH["Middleware :: Authentication<br/>Access Key | DB Binding | Whitelist"]
    ROUTE{"Gateway :: Router"}

    LLM -->|Call tool with SQL| MCP
    MCP --> AUTH
    AUTH --> ROUTE

    subgraph Query_Flow [" 🔍 Query Pipeline (SELECT) "]
        QPARSE["Parse Query SQL<br/>SqlDefinitionParser.ParseQuery"]
        QDEF["QueryDefinition<br/>AST Structure Data"]
        QVALID["DefinitionValidator<br/>Rule Verification"]
        QBUILD["SQL Strategy Compiler<br/>Compile Strategy"]
        QEXEC["Execution Engine<br/>Execute SELECT"]
        QRESULT(["Result :: Rows / JSON"])

        QPARSE --> QDEF
        QDEF --> QVALID
        QVALID --> QBUILD
        QBUILD --> QEXEC
        QEXEC --> QRESULT
    end

    subgraph DML_Flow [" ✏️ Mutation Pipeline (DML) "]
        DPARSE["Parse Mutation SQL<br/>SqlDefinitionParser.ParseDml"]
        DDEF["DmlDefinition<br/>AST Structure Data"]
        DVALID["DefinitionValidator<br/>Rule Verification"]
        DRYRUN["Transaction Dry-run<br/>Uncommitted State"]
        ELICIT["MCP Elicitation<br/>User Approval Prompt"]
        DECIDE{" Action :: Decision"}
        DEXEC["Transaction :: Commit<br/>Apply Changes"]
        DROLLBACK["Transaction :: Rollback<br/>Discard Changes"]

        DPARSE --> DDEF
        DDEF --> DVALID
        DVALID --> DRYRUN
        DRYRUN --> ELICIT
        ELICIT --> DECIDE
        DECIDE -->|Allowed| DEXEC
        DECIDE -->|Denied| DROLLBACK
    end

    ROUTE -->|execute_query_sql| QPARSE
    ROUTE -->|execute_dml_sql| DPARSE
    AUDIT[("Storage :: Async Audit Log")]

    QRESULT --> AUDIT
    DEXEC --> AUDIT
    DROLLBACK --> AUDIT

    classDef client fill:#f3f4f6,stroke:#374151,stroke-width:1px,color:#111827;
    classDef server fill:#e5e7eb,stroke:#4b5563,stroke-width:1px,color:#1f2937;
    classDef auth fill:#f9fafb,stroke:#9ca3af,stroke-width:1px,color:#4b5563;
    classDef cond fill:#ffffff,stroke:#111827,stroke-width:1.5px,color:#111827;
    classDef danger fill:#fee2e2,stroke:#ef4444,stroke-width:1px,color:#991b1b;
    classDef success fill:#dcfce7,stroke:#22c55e,stroke-width:1px,color:#166534;

    class LLM client;
    class MCP,AUDIT server;
    class AUTH auth;
    class ROUTE,DECIDE cond;
    class QRESULT,DEXEC success;
    class DROLLBACK danger;

DML Approval Prompt

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

🤝 Contributing

See CONTRIBUTING.md and the Development wiki page.

📜 License

Apache License 2.0