SQL Agent + MySQL MCP Server

当前版本：v0.8.0（标准可观测性导出 + CI 安全扫描 + 审计落盘）；V0.4 Schema Intelligence + 契约锁定 + CI → V0.5 Domain Query Layer → V0.6 Agent Reliability → V0.7 可观测性加固 → v0.8.0 工程化收尾（Metrics 标准导出、Alertmanager 外置、零基础设施审计落盘、CodeQL/Trivy/Dependabot 安全门禁）。MCP Tool 契约仍以 v0.5.0 兼容基线为准。

企业级 SQL Agent + MCP 数据访问平台：基于 MCP（Model Context Protocol） 构建 Agent 与数据库之间的标准化工具调用层，让数据访问收敛为受治理的 MCP 工具，限制 LLM 对数据库的直接访问，形成从 Agent → MCP → 权限 → SQL → 数据库的完整治理链路。安全防线独立成模块、策略外置为 YAML，Agent 动态发现工具并调用受治理的领域能力；底层是标准 MCP Server，可作为学习型 Reference Implementation（Agent 自然语言查询 MySQL），治理与可观测能力见下文。

本项目已经覆盖 Agent 可靠性、权限控制和可观测性，但默认配置不等同于可直接公开部署的生产系统；部署前请阅读「生产化要点」和「已知边界」。

它能做什么

输入一句自然语言，Agent 自动完成：发现工具 → 查表结构 → 生成只读 SQL → 执行 → 汇总答案。

• 简单查询、多表 JOIN、聚合统计、排序 + LIMIT

• SQL 错误自动修正

• 识别不存在的字段 / 表，不编造

• 拦截恶意 / 危险 SQL（基于 sqlglot AST 的校验管线：只读语句白名单 + 单语句 + 表/列 Allowlist + JOIN 上限 + 系统库封禁 + 行数/字节/长度/并发成本限制；关键字黑名单仅作辅助防线）

• 请求级权限：认证 Principal → RBAC → 表/列 ACL → Row-Level Security → SQL 重写 → 审计

• 受限用户查询 SELECT * 时自动展开可见列；schema 工具与 Resource 也只返回当前主体可见的表和列

• Schema Intelligence：为表/列补充业务名、用途、口径与同义词（外置 configs/schema_desc.yaml），提供轻量语义检索 search_schema，让 Agent 生成 SQL 前先理解字段语义、减少幻觉列名

• Domain Query Layer（V0.5）：sales_summary / company_ranking / industry_analysis 三个领域工具，模板与领域口径由服务端维护（configs/domain_queries.yaml），值参数经数据库驱动绑定、排序/分组/时间粒度等标识符只能取白名单；Agent 优先调用领域工具，复杂问题才回退 run_query

• Agent Reliability（V0.6）：AsyncOpenAI + 连接/读取/单次调用超时 + 全局请求截止时间；临时错误退避重试（仅只读调用）、永久错误立即终止；统一预算（迭代/工具调用/SQL修复/Token/费用上限）杜绝无限循环与无限等待；SQL 修复仅针对语法/字段错误，权限/超时/危险 SQL 不进入盲重试；每次结束都返回稳定错误码（success/timeout/model_error/tool_error/sql_syntax_error/permission_denied/budget_exceeded）与用户可理解信息及运行指标（迭代数/工具调用数/修复次数/耗时/最终状态）

• Observability Hardening（V0.7）：接入共享 telemetry 内核（OpenTelemetry 数据模型 + W3C traceparent 传播 + 有界内存缓冲 + 可选 OTLP/HTTP 导出），让 Agent → MCP → Authorization → Database 四层落在同一条 trace；任意一次请求都能靠 request_id 与 trace_id 跨服务完整定位。SQL 延迟成功/失败都记录，错误率按错误码、工具、主体类型聚合；Metrics 改为有界直方图（固定分桶，不再在内存保留全部样本），指标标签卫生化（禁止原始 SQL / 完整用户输入 / 高基数字段）。审计支持异步落库、失败策略、保留周期与归档。内置 /dashboard、/alerts、/traces 端点与进程内告警引擎，并配套 Grafana 面板与 Prometheus 告警规则（错误率 / P95/P99 延迟 / 超时率 / 工具失败率 / 连接池饱和度）

Related MCP server: easy-mysql-mcp

架构

