内容
# nl2sql-mcp
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](https://github.com/detachhead/basedpyright)
[](https://github.com/astral-sh/ruff)
一个生产就绪的 **模型上下文协议（MCP）服务器**，将自然语言转换为安全、可执行的 SQL 查询。为大型语言模型（LLM）构建，具有全面的类型安全性、多数据库支持和智能模式分析。
## 数据库支持
该项目提供一个“全驱动程序”容器镜像，可以连接到主要数据库，无需构建后步骤。驱动程序被建模为可选依赖项，Dockerfile 安装运行时所需的最小 OS 库。
- PostgreSQL：Python 驱动程序 `psycopg[binary]`（v3）；OS 库：`libpq5`。
- MySQL/MariaDB：Python 驱动程序 `mysqlclient`；OS 库：`libmariadb3`。
- SQL Server：Python 驱动程序 `pyodbc`；OS 库：`unixodbc`，Microsoft `msodbcsql18`（+ 可选 `mssql-tools18`）。
- SQLite：标准库 `sqlite3`（无需额外 OS 库）。
本地开发安装：
- 所有驱动程序：`uv sync --extra drivers-all`
- 特定后端：`uv sync --extra postgres --extra mysql`（按需）
构建全驱动程序镜像：
```bash
docker build -t nl2sql-mcp:drivers-all .
docker run --rm -p 8000:8000 nl2sql-mcp:drivers-all
```
注意：
- Debian slim 基础镜像最大化预构建轮胎兼容性。避免为 DB 堆栈使用 Alpine。
- 要将 MySQL 切换到纯 Python 驱动程序，请在 `pyproject.toml` 中将 `mysqlclient` 替换为 `mysql-connector-python`，并使用 `uv lock --extra drivers-all` 重新锁定。
## 🚀 主要功能
### 🎯 **LLM 优化智能**
- **意图优先的查询规划**，具有结构化模式上下文和连接建议
- **语义模式分析**，具有自动表分类（事实、维度、桥梁、参考）
- **多模式表发现**，使用词法匹配、嵌入和图遍历
- **列角色检测**（键、日期、指标、类别），具有语义标记
### 🛡️ **生产就绪的安全性**
- **仅限 SELECT 执行**，具有全面的 SQL 验证
- **方言规范化** 和通过 SQLGlot 的转译
- **行限制和单元格截断**，以防止资源耗尽
- **全面的错误处理**，具有可行的反馈
### 🔧 **多数据库支持**
- **SQLAlchemy 支持**，兼容 PostgreSQL、MySQL、SQL Server、SQLite、Oracle、Snowflake
- **方言感知** SQL 生成和优化
- **跨平台** 模式反射和分析
### 🏗️ **企业架构**
- **类型安全** Pydantic 模型贯穿始终
- **依赖注入**，用于可测试性
- **后台初始化**，具有优雅的降级
- **零硬编码假设** - 适应任何数据库模式
## 📦 快速入门
### 先决条件
- **Python 3.13+**
- **uv** 包管理器
- 已安装数据库驱动程序
### 安装
```bash
# 克隆仓库
git clone https://github.com/jb3cloud/nl2sql-mcp.git
cd nl2sql-mcp
# 安装依赖项
uv sync
# 配置数据库
cp .env.example .env
# 编辑 .env 以包含数据库连接详细信息
```
### 基本用法
```bash
# 启动 MCP 服务器
uv run nl2sql-mcp
# 或直接运行
uv run python -m nl2sql_mcp.server
# 或使用 uvx 运行
uvx --from git+https://github.com/jb3cloud/nl2sql-mcp nl2sql-mcp
```
## 🛠️ Makefile 工作流
存储库中包含一个 Makefile，用于标准化常见任务。所有目标都通过 `uv run` 调用工具，以确保环境一致。
```bash
# 发现可用目标和变量
make help
# 运行完整的质量检查（格式化 → 校验 → 类型检查 → 测试）
make quality
# 单个步骤（按需）
make format # Ruff 格式化
make lint # Ruff 检查 -- 修复
make typecheck # basedpyright（严格）
make test # pytest
make clean # 删除缓存和构建工件
```
还提供了 Azure 容器应用的部署助手：
```bash
# 创建 Docker 容器
make docker
# 运行 Docker 容器
make docker-run
# 验证 Azure CLI 登录并（可选）设置订阅
make preflight AZ_SUBSCRIPTION="00000000-0000-0000-0000-000000000000"
# 从源代码构建并部署
make publish \
APP_NAME=my-nl2sql-mcp \
RESOURCE_GROUP=my-rg \
ENVIRONMENT=my-aca-env \
LOCATION=eastus \
AZ_SUBSCRIPTION="00000000-0000-0000-0000-000000000000" \
INGRESS=external \
TARGET_PORT=8000 \
ENV_ARGS="NL2SQL_MCP_DATABASE_URL=postgresql://user:pass@host:5432/db"
```
支持的变量（可以通过环境或 CLI 提供）：`APP_NAME`、`RESOURCE_GROUP`、`LOCATION`、`ENVIRONMENT`、`AZ_SUBSCRIPTION`、`INGRESS`（默认为 `external`）、`TARGET_PORT`（默认为 `8000`）。
### 环境配置
使用数据库连接创建 `.env` 文件：
```bash
# 必需：数据库连接
NL2SQL_MCP_DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
# 可选：结果限制和调试
NL2SQL_MCP_ROW_LIMIT=1000
NL2SQL_MCP_MAX_CELL_CHARS=500
NL2SQL_MCP_DEBUG_TOOLS=1 # 启用查找表/列工具
```
## 🏛️ 架构
```mermaid
graph TD
A[LLM 客户端] -->|MCP 协议| B[FastMCP 服务器]
subgraph "核心服务"
B --> C[模式服务]
B --> D[SQLGlot 服务]
B --> E[执行引擎]
end
subgraph "智能层"
C --> F[模式资源管理器]
C --> G[查询引擎]
F --> H[反射和剖析]
F --> I[图分析]
G --> J[多模式检索]
G --> K[图扩展]
end
subgraph "数据层"
E --> L[SQLAlchemy 引擎]
H --> L
L --> M[(您的数据库)]
end
style A fill:#e1f5fe
style B fill:#f3e5f5
style M fill:#e8f5e8
```
系统遵循 **两阶段架构**：
1. **模式构建阶段**：全面的数据库分析、关系映射和语义理解
2. **查询处理阶段**：实时自然语言到 SQL 转换，具有上下文感知规划
## 🔌 MCP 工具 API
### 核心工作流工具
#### `get_init_status()`
检查服务器就绪性和初始化进度。
```json
// 响应
{
"phase": "READY",
"attempts": 1,
"started_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:30:45Z"
}
```
#### `get_database_overview(req: DatabaseOverviewRequest)`
高级别数据库摘要，包含主题区域。
```json
// 请求
{
"include_subject_areas": true,
"area_limit": 8
}
// 响应
{
"total_tables": 45,
"total_schemas": 3,
"subject_areas": [
{
"name": "销售分析",
"tables": ["orders", "customers", "products"],
"summary": "客户订单和产品销售数据"
}
]
}
```
#### `plan_query_for_intent(req: PlanQueryRequest)`
意图优先的 SQL 规划，具有结构化指导。
```json
// 请求
{
"request": "显示 2024 年按地区划分的每月收入",
"constraints": {
"time_range": "2024-01-01..2024-12-31",
"metric": "revenue"
},
"detail_level": "standard"
}
// 响应
{
"relevant_tables": [
{
"table_key": "sales.orders",
"relevance_score": 0.95,
"why_relevant": "包含收入数据和日期列"
}
],
"join_plan": [
["sales.orders.customer_id", "customers.id"]
],
"main_table": "sales.orders",
"draft_sql": "SELECT DATE_TRUNC('month', order_date) as month...",
"confidence": 0.92
}
```
#### `execute_query(req: ExecuteQueryRequest)`
安全的 SQL 执行，具有验证和结果。
```json
// 请求
{
"sql": "SELECT region, SUM(amount) as revenue FROM sales.orders WHERE order_date >= '2024-01-01' GROUP BY region"
}
// 响应
{
"success": true,
"rows": [
{"region": "North", "revenue": 125000.50},
{"region": "South", "revenue": 98750.25}
],
"row_count": 2,
"columns": [
{"name": "region", "type": "VARCHAR"},
{"name": "revenue", "type": "DECIMAL"}
],
"execution_time_ms": 45,
"next_action": "success"
}
```
### 发现工具
#### `get_table_info(req: TableInfoRequest)`
优化用于 SQL 生成的详细表元数据。
```json
// 请求
{
"table_key": "sales.orders",
"include_samples": true,
"column_role_filter": ["key", "date", "metric"]
}
```
#### `find_tables(req: FindTablesRequest)` *(调试模式)*
通过自然语言意图快速发现表。
#### `find_columns(req: FindColumnsRequest)` *(调试模式)*
用于构建 SELECT 和 WHERE 子句的列搜索。
### SQL 辅助工具
#### `sql_validate(sql: str)`
验证 SQL 语法和结构。
#### `sql_auto_transpile_for_database(sql: str)`
自动检测和转换 SQL 方言。
#### `sql_optimize_for_database(sql: str)`
为您的数据库引擎优化 SQL。
## ⚙️ 配置
### 数据库支持
| 数据库 | SQLAlchemy 驱动程序 | 连接字符串示例 |
|----------|-------------------|---------------------------|
| PostgreSQL | `psycopg2` | `postgresql://user:pass@host:5432/db` |
| MySQL | `pymysql` | `mysql+pymysql://user:pass@host:3306/db` |
| SQL Server | `pyodbc` | `mssql+pyodbc://user:pass@host/db?driver=ODBC+Driver+17` |
| SQLite | 内置 | `sqlite:///path/to/database.db` |
| Oracle | `cx_oracle` | `oracle://user:pass@host:1521/service` |
| Snowflake | `snowflake-sqlalchemy` | `snowflake://user:pass@account/db/schema` |
### 模式配置
控制模式分析行为：
```python
# 通过环境或配置
NL2SQL_MCP_INCLUDE_SCHEMAS=public,analytics
NL2SQL_MCP_EXCLUDE_SCHEMAS=temp,audit
NL2SQL_MCP_SAMPLE_SIZE=100 # 每张表用于分析的行数
```
### 性能调优
```bash
# 内存和处理限制
NL2SQL_MCP_ROW_LIMIT=1000 # 返回的最大行数
NL2SQL_MCP_MAX_CELL_CHARS=500 # 截断长文本
NL2SQL_MCP_SAMPLE_TIMEOUT=5 # 采样超时（秒）
NL2SQL_MCP_MAX_COLS_FOR_EMBEDDINGS=20 # 列嵌入限制
NL2SQL_MCP_REFLECT_TIMEOUT=15 # 每个语句的反射超时（秒）
NL2SQL_MCP_ENABLE_LIGHTWEIGHT_NER=1 # 在分析期间启用 NER 丰富（0 禁用）
```
## 🧪 测试和开发
### 本地开发设置
```bash
# 安装开发依赖项
uv sync --dev
# 运行类型检查
uv run basedpyright
# 格式化和校验代码
uv run ruff format .
uv run ruff check --fix .
# 运行测试
uv run pytest -v
```
### 使用实时数据库测试
```bash
# 智能测试
uv run python scripts/test_intelligence_harness.py "show sales by region"
# SQL 工具测试
uv run python scripts/test_sqlglot_harness.py "SELECT TOP 10 * FROM customers"
```
### 质量保证
- **100% 类型覆盖率**，使用基于严格模式的 basedpyright
- **全面的测试套件**，使用 pytest
- **零 linting 违规**，使用 ruff
- **依赖注入**，用于可测试性
- **纯函数**，在可能的情况下
## 📚 高级用法
### 自定义模式分析
```python
from nl2sql_mcp.services import ConfigService, SchemaServiceManager
# 使用自定义配置初始化
config = ConfigService()
manager = SchemaServiceManager.get_instance()
# 在初始化后访问模式服务
schema_service = manager.get_schema_service()
result = schema_service.analyze_query_schema(
"Find customers with high lifetime value",
max_tables=10,
expand_strategy="fk_following"
)
```
### 多代理集成
MCP 服务器与多代理框架无缝集成：
```python
# 示例与您的 LLM 框架
async def query_database(natural_language_query: str):
# 1. 计划查询
plan_result = await mcp_client.call_tool(
"plan_query_for_intent",
{"request": natural_language_query}
)
# 2. 执行草稿 SQL
if plan_result.draft_sql:
execution_result = await mcp_client.call_tool(
"execute_query",
{"sql": plan_result.draft_sql}
)
return execution_result.rows
```
### 代码标准
- **Python 3.13+**，具有严格的类型检查
- **Pydantic 模型**，适用于所有数据结构
- **纯函数** 和依赖注入，用于可测试性
- **全面的文档字符串**，适用于公共 API
- **零容忍度**，适用于类型错误、linting 违规或测试失败
## 🏢 生产部署
### 环境变量
```bash
# 必需
NL2SQL_MCP_DATABASE_URL=postgresql://...
# 可选性能调优
NL2SQL_MCP_ROW_LIMIT=5000
NL2SQL_MCP_MAX_CELL_CHARS=1000
NL2SQL_MCP_SAMPLE_SIZE=200
```
### 健康监控
通过 `get_init_status()` 工具监控服务器健康状况：
- `READY`: 服务器完全运行
- `STARTING`: 初始化进行中
- `FAILED`: 初始化失败，请检查日志
## 📖 相关研究
此实现结合了文本到 SQL 的最新研究：
- **多代理架构**，用于复杂的查询分解
- **模式链接**，具有双向上下文理解
- **错误纠正框架**，具有多轮细化
- **语义理解**，通过轻量级 NER 和角色分类
有关详细研究上下文，请参阅 [NL2SQL_RESEARCH.md](docs/NL2SQL_RESEARCH.md)。
## 🙏 致谢
- **[FastMCP](https://gofastmcp.com)**，适用于优秀的 MCP 服务器框架
- **[SQLGlot](https://sqlglot.com)**，适用于多方言 SQL 解析和转译
- **[SQLAlchemy](https://sqlalchemy.org)**，适用于强大的数据库抽象
- **文本到 SQL 研究社区**，推进该领域
连接信息
猜你喜欢
暂无推荐服务器