MCP 协议落地实践：国产化数据库 AI 一站式 SQL 诊断调优方案

一、前言

Model Context Protocol（MCP，模型上下文协议）是Anthropic推出的标准化AI外部交互协议，统一大模型与数据库、API、文件系统的通信标准，解决传统开发中「AI与数据库割裂、频繁切换客户端、手动复制表结构/执行计划」的低效问题。

电科金仓（KingbaseES，简称KES）作为国内主流国产化事务型数据库，官方开源 kingbase-mcp MCP Server，基于Python实现，原生适配KES V8R6+，封装9类数据库标准工具，支持表结构查询、SQL执行、执行计划解析、虚拟索引模拟、慢查询诊断、数据库健康巡检等全链路运维分析能力。

开发者在Cursor、TRAE等MCP兼容IDE内，自然语言提问即可完成数据库全流程排查，无需切换DBeaver、Navicat等客户端，实现AI+国产数据库闭环开发。

二、核心架构与通信流程

2.1 分层架构

KES MCP采用五层分层设计，职责解耦、易扩展：

AI客户端层：Cursor/TRAE等MCP开发工具，发起自然语言请求
传输层：Stdio（本地）/SSE/Streamable HTTP（远程）三通信模式
核心安全服务层：SQL语法AST校验、访问权限控制、连接池管理、超时熔断
分析能力层：表元数据、EXPLAIN解析、虚拟索引、负载索引推荐、健康检测
KES数据库层 ：金仓实例，支持sys_hypo/sys_stat_statements扩展增强性能分析

2.2 完整交互链路

用户在IDE输入自然语言指令；
MCP客户端解析需求，调用对应MCP工具；
KES MCP Server接收请求，安全层先校验SQL合法性（restricted模式拦截DML/DDL高危语句）；
建立数据库连接执行操作，原生返回表结构、执行计划、慢查询统计；
数据回传给大模型，AI结合真实库数据完成分析并输出优化建议；

关键安全约束：AI无法绕过MCP直连数据库，MCP访问模式 + 数据库账号最小权限双重防护。

2.3 三种传输模式选型

传输模式	适用场景	特点
Stdio	本地开发调试	无需开放端口，IDE自动拉起进程，推荐本地使用
SSE	简单远程共享	基于HTTP长轮询，老旧网络兼容
Streamable HTTP	生产集群、反向代理、HTTPS部署	双向流标准，企业集中运维首选

三、环境前置依赖

数据库：KingbaseES V8R6 及以上版本
Python：3.12 ~ 3.13（ksycopg2驱动仅支持该区间）
包管理工具：uv（官方推荐，替代pip）
MCP客户端：Cursor / TRAE / Claude Desktop
可选数据库扩展（增强分析能力）

sql 复制代码

-- 虚拟索引模拟（模拟新增索引，无需真实创建）
CREATE EXTENSION sys_hypo;
-- 慢查询、负载索引推荐
CREATE EXTENSION sys_stat_statements;

四、完整部署流程（含代码/配置）

4.1 拉取项目源码

bash 复制代码

git clone https://gitee.com/king-db/kingbase-mcp
cd kingbase-mcp

4.2 安装uv与项目依赖

Linux/macOS

bash 复制代码

# 安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 创建虚拟环境并安装依赖
uv venv --python 3.12
source .venv/bin/activate
uv pip install .

Windows PowerShell

bash 复制代码

irm https://astral.sh/uv/install.ps1 | iex
uv venv --python 3.12
.venv\Scripts\activate
uv pip install .

4.3 两种启动方式

方式1：本地Stdio（IDE自动启动，无需手动运行）

仅需在IDE写入MCP配置文件，打开编辑器自动拉起服务。

方式2：手动远程HTTP服务（Streamable HTTP示例）

bash 复制代码

# 配置数据库连接环境变量
export DATABASE_URI="kingbase://ai_mcp:123456@10.xx.xx.21:54321/edu_db"
# 生产安全只读模式启动，监听0.0.0.0外网
uv run kingbase-mcp --access-mode restricted --transport streamable-http --streamable-http-host 0.0.0.0 --streamable-http-port 8000

4.4 IDE MCP配置文件（代码示例）

示例1：Cursor 配置 ~/.cursor/mcp.json（Stdio本地模式，生产restricted）

json 复制代码

{
  "mcpServers": {
    "kes-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/data/code/kingbase-mcp",
        "run",
        "kingbase-mcp",
        "--access-mode",
        "restricted"
      ],
      "env": {
        "DATABASE_URI": "kingbase://ai_mcp:123456@127.0.0.1:54321/edu_db",
        "KSYCOPG2_LIB_PATH": "/home/jenkins/.venv/lib/python3.12/site-packages/ksycopg2"
      }
    }
  }
}

示例2：TRAE Streamable HTTP远程配置

json 复制代码

{
  "mcpServers": {
    "kes-mcp-remote": {
      "type": "streamableHttp",
      "url": "http://10.xx.xx.21:8000/mcp"
    }
  }
}

4.5 核心启动参数说明

bash 复制代码

# 访问模式二选一
--access-mode restricted  # 生产强制：仅SELECT/EXPLAIN/SHOW只读，拦截增删改DDL/DML
--access-mode unrestricted # 仅测试：允许所有数据库操作

# 传输协议切换
--transport stdio / sse / streamable-http
# 端口绑定参数
--streamable-http-host 0.0.0.0 --streamable-http-port 8000

五、内置9大标准MCP工具（能力清单）