agent/
  agent.py             ReAct / function-calling 主循环 + 可靠性预算
  client.py            MCP Session + traceparent 注入
  reliability.py       超时、重试、错误码、RunResult

              │ MCP Streamable HTTP / stdio
              ▼

mcp_server/
  server.py            工具/Resource 注册、HTTP/stdio、探针与管理端点
  tools/               list_tables / get_schema / search_schema
                       run_query / 领域工具 / 策略管理工具
  services/            QueryService：安全 → 授权 → LIMIT → 执行 → 审计/指标
  domain/              QueryTemplate / QuerySpec / 安全参数绑定 / 领域 DTO
  security/            sqlglot AST / Security Policy / Validator
  authorization/       RBAC / ACL / RLS / SQL 重写 / Policy DB / Audit
  auth/                Bearer / JWT / Principal / RequestContext
  catalog/             SchemaCatalog / 业务语义检索
  database/            连接池 / 参数绑定 / 只读执行
  observability/       Metrics / Trace / Alerts / Health / Lifecycle

telemetry/             共享 Span 模型 / W3C traceparent / OTLP 导出

              │ SQL
              ▼

MySQL                  sales_demo：company / sale_records

SQL 安全架构（V0.2）

• ① 三层职责分离：Tool 层只负责 MCP 协议；Security 层只回答「这条 SQL 能不能执行」；Database 层只负责执行。

• ② 校验管线基于 AST：SQL → Parser → AST（表 / 列 / JOIN / 子查询 / LIMIT）→ Statement Type → Policy → ValidationResult，结构提取后再比对，避免字符串匹配的误判与绕过。

• ③ Allowlist 优先于 Denylist：不是「发现危险才拒绝」，而是「符合安全 Policy 才允许执行」。

权限架构（V0.3）

MCP Request
  -> Authentication（Bearer Token / 本地服务身份）
  -> 外部 OAuth 2.1 / JWT JWKS 或静态 Token
  -> Principal（subject / roles / attributes）
  -> RBAC（query:run / schema:read）
  -> Table ACL + Column ACL
  -> Row-Level Security（AST 条件注入）
  -> CTE / 派生表列血缘与结果列二次防护
  -> SQL 二次安全校验
  -> QueryExecutor

• 策略集中在 configs/permissions.yaml，角色、主体、ACL、RLS 均不写死在 SQL 中。

• Policy DB 与 Business DB 使用独立连接和账号；MySQL 发布在单事务内完成 active 行锁、版本写入、指针切换和审计。

• 发布前执行 Schema / Semantic / Security Validation；当前禁止全局 *、控制面与查询面混用。

• 默认 AUTH_PRINCIPAL_MODE=policy；JWT claims 必须经过服务端角色映射，不能直接获得 query/policy admin。

• JWT 模式校验签名、issuer、audience、exp，可通过 JWKS 或静态公钥加载密钥。

• 决策采用 deny > allow > 默认拒绝；受 RLS 保护的表没有适用策略时直接拒绝。

• 表结构工具同样经过授权：不可见表不返回，列级 ACL 隐藏的字段不会出现在 schema 结果中。

• AUTH_MODE=disabled 保持本地开发体验；AUTH_MODE=static 可用 Bearer Token 验证完整认证链。

MCP 对外能力：

稳定 API 契约（V0.5 兼容基线，当前实现 v0.7.0）

V0.5.0 冻结了以下 MCP Tool 和 Resource 契约。V0.6、V0.7 增加了 Agent 可靠性和可观测性，但没有破坏既有 MCP Tool 名称与参数。任何增删改仍须走版本演进，并同步更新 tests/test_api_contract.py。

• Tool（13 个）：list_tables / get_schema(table_name) / search_schema(keyword, deep=false) / run_query(sql) / sales_summary(start_date, end_date, granularity, company_id, limit) / company_ranking(start_date, end_date, industry, sort_by, order_dir, limit) / industry_analysis(start_date, end_date, industry, sort_by, order_dir, limit) / get_policy_status / reload_permission_policy / validate_permission_policy(document) / publish_permission_policy(document, expected_version) / list_permission_policy_versions(limit) / export_permission_policy。

• Resource（2 个）：database://schema、database://table/{table_name}（均返回完整语义 DTO：表级 label/description/primary_keys/foreign_keys/indexes + 列 name/type/label/description/synonyms/enum_values）。

• 权限动作：schema:list / schema:read / query:run / policy:read|validate|publish|rollback。

• 查询错误结构：run_query、get_schema 与三个领域工具出错时返回 {"error": str, "code": str}。

