{"id":48571715,"url":"https://github.com/tse-wei-chen/hs-sql-agent","last_synced_at":"2026-05-03T11:05:27.158Z","repository":{"id":350008990,"uuid":"1200271184","full_name":"tse-wei-chen/hs-sql-agent","owner":"tse-wei-chen","description":"security, high accuracy sql agent mcp, include admin panel.","archived":false,"fork":false,"pushed_at":"2026-04-16T14:42:17.000Z","size":1584,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T16:31:57.366Z","etag":null,"topics":["mcp","mcp-server","mysql","nl2sql","postgres","postgresql","security","sql-agent","sqlite"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tse-wei-chen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T08:10:29.000Z","updated_at":"2026-04-16T14:41:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tse-wei-chen/hs-sql-agent","commit_stats":null,"previous_names":["tse-wei-chen/hs-sql-agent"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/tse-wei-chen/hs-sql-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tse-wei-chen%2Fhs-sql-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tse-wei-chen%2Fhs-sql-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tse-wei-chen%2Fhs-sql-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tse-wei-chen%2Fhs-sql-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tse-wei-chen","download_url":"https://codeload.github.com/tse-wei-chen/hs-sql-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tse-wei-chen%2Fhs-sql-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31964948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","mysql","nl2sql","postgres","postgresql","security","sql-agent","sqlite"],"created_at":"2026-04-08T15:00:14.166Z","updated_at":"2026-05-03T11:05:27.144Z","avatar_url":"https://github.com/tse-wei-chen.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚡ hs-sql-agent (High-Speed SQL Agent)\n\n\u003e **The high-performance MCP server designed for instant SQL interaction and secure enterprise governance.**\n\n![GitHub License](https://img.shields.io/github/license/tse-wei-chen/hs-sql-agent) [![Docker](https://github.com/tse-wei-chen/hs-sql-agent/actions/workflows/docker-publish.yml/badge.svg?event=release)](https://github.com/tse-wei-chen/hs-sql-agent/actions/workflows/docker-publish.yml) [![CodeQL Advanced](https://github.com/tse-wei-chen/hs-sql-agent/actions/workflows/codeql.yml/badge.svg?event=release)](https://github.com/tse-wei-chen/hs-sql-agent/actions/workflows/codeql.yml)\n\n`hs-sql-agent` is a robust HTTP MCP server for relational databases that bridges the gap between AI agents and your data. Unlike \"black-box\" generic SQL agents, `hs-sql-agent` provides a **High-Speed** execution engine with a **Built-in Admin Panel** to ensure every AI-generated query is managed, audited, and secure.\n\n---\n\n## ✨ Key Features\n\n### 🚀 High-Speed \u0026 Universal Access\n\n- **Instant Interaction**: Optimized C# backend ensures ultra-low latency for schema discovery and query execution.\n- **Universal Database Support**: One agent for all — supports `Sqlite`, `Postgres`, `Mysql`, `SqlServer`, `Oracle`, and `FireBird`.\n- **Structured Querying**: Powered by [SqlKata](https://sqlkata.com) for reliable and safe SQL construction.\n\n### 🛡️ Enterprise-Grade Governance\n\n- **Built-in Admin Web UI**: Manage your SQL Agent visually. No more manual JSON configuration files.\n- **Granular Security Control**:\n  - **Key-Level Mapping**: Assign specific database connections to individual API keys.\n  - **Lifecycle Management**: Effortlessly issue, list, or revoke access keys in real-time.\n- **Guardrails \u0026 Safety**:\n  - **Global Rate Limiting**: Prevent your database from being overwhelmed by AI loops or excessive traffic.\n  - **Comprehensive Audit Logs**: Track every single query with daily summaries and detailed execution history.\n- **Customization**:\n  - **Custom SQL Tools**: Define domain-specific SQL queries and DML statements to be exposed to the AI agent.\n\n---\n\n## 🖥️ Admin Panel\n\nThe built-in Admin Panel allows you to monitor operations and manage access without touching a single configuration file.\n\n\u003cimg width=\"1919\" height=\"1007\" alt=\"Screenshot 2026-05-02 234836\" src=\"https://github.com/user-attachments/assets/521be5e0-9589-49e6-90a3-3bf216618eed\" /\u003e\n\n_Operational Dashboard: Monitor keys and audit events in real-time._\n\n\u003cimg width=\"1919\" height=\"1009\" alt=\"Screenshot 2026-05-02 234907\" src=\"https://github.com/user-attachments/assets/487d9a03-93e4-4451-aed9-95512a9c44c4\" /\u003e\n\n_Granular Control: Assign specific database connections and tool subsets to each API key._\n\n\u003cimg width=\"1919\" height=\"1007\" alt=\"Screenshot 2026-05-02 234920\" src=\"https://github.com/user-attachments/assets/a779bf60-6c88-49c9-94f2-4fbc9d554ba6\" /\u003e\n\n_Low-Code Tools: Define custom SQL operations (e.g., `calculate_churn_rate`) for the AI agent._\n\n---\n\n## 🚀 Quick Start (Docker Compose)\n\nThe easiest way to run **HS SQL Agent** is using Docker Compose. This ensures your configuration is saved and your data persists across restarts.\n\n### 1. Setup Configuration\n\nCopy the example environment file:\n\n```bash\ncp .env.example .env\n```\n\nEdit the `.env` file to set your secret keys:\n\n```env\nHMAC_KEY=YourMcpHmacSecretKeyHere-AtLeast32Bytes!\nJWT_KEY=YourSuperSecretKeyHere-AtLeast32Bytes!\nJWT_ISS=HS-Agent\nJWT_AUD=HS-Agent-Users\nJWT_ACCESS_TOKEN_EXPIRATION_MINUTES=1\nJWT_REFRESH_TOKEN_EXPIRATION_DAYS=30\nRATE_LIMITING_PERMIT_LIMIT=0\nRATE_LIMITING_WINDOW_SECONDS=0\nRATE_LIMITING_QUEUE_LIMIT=0\n```\n\n\u003e [!IMPORTANT]\n\u003e **Security Note:** Never use example keys in production. Replace `HMAC_KEY` and `JWT_KEY` with unique, 32+ byte strings.\n\n### 2. Launch the Application\n\n```bash\ndocker-compose up -d\n```\n\n### 3. Access the Service\n\n- **Admin Panel:** `http://localhost:8080`\n- **MCP Endpoint:** `http://localhost:8080/mcp`\n\n---\n\n## 🏗️ Architecture\n\n- **Backend**: ASP.NET Core (`net10.0`) - High-performance server and MCP tool logic.\n- **Frontend**: Nuxt 4 - Premium administrative dashboard.\n- **Storage**: SQLite - Local persistent store for keys, logs, and custom tool definitions.\n\n---\n\n## 🗺️ Roadmap \u0026 Capabilities\n\n### MCP Tools\n\nReady for use (Experimental Stage). You can also define your own tools in the Admin Panel!\n\n| Progress | Tool                 | Description                                                               |\n| :------- | :------------------- | :------------------------------------------------------------------------ |\n| 🧪       | `execute_query_safe` | Execute a query (supports join, where, order by, group by, limit)         |\n| 🧪       | `get_columns`        | Get column names and data types of a table                                |\n| 🧪       | `get_schemas`        | Get schemas in the database                                               |\n| 🧪       | `get_tables`         | Get tables in the database                                                |\n| 🧪       | `execute_dml_safe`   | Execute a DML statement (INSERT, UPDATE, DELETE) with safety confirmation |\n\n### Admin \u0026 Security\n\n| Progress | Feature              | Description                                   |\n| :------- | :------------------- | :-------------------------------------------- |\n| ✅       | `Allowed Tools`      | Manage tool access for each API key           |\n| ✅       | `Per-key Connection` | Override database settings for specific keys  |\n| ✅       | `Key Management`     | Issue, list, and revoke keys in real-time     |\n| ✅       | `Audit Logging`      | Detailed query execution history and metadata |\n| ✅       | `Rate Limiting`      | Global rate limiting                          |\n| 🔜       | `Table WhiteList`    | Configure table whitelisting per API key      |\n\n---\n\n## 📒 How to Use\n\n### First-time Setup\n\n1. Start the services and open `http://localhost:8080`.\n2. Create the first admin account and sign in.\n3. Go to **MCP Keys** and click `Issue Key`.\n4. Copy the **Key Value** (only shown once) and add it to your client config.\n\n### Client Configuration\n\nAdd the following to your MCP client configuration (e.g., `claude_desktop_config.json`):\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"hs-sql-agent\": {\n\t\t\t\"url\": \"http://localhost:8080/mcp\",\n\t\t\t\"headers\": {\n\t\t\t\t\"X-MCP-Server-Key\": \"\u003cYOUR_MCP_KEY\u003e\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n_Works with **Claude Desktop**, **VS Code (Cline/Roo)**, and **Cursor**._\n\n---\n\n## 🛠️ Detailed Tool Information\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eData Query (DQL)\u003c/b\u003e\u003c/summary\u003e\n\n- **execute_query_safe**\n  - **Description**: Execute a complex query (supports joins, grouping, CTEs, etc.).\n  - **Parameters**: `tableName`, `selectColumns`, `whereConditions`, `joins`, `groupBy`, etc.\n  - **Read-only**: True\n\n- **get_columns**\n  - **Description**: Get column names and types for a specific table.\n  - **Read-only**: True\n\n- **get_tables / get_schemas**\n  - **Description**: Discover the database structure.\n  - **Read-only**: True\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eData Manipulation (DML)\u003c/b\u003e\u003c/summary\u003e\n\n- **execute_dml_safe**\n  - **Description**: Execute INSERT, UPDATE, or DELETE with a two-step confirmation process.\n  - **Safety**: Requires a `ConfirmToken` from a dry-run call before committing changes.\n  - **Read-only**: False\n\n\u003c/details\u003e\n\n---\n\n## 🏠 Local Development\n\n### Prerequisites\n\n- [.NET 10 SDK](https://dotnet.microsoft.com/download)\n- [Node.js 20+](https://nodejs.org/)\n- [pnpm](https://pnpm.io/)\n\n### Setup\n\n1. **Clone**:\n\n```bash\ngit clone https://github.com/tse-wei-chen/hs-sql-agent.git\n\ngit submodule update --init --recursive\n```\n\n2. **Backend**:\n\n```bash\ncp backend/src/ToolBox/appsettings.Example.json backend/src/ToolBox/appsettings.json\ndotnet run --project backend/src/ToolBox\n```\n\n3. **Frontend**:\n\n```bash\ncd frontend \u0026\u0026 pnpm install \u0026\u0026 pnpm dev\n```\n\n---\n\n## 📜 License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftse-wei-chen%2Fhs-sql-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftse-wei-chen%2Fhs-sql-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftse-wei-chen%2Fhs-sql-agent/lists"}