所有工具原生适配KES语法，支持国产数据库特有函数、扩展。

工具名称	核心能力	业务场景
list_schemas	列出所有schema，区分系统/业务库	快速梳理库分层
list_objects	指定schema查询表、视图、序列、扩展	批量盘点业务表
get_object_details	查询表字段、约束、主键、索引详情	建表结构核查
execute_sql	执行SQL，restricted模式仅放行只读语句	业务数据查询
explain_query	EXPLAIN / EXPLAIN ANALYZE，支持虚拟索引模拟	SQL慢查询根源定位
analyze_query_indexes	单条SQL推荐最优索引	单语句调优
analyze_workload_indexes	基于历史慢查询负载批量推荐索引	库全局性能优化
analyze_db_health	7项数据库体检：索引/连接/Vacuum/序列/复制/缓存/约束	DBA日常巡检
get_top_queries	按耗时/资源排序输出Top慢SQL	批量性能瓶颈排查

六、完整实战闭环：订单SQL调优全流程

业务背景

订单查询SQL执行全表扫描，耗时高，通过MCP自然语言一站式完成分析、虚拟索引验证。

步骤1：查看orders表结构与现有索引

IDE自然语言输入

复制代码

查看public下orders表的全部字段、主键、普通索引、联合索引

MCP工具get_object_details自动查询KES元数据表，返回：字段类型、长度、主键约束、现有索引列表，AI识别当前查询条件user_id, status无联合索引。

步骤2：分析原始SQL执行计划

待优化SQL：

sql 复制代码

SELECT * FROM orders WHERE user_id = 123 AND status = 'pending';

IDE提问

复制代码

分析这条SQL的真实执行计划，输出扫描类型、代价、索引使用情况：
SELECT * FROM orders WHERE user_id = 123 AND status = 'pending';

底层执行EXPLAIN ANALYZE，返回全表扫描（Seq Scan）、高扫描代价，确认无索引命中。

步骤3：虚拟联合索引模拟（核心零成本能力）

无需真实创建索引，利用sys_hypo扩展模拟(user_id, status)联合索引，对比执行代价。

IDE提问

复制代码

假设给orders表创建联合索引idx_uid_status(user_id, status)，重新分析这条SQL执行计划，对比优化前后扫描代价

MCP执行虚拟索引EXPLAIN，输出Index Scan索引扫描，代价大幅下降，证明索引有效。

步骤4：全局负载批量索引建议

复制代码

分析数据库近一小时慢查询负载，输出可落地索引优化清单

工具analyze_workload_indexes读取sys_stat_statements，批量输出高频SQL缺失索引。

步骤5：数据库健康巡检

复制代码

执行全部数据库健康检查，输出索引膨胀、Vacuum告警、序列不足风险

七、双重安全机制（生产环境必备）

1. restricted 只读安全模式（强制生产启用）

底层采用AST语法树解析SQL，建立操作白名单，拦截以下高危语句：

DDL：ALTER/DROP/TRUNCATE/CREATE
DML：INSERT/UPDATE/DELETE/MERGE
高危运维：VACUUM FULL、锁表语句
仅放行：SELECT、EXPLAIN、SHOW、ANALYZE、元数据查询等只读操作，单SQL最大执行30秒熔断，防止长查询占满连接。

2. 数据库账号最小权限原则

专门创建AI只读账号，仅授予SELECT权限，禁止修改表、数据：

sql 复制代码

-- 创建MCP专用只读账号
CREATE USER ai_mcp WITH PASSWORD 'xxxx';
-- 仅赋予查询权限
GRANT SELECT ON ALL TABLES IN SCHEMA public TO ai_mcp;
-- 限制扩展查询权限
GRANT USAGE ON EXTENSION sys_stat_statements, sys_hypo TO ai_mcp;

双重隔离：MCP拦截高危SQL + 数据库账号无写入权限，杜绝AI误操作篡改业务数据。

八、项目工程结构（Python源码分层）

复制代码

kingbase-mcp/
├── src/kingbase_mcp/
│   ├── server.py                # MCP服务入口、命令行参数、工具注册
│   ├── sql/                     # SQL安全校验、数据库连接池
│   │   ├── sql_driver.py        # KES连接池封装
│   │   └── safe_sql.py          # AST白名单安全校验核心
│   ├── explain/                 # 执行计划、虚拟索引解析
│   ├── index/                   # 索引推荐DTA代价算法
│   ├── top_queries/             # 慢查询统计分析
│   └── database_health/         # 7项健康检查逻辑
├── tests/                       # 单元测试用例
├── pyproject.toml               # 项目依赖配置
└── justfile                     # 开发快捷脚本（test/dev/build）

九、常见问题与最佳实践

ksycopg2驱动找不到libkci.so
Linux环境配置环境变量指定库路径：
bash 复制代码
```
export KSYCOPG2_LIB_PATH=.venv/lib/python3.12/site-packages/ksycopg2
```
Mac系统无法运行
ksycopg2无Mac原生包，临时兼容方案：替换psycopg2伪装驱动连接KES。
生产环境规范
- 固定使用--access-mode restricted；
- 采用Streamable HTTP + HTTPS反向代理部署；
- MCP账号仅分配SELECT最小权限；
  安装sys_hypo/sys_stat_statements扩展完整使用索引分析能力。

编译/代码检查脚本

bash 复制代码

# 代码格式化+静态检查
uv run ruff format .
uv run ruff check .
# 类型校验
uv run pyright
# 单元测试（需配置DATABASE_URI）
uv run pytest