• 查询成功结构：rows / columns / row_count / elapsed_seconds / truncated / result_bytes / truncated_reason。

• 领域工具成功 DTO：data / columns / meta（tool / parameters / semantics / row_count / elapsed_seconds / result_bytes / truncated_reason）/ definition_version / policy_version / truncated。

Domain Query Layer（V0.5）

• 定义由服务端维护在 configs/domain_queries.yaml（SQL 模板 / 参数定义 / 结果契约 / 领域口径），以内容哈希生成 definition_version 随 DTO 返回；按 mtime + TTL 自动重载。

• 参数绑定：值参数（日期 / 整数 / 枚举）先做类型与范围校验，再以 ? 占位符经数据库驱动绑定执行，值文本绝不进入 SQL；排序 / 分组 / 时间粒度等标识符只能取 identifiers 白名单映射的固定片段。

• 口径显式定义：sales_summary 当前表没有退款/取消状态字段，所有销售记录均视为有效成交并全额计入；company_ranking 按指定指标排序并以 company_id 保证唯一顺序；industry_analysis 的占比分母始终是窗口内全部行业销售额，不随 industry 过滤改变。

• 安全一致性：领域工具不直接访问数据库，统一经 QueryService（AST Guard / RBAC / ACL / RLS / LIMIT / 审计 / 指标），任意主体的越权与行级过滤行为与 run_query 完全一致。

Agent 返回契约（V0.6/V0.7）

SQLAgent.run() 不再返回裸字符串，而是返回 RunResult：

from agent.agent import SQLAgent

agent = SQLAgent()
result = await agent.run("今年销售额最高的10家公司")

print(result.status)          # success / timeout / model_error / ...
print(result.answer)          # 成功时为用户答案
print(result.error_message)   # 失败时为稳定错误说明
print(result.to_dict())       # answer + status + 运行指标

运行指标包括迭代数、工具调用数、SQL 修复次数、耗时、Token 数量和估算费用。CLI 入口会将这些信息渲染为终端文本。

模块边界与依赖方向

三层划分明确所属，避免能力重复实现：

agent/（LLM 编排层）
  └─ 提示 / 工具发现 / function-calling 主循环；唯一 MCP 客户端入口；不做 SQL 安全与授权
mcp_server/server.py（传输/组装层）
  └─ 组装 MCPServer：工具注册、Resource、HTTP/stdio、探针；不实现任何业务判定
mcp_server/（领域层）
  tools/        只做 MCP 协议转换 + 参数校验 + 授权裁剪；不做安全判定
  services/     编排（QueryService：校验→RBAC/ACL/RLS→LIMIT→执行）
  domain/       领域查询层（QueryTemplate/QuerySpec、参数绑定、Registry、统一 DTO）
  security/     只读安全判断（AST 解析 / 策略 / 校验）；不含授权决策
  catalog/      表结构 + 语义元数据缓存；不依赖授权
  authorization/ 授权（RBAC / ACL / RLS / SQL 重写 / 策略版本发布）；不含查询执行
  auth/         认证（Principal / Token / JWT）
  database/     连接池 + 只读执行（含驱动参数绑定）；不含安全/授权

依赖方向：agent → server(HTTP/stdio) → tools → services → security / authorization / catalog → database。

约束（各层“不做什么”）：

• agent/ 不得 import mcp_server 内部的 security / authorization；只经由公开的 MCP 端点和工具交互。

• tools/ 不实现安全判定与授权决策，只校验参数并调用下层。

• domain/ 只做模板渲染与 DTO 包装，不直接访问数据库；安全判定全部委托 QueryService。

• catalog/ 不做表/列级授权，可见性裁剪统一由 tools/ 层依据 authorization 完成。

• database/ 不判断 SQL 是否合法，只负责执行、驱动参数绑定与结果限量。

• 新增领域能力时，按此边界落到对应包；能力归属不清时优先 services/ 编排、实体进 catalog/models。

快速开始

1. 环境准备

需要 Python 3.12+ 和 MySQL 8.0+。业务库建议使用独立的只读账号。

python -m venv .venv
.venv\Scripts\activate        # Windows；macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

2. 配置连接

cp .env.example .env

.env.example 是最小可复制模板。Static/JWT、MySQL Policy Store、Audit、OTLP 和告警配置均以注释形式提供，只在需要对应模式时取消注释。

至少需要确认：

