tse-wei-chen/hs-sql-agent

# ⚡ hs-sql-agent（高速SQL代理）  [](https://github.com/tse-wei-chen/hs-sql-agent/actions/workflows/docker-publish.yml) [](https://github.com/tse-wei-chen/hs-sql-agent/actions/workflows/codeql.yml) `hs-sql-agent` 是一个用于关系型数据库的强大 HTTP MCP 服务器，它搭建了 AI 代理与您数据之间的桥梁。与通用的"黑盒" SQL 代理不同，`hs-sql-agent` 提供了一个**高速**执行引擎和**内置管理面板**，以确保每个 AI 生成的查询都受到管理、审计且安全。 ## ✨ 核心特性 ### 🚀 高速与核心引擎 - **即时交互**：优化的 C# 后端确保模式发现和查询执行具有超低延迟。 - **通用数据库支持**：一个代理通吃所有主流数据库——原生支持 `Sqlite`、`PostgreSQL`、`MySQL`、`SQLServer`、`Oracle` 和 `FireBird`。 - **确定性准确性**：别再让 LLM 凭空想象原始 SQL。LLM 不需要了解复杂或晦涩的数据库语法；它只需提取结构化参数（表、列和条件），将确定性的 SQL 生成工作交给代理。借助**元数据工具**，LLM 可以每次动态查询并映射出完美的参数。 - **强大的安全性**：完全由 [SqlKata](https://sqlkata.com) 驱动，对所有输入强制执行自动参数化，从源头上消除 LLM 驱动的 SQL 注入风险。 - **领域知识与语义层**：定义健壮的数据库语义层和可定制的 SQL 工具，以增强 AI 推理，使代理与您的特定业务逻辑完美对齐。 ### 🛡️ 企业级治理 - **内置管理 Web 界面**：通过直观的仪表板可视化管理您的 SQL 代理。不再需要费力处理手动 JSON 配置文件。 - **细粒度访问控制**： - **密钥级别映射**：安全地将特定的数据库连接和范围分配给各个 API 密钥。 - **生命周期管理**：轻松地实时发放、列出或撤销访问密钥。 - **生产环境防护**： - **表白名单**：限制 AI 仅能访问授权的表，确保敏感数据不被触碰。 - **全局速率限制**：防止您的生产数据库因无限 AI 循环或过量流量而不堪重负。 - **全面的审计日志**：跟踪每一个查询，提供每日摘要和详细的执行历史记录，以满足合规要求。 ## 🖥️ 管理面板 内置的管理面板允许您监控操作和管理访问权限，无需触碰任何配置文件。 _操作仪表板：实时监控密钥和审计事件。_ _精细控制：为每个 API 密钥分配特定的数据库连接和工具子集。_ _低代码工具：为 AI 代理定义自定义 SQL 操作（例如，`calculate_churn_rate`）。_ _数据库管理：管理您的数据库连接。_ ## 🚀 快速开始（Docker Compose） 运行 **HS SQL Agent** 最简单的方式是使用 Docker Compose。这能确保您的配置被保存，并且数据在重启后得以保留。 ### 1. 设置配置 复制示例环境文件： ``` cp .env.example .env ``` 编辑 `.env` 文件以设置您的密钥： ``` HMAC_KEY=YourMcpHmacSecretKeyHere-AtLeast32Bytes! JWT_KEY=YourSuperSecretKeyHere-AtLeast32Bytes! JWT_ISS=HS-Agent JWT_AUD=HS-Agent-Users JWT_ACCESS_TOKEN_EXPIRATION_MINUTES=1 JWT_REFRESH_TOKEN_EXPIRATION_DAYS=30 RATE_LIMITING_PERMIT_LIMIT=0 RATE_LIMITING_WINDOW_SECONDS=0 RATE_LIMITING_QUEUE_LIMIT=0 ``` ### 2. 启动应用 ``` docker compose up -d ``` ### 3. 访问服务 - **管理面板：** `http://localhost:8080` - **MCP 端点：** `http://localhost:8080/mcp` ## 🏗️ 架构 - **后端**：ASP.NET Core (`net10.0`) - 高性能服务器和 MCP 工具逻辑。 - **前端**：Nuxt 4 - 高级管理仪表板。 - **存储**：SQLite - 用于存储密钥、日志和自定义工具定义的本地持久化存储。 ## 🗺️ 路线图与功能 ### MCP 工具 已可供使用（实验阶段）。您也可以在管理面板中定义自己的工具！ | 进度 | 工具 | 描述 | | :--- | :---------------------- | :--------------------------------------------------------------------- | | 🧪 | `execute_query_safe` | 执行查询（支持连接、where、order by、group by、limit） | | 🧪 | `get_columns` | 获取表的列名和数据类型 | | 🧪 | `get_schemas` | 获取数据库中的模式 | | 🧪 | `get_tables` | 获取数据库中的表 | | 🧪 | `execute_dml_safe` | 执行 DML 语句（INSERT、UPDATE、DELETE），并需安全确认 | | 🔜 | `save_query` | 为 AI 代理保存查询 | | 🔜 | `update_semantic_layer` | 让 AI 代理使用发现的元数据更新和丰富语义层 | ### 管理与安全 | 进度 | 功能 | 描述 | | :--- | :------------------- | :------------------------------------- | | ✅ | `Allowed Tools` | 管理每个 API 密钥的工具访问权限 | | ✅ | `Per-key Connection` | 为特定密钥覆盖数据库设置 | | ✅ | `Key Management` | 实时发放、列出和撤销密钥 | | ✅ | `Audit Logging` | 详细的查询执行历史记录和元数据 | | ✅ | `Rate Limiting` | 全局速率限制 | | ✅ | `Table WhiteList` | 按 API 密钥配置表白名单 | | ✅ | `Semantic Layer` | 为 AI 代理定义数据库语义层 | ## 📒 如何使用 ### 首次设置 1. 启动服务并打开 `http://localhost:8080`。 2. 创建第一个管理员账户并登录。 3. 转到 **MCP Keys** 并点击 `Issue Key`。 4. 复制 **Key Value**（仅显示一次）并将其添加到您的客户端配置中。 ### 客户端配置 将以下内容添加到您的 MCP 客户端配置（例如，`claude_desktop_config.json`）： ``` { "mcpServers": { "hs-sql-agent": { "url": "http://localhost:8080/mcp", "headers": { "X-MCP-Server-Key": "" } } } } ``` _适用于 **Claude Desktop**、**VS Code (Cline/Roo)** 和 **Cursor**。_ ## 🛠️ 详细工具信息

