# Hs Sql Agent

> A high-performance C# SQL Agent MCP that eliminates LLM hallucinations and security risks. Instead of letting the AI write raw SQL, it extracts parameters to generate deterministic, injection-free queries across 6 major databases—complete with a visual Admin UI and enterprise guardrails.

- **Type:** MCP server
- **Install:** `agentstack add mcp-tse-wei-chen-hs-sql-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tse-wei-chen](https://agentstack.voostack.com/s/tse-wei-chen)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [tse-wei-chen](https://github.com/tse-wei-chen)
- **Source:** https://github.com/tse-wei-chen/hs-sql-agent

## Install

```sh
agentstack add mcp-tse-wei-chen-hs-sql-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# hs-sql-agent
> **The high-performance MCP server for instant SQL interaction and secure enterprise governance.**

[](https://github.com/tse-wei-chen/hs-sql-agent/blob/main/LICENSE) [](https://github.com/tse-wei-chen/hs-sql-agent/actions/workflows/docker-publish.yml) [](https://www.nuget.org/packages/HsSqlAgent.Server) [](https://github.com/tse-wei-chen/hs-sql-agent/actions/workflows/codeql.yml) [](https://github.com/tse-wei-chen/hs-sql-agent/actions/workflows/test.yml) [](https://zeabur.com/templates/RFPWDU)

`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

```bash
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:

```bash
dotnet add package HsSqlAgent.Server
```

```csharp
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](https://github.com/tse-wei-chen/hs-sql-agent/wiki/NuGet-Package) for details.

## 📖 Documentation

Detailed docs are on the [Wiki](https://github.com/tse-wei-chen/hs-sql-agent/wiki):

| Topic | Link |
|-------|------|
| 🚀 Getting Started | [Getting-Started](https://github.com/tse-wei-chen/hs-sql-agent/wiki/Getting-Started) |
| ✨ Features | [Features](https://github.com/tse-wei-chen/hs-sql-agent/wiki/Features) |
| 📘 MCP Tools | [MCP-Tools-Reference](https://github.com/tse-wei-chen/hs-sql-agent/wiki/MCP-Tools-Reference) |
| 🖥️ Admin Panel | [Admin-Panel](https://github.com/tse-wei-chen/hs-sql-agent/wiki/Admin-Panel) |
| ⚙️ Configuration | [Configuration](https://github.com/tse-wei-chen/hs-sql-agent/wiki/Configuration) |
| 🐳 Deployment | [Deployment](https://github.com/tse-wei-chen/hs-sql-agent/wiki/Deployment) |
| 🏠 Development | [Development](https://github.com/tse-wei-chen/hs-sql-agent/wiki/Development) |
| 📡 API Reference | [API-Reference](https://github.com/tse-wei-chen/hs-sql-agent/wiki/API-Reference) |
| ❓ FAQ | [FAQ](https://github.com/tse-wei-chen/hs-sql-agent/wiki/FAQ) |

## SQL Execution Flow

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#18181B',
    'primaryTextColor': '#FAFAFA',
    'primaryBorderColor': '#27272A',
    'lineColor': '#52525B',
    'secondaryColor': '#27272A',
    'tertiaryColor': '#09090B',
    'mainBkg': '#09090B'
  }
}}%%

flowchart TD
    LLM(["Client :: LLM / MCP Client"])
    MCP["Server :: HsSqlAgent"]
    AUTH["Middleware :: AuthenticationAccess 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 SQLSqlDefinitionParser.ParseQuery"]
        QDEF["QueryDefinitionAST Structure Data"]
        QVALID["DefinitionValidatorRule Verification"]
        QBUILD["SQL Strategy CompilerCompile Strategy"]
        QEXEC["Execution EngineExecute 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 SQLSqlDefinitionParser.ParseDml"]
        DDEF["DmlDefinitionAST Structure Data"]
        DVALID["DefinitionValidatorRule Verification"]
        DRYRUN["Transaction Dry-runUncommitted State"]
        ELICIT["MCP ElicitationUser Approval Prompt"]
        DECIDE{" Action :: Decision"}
        DEXEC["Transaction :: CommitApply Changes"]
        DROLLBACK["Transaction :: RollbackDiscard 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 default fill:#18181B,stroke:#27272A,stroke-width:1px,color:#E4E4E7;
    classDef client fill:#FAFAFA,stroke:#FAFAFA,stroke-width:1px,color:#09090B;
    classDef server fill:#27272A,stroke:#3F3F46,stroke-width:1px,color:#F4F4F5;
    classDef auth fill:#09090B,stroke:#27272A,stroke-width:1px,color:#A1A1AA;
    classDef cond fill:#18181B,stroke:#FAFAFA,stroke-width:1.5px,color:#FAFAFA;
    
    classDef danger fill:#451A03,stroke:#7F1D1D,stroke-width:1px,color:#FCA5A5;
    classDef success fill:#022C22,stroke:#064E3B,stroke-width:1px,color:#86EFAC;

    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](CONTRIBUTING.md) and the [Development](https://github.com/tse-wei-chen/hs-sql-agent/wiki/Development) wiki page.

## 📜 License

[Apache License 2.0](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tse-wei-chen](https://github.com/tse-wei-chen)
- **Source:** [tse-wei-chen/hs-sql-agent](https://github.com/tse-wei-chen/hs-sql-agent)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tse-wei-chen-hs-sql-agent
- Seller: https://agentstack.voostack.com/s/tse-wei-chen
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.