• LLM_API_KEY 和模型端点。

• MYSQL_HOST / MYSQL_PORT / MYSQL_USER / MYSQL_PASSWORD / MYSQL_DATABASE。

• 本地开发保持 AUTH_MODE=disabled；启用认证时设置 AUTH_MODE 和 MCP_AUTH_TOKEN。

3. 建库造数

python scripts/db_init.py --reset
python scripts/db_init.py --permission-fixtures

4. 启动 MCP Server

python -m mcp_server.server
# 默认监听 http://127.0.0.1:8000/mcp

启动后可验证：

curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/readyz

启用静态 Bearer Token：

AUTH_MODE=static
AUTH_TOKENS_JSON={"alice-token":"alice"}
MCP_AUTH_TOKEN=alice-token

服务端验证 token 并映射到 configs/permissions.yaml 中的 principal；Agent 会在 MCP HTTP 请求中发送 Authorization: Bearer ...。

启用外部 OAuth 2.1 / JWT：

AUTH_MODE=jwt
AUTH_JWT_ISSUER=https://issuer.example
AUTH_JWT_AUDIENCE=http://127.0.0.1:8000/mcp
AUTH_JWT_JWKS_URL=https://issuer.example/.well-known/jwks.json
AUTH_JWT_ALGORITHMS=RS256
MCP_AUTH_TOKEN=<access-token>

策略存 MySQL 并启用热加载：

POLICY_STORE=mysql
POLICY_RELOAD_SECONDS=5
POLICY_DB_HOST=127.0.0.1
POLICY_DB_PORT=3306
POLICY_DB_USER=policy_app
POLICY_DB_PASSWORD=<policy-db-password>
POLICY_DB_DATABASE=mcp_policy
python scripts/policy_db_init.py
python -m mcp_server.policy_admin validate configs/permissions.yaml
python -m mcp_server.policy_admin publish configs/permissions.yaml --actor admin --reason v0.7

5. 运行 Agent

python -m agent.agent "今年销售额最高的10家公司"
python -m agent.agent "各行业今年的销售总额排名" --trace

包内使用相对导入，请在项目根目录使用 python -m ... 执行。

配置速查

完整键位和默认值见 .env.example 以及 agent/config.py、mcp_server/config.py。

目录结构

agent/                  Agent 侧
  config.py             LLM 参数 + MCP 端点
  client.py             MCP 会话管理与 MCP→OpenAI 适配（V0.7：注入 traceparent）
  agent.py              SQLAgent（ReAct + function calling）主循环（V0.7：Agent 层 Span）
  reliability.py        超时/退避重试/统一预算/稳定错误码

telemetry/              共享遥测内核（V0.7，纯标准库，Server 与 Agent 共用）
  __init__.py           Span 模型 / W3C traceparent / 有界内存缓冲 / OTLP-HTTP 导出

mcp_server/             Server 侧
  server.py             入口：注册工具/资源、启动传输层、/healthz /readyz /metrics /traces /dashboard /alerts
  config.py             数据库连接 + 传输参数 + 审计/遥测/告警配置
  tools/
    schema.py           list_tables / get_schema / search_schema
    query.py            run_query（仅 MCP 协议转换，委托 QueryService）
    domain.py           sales_summary / company_ranking / industry_analysis
    policy_admin.py     策略状态、热加载、版本列表、导出与发布工具
  domain/               V0.5 领域查询层
    models.py           QueryTemplate / QuerySpec / ParameterSpec
    binder.py           白名单内联 + 类型校验 + ? 占位符
    registry.py         configs/domain_queries.yaml 加载与 mtime 重载
    service.py          渲染 → QueryService → 统一 DTO
  services/
    query_service.py    安全校验 → RBAC/ACL/RLS → LIMIT → 执行 → 错误收敛
  auth/                 Principal / RequestContext / 静态 Token / OAuth 2.1 JWT
  catalog/              SchemaCatalog + 业务语义加载与检索
  observability/        Trace / Metrics / Health / Lifecycle / Alerts；prom_exporter 桥接标准 Prometheus 导出（v0.8）
  authorization/        RBAC / ACL / RLS / SQL 重写 / Policy DB / Audit
  security/             AST 解析 / 策略匹配 / 只读校验
  database/             连接池 + 只读执行 + 参数绑定
  policy_admin.py       策略管理 CLI