数据查询（DQL）

- **execute_query_safe** - **描述**：执行复杂查询（支持连接、分组、CTE 等）。 - **参数**：`tableName`, `selectColumns`, `whereConditions`, `joins`, `groupBy` 等。 - **只读**：是 - **get_columns** - **描述**：获取特定表的列名和类型。 - **只读**：是 - **get_tables / get_schemas** - **描述**：发现数据库结构。 - **只读**：是

数据操作（DML）

- **execute_dml_safe** - **描述**：通过两步确认过程执行 INSERT、UPDATE 或 DELETE。 - **安全性**：在提交更改前，需要来自试运行调用的 `ConfirmToken`。 - **只读**：否

## 🏠 本地开发 ### 前置条件 - [.NET 10 SDK](https://dotnet.microsoft.com/download) - [Node.js 20+](https://nodejs.org/) - [pnpm](https://pnpm.io/) ### 设置 1. **克隆仓库**： ``` git clone https://github.com/tse-wei-chen/hs-sql-agent.git git submodule update --init --recursive ``` 2. **后端**： ``` cp backend/src/ToolBox/appsettings.Example.json backend/src/ToolBox/appsettings.json dotnet run --project backend/src/ToolBox ``` 3. **前端**： ``` cd frontend pnpm install pnpm run dev ``` ## 📜 许可证 [Apache License 2.0](LICENSE)

标签：AI代理, C#编程, Docker容器化, FireBird数据库, LLM安全集成, Oracle数据库, PostgreSQL, SQLite, SqlKata, SQL Server, SQL处理, SQL查询构建, 企业级治理, 元数据映射, 参数化查询, 数据库管理, 查询审计, 确定性查询, 管理界面, 语义层, 请求拦截, 防SQL注入, 高性能计算