configs/security.yaml             安全策略
configs/permissions.yaml          权限策略
configs/schema_desc.yaml          业务语义
configs/domain_queries.yaml       领域查询定义
configs/alerts.yaml               进程内告警规则
configs/prometheus/alerts.yml     Prometheus 告警规则
configs/prometheus/alertmanager.yml  Alertmanager 去重/静默/路由配置（v0.8）
configs/grafana/dashboard.json    Grafana 面板
.github/workflows/                CI 安全门禁：CodeQL / Trivy / Dependabot（v0.8）

tests/                  pytest 测试
scripts/                建库、策略库、迁移和批处理脚本
examples.md             已验证问题和测试报告
.env.example            最小可复制配置模板

测试

python -m pytest -q
python -m pytest tests/test_sql_validator.py -q
python -m pytest tests/test_authorization.py -q

默认会跳过需要真实 MySQL 的集成用例。设置 RUN_DB_TESTS=1 后运行完整测试：

$env:RUN_DB_TESTS=1; python -m pytest -q
$env:RUN_DB_TESTS=1; python -m pytest tests/test_query.py -q
$env:RUN_DB_TESTS=1; python -m pytest tests/test_permission_integration.py -q
$env:RUN_DB_TESTS=1; python -m pytest tests/test_domain_query.py -q

生产化要点

• 只读三层纵深：Agent 约定只读 → MCP Server AST Allowlist 校验 → 数据库账号只授 SELECT。

• 请求级权限：Bearer Token → Principal → RBAC/ACL/RLS；不接受模型或工具参数自报身份。

• 控制面隔离：query_admin、policy_admin 分离；控制面权限不能混入查询角色。

• 独立 Policy DB：策略库使用 POLICY_DB_*，业务库账号无需策略表写权限。

• 原子发布：active 行锁、版本写入、指针切换和审计在同一事务提交。

• 授权后再校验：RLS 与 SELECT * 展开后再次经过 AST 安全校验。

• 凭证隔离：连接串和 Key 使用 .env 或 Secret Manager，不进入镜像和仓库。

• 策略外置：安全规则集中在 configs/security.yaml。

• 校验先于连库：恶意 SQL 在无数据库连接时也会被拒绝。

• 连接池与 SchemaCatalog：业务库与策略库独立连接池，SchemaCatalog 提供 TTL 缓存。

• 审计：AUDIT_STORE=mysql 支持异步批量落库、失败策略、保留周期和归档；AUDIT_REQUIRED=true 会同步写入并向上传播失败；v0.8 起设置 AUDIT_LOG_FILE 可将结构化 JSON 审计事件以纯 JSON 独立落盘并按大小轮转（零基础设施，可直接被 Promtail / Fluent Bit 采集）。

• 可观测性：telemetry 提供 W3C traceparent 和 OTLP/HTTP JSON 导出；/metrics 自 v0.8 起输出官方 prometheus_client 标准文本（薄适配层），可直接被 Prometheus 抓取；告警外置配合 configs/prometheus/alertmanager.yml。生产环境建议接入 OpenTelemetry Collector、Prometheus、Grafana 和 Alertmanager。

• CI 安全门禁：仓库内置 CodeQL、Trivy、Dependabot 工作流，PR/主分支自动执行依赖与代码漏洞扫描。

• 优雅退出：停止接收新请求、等待在途请求排空、排空审计队列、关闭连接池后退出。

已知边界

• 关键字黑名单是粗粒度防线，生产环境仍应以数据库最小权限（只读账号、禁止 UDF/LOAD_FILE 等）为根本。

• 解析基于 sqlglot AST；@@version 这类符号 token AST 不可见，因此保留 forbidden_patterns 作为辅助防线。

• 普通 CTE、嵌套 CTE 与派生表列血缘已支持；无法完整解析血缘时 fail closed。

• 静态 Bearer Token 只适合本地测试；生产认证应使用 AUTH_MODE=jwt 接入外部 OAuth 2.1 / JWKS。

• /metrics、/traces、/dashboard、/alerts 是运维接口，不应直接暴露到公网。部署时必须限制内网访问或由反向代理增加管理认证。

• /traces 和 /alerts 展示的是当前进程内有界状态；多实例场景应通过 OpenTelemetry Collector、Prometheus 和 Alertmanager 聚合。

• 默认不提供 TLS、HA、Secret Manager、备份和灾备能力，需要由部署平台补齐。

• 本项目不是通用 BI 平台，也不替代数据库自身的权限、审计和备份机制。

License

示例代码，MIT。