mydb-kingbase-mcp

人大金仓 KingbaseES MCP Server · WorkBuddy 连接器

为 AI 助手提供 KingbaseES（KES）数据库的结构探索、SQL 执行、执行计划分析、索引优化、健康检查与慢查询分析能力。

作者

项目	署名
作者	严少安
事务所	少安事务所
主页	https://shawnyan.cn
联系	admin@shawnyan.cn
PyPI	mydb-kingbase-mcp

本项目派生自 KingbaseES MCP Server（Apache-2.0）， 上游著作权人 Johann Schleier-Smith / 人大金仓保留原始权利，详见 NOTICE。

环境要求

组件	版本要求	说明
Python	3.12+	ksycopg2 驱动最高支持 Python 3.13
MCP Python SDK	2.x（mcp[cli]>=2.2.0,<3）	FastMCP 在 2.x 中更名为 MCPServer
MCP 协议	2025-11-25	经 stdio / SSE / streamable-http 三种传输验证
KingbaseES	V8R6+	本仓库在 V9（V009R200C013PS002）实测通过
数据库驱动	ksycopg2 ≥ 2.9.0	macOS / Alpine 无官方 wheel，可用 psycopg2 替代
可选扩展	sys_hypo、sys_stat_statements	不安装则索引/慢查询分析不可用

架构

MCP Server 作为 AI 工具与 KingbaseES 之间的桥梁：

1. AI 客户端 发送自然语言请求（如「找出最慢的查询」）
2. MCP Server 解析请求，调用对应工具
3. KingbaseES 执行查询并返回结果
4. AI 客户端 展示结果并给出分析建议

能力清单

• 结构探索：列出 schema、表、视图，查看列 / 约束 / 索引详情
• SQL 执行：执行任意 SQL；restricted 为 AST 白名单受限模式
• 执行计划分析：EXPLAIN（unrestricted 下可用 EXPLAIN ANALYZE），支持假设索引模拟
• 索引优化：基于代价模型 DTA 算法，从查询负载推荐索引
• 健康检查：7 项 — 索引、连接、vacuum、序列、复制、缓存、约束
• 慢查询分析：按总耗时 / 均值耗时 / 资源消耗排序的 Top N
• 配置诊断：analyze_db_config 分析内存 / 并行 / WAL / autovacuum / planner 参数
• 多传输方式：Stdio、SSE、Streamable HTTP

Tools

Tool	说明	主要参数
list_schemas	列出所有 schema，区分系统 / 用户 schema	无
list_objects	列出指定 schema 下的表、视图、序列、扩展	schema_name, object_type
get_object_details	查看表 / 视图的列定义、约束、索引详情	schema_name, object_name, object_type
execute_sql	执行 SQL；restricted 仅放行白名单内只读语句	sql
explain_query	执行 EXPLAIN，支持假设索引模拟	sql, analyze, hypothetical_indexes
analyze_workload_indexes	基于 sys_stat_statements 的负载索引推荐	max_index_size_mb, method, min_calls, min_avg_time_ms, limit
analyze_query_indexes	对指定 SQL 列表（≤10 条）推荐索引	queries, max_index_size_mb, method
analyze_db_health	执行 7 项数据库健康检查	health_type（index / index,buffer / all）
get_top_queries	返回 Top N 慢查询	sort_by, limit（1–100）
analyze_db_config	分析配置参数并给出优化建议	parameter（可选）

参数约束均为 schema 级校验（@validate_call + Literal），非法入参在触达数据库前即被拒绝。 object_type 仅接受 table / view / sequence / extension；sort_by 仅接受 resources / mean_time / total_time；min_calls ≥ 1、min_avg_time_ms ≥ 0、limit 取值 1–200。

Resources

Resource URI	说明
kingbase://server/info	服务器元信息：访问模式、工具清单、可选扩展依赖映射
kingbase://schema/overview	Schema 概览（含系统 / 用户分类），等价于 list_schemas 的 JSON 形态

服务器还在初始化时下发 instructions，说明推荐工作流（探索 → 查询 → 诊断 → 索引建议）、 restricted 模式限制，以及 sys_stat_statements / sys_hypo 可选扩展依赖。

安装

方式一：作为 WorkBuddy 连接器（推荐）

在 WorkBuddy 连接器市场搜索 mydb-kingbase-mcp 安装，安装时填入数据库连接串即可。

方式二：uvx 直接运行

uvx mydb-kingbase-mcp==1.0.0 kingbase://user:password@host:port/dbname --access-mode restricted

方式三：源码安装

# 安装 uv：https://astral.sh/uv
uv venv --python 3.12
uv pip install .

驱动说明

• ksycopg2 在 PyPI 仅发布 Linux x86_64/AArch64 与 Windows 版本，其他平台需从 Kingbase 官网下载页 手动安装。
• macOS / Alpine 明确不支持 ksycopg2，可改用 psycopg2 访问 KingbaseES。
• Linux 下若报 libkci.so* 找不到，用 KSYCOPG2_LIB_PATH 指定库路径。

配置

环境变量

变量	必填	说明
DATABASE_URI	是	kingbase://user:password@host:port/dbname
KSYCOPG2_LIB_PATH	Windows 不需要，Linux 可选	libkci.so* 所在路径
KINGBASE_MCP_LLM_MODEL	否	LLM 模型名，默认 gpt-4o
KINGBASE_MCP_LLM_BASE_URL	否	LLM API 基础 URL，留空用 OpenAI 默认
KINGBASE_MCP_LLM_API_KEY	否	LLM API Key，留空用 OPENAI_API_KEY

CLI 参数

参数	默认值	可选值
--access-mode	restricted	restricted / unrestricted
--transport	stdio	stdio / sse / streamable-http
--sse-host / --sse-port	localhost / 8000	任意可监听地址 / 1–65535
--streamable-http-host / --streamable-http-port	localhost / 8000	任意可监听地址 / 1–65535

访问模式

模式	说明	场景
restricted	AST 白名单只读模式，禁止 DML / DDL / VACUUM / ANALYZE / CREATE EXTENSION，30s 超时	生产环境
unrestricted	允许全部 SQL（DDL + DML）	开发调试

MCP 客户端配置

Stdio（WorkBuddy 连接器默认方式）

{
  "mcpServers": {
    "mydb-kingbase-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mydb-kingbase-mcp==1.0.0", "--access-mode", "restricted"],
      "env": {
        "DATABASE_URI": "${DATABASE_URI}",
        "PYTHONUTF8": "1",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

入口等价写法：kingbase-mcp（控制台脚本）或 python -m kingbase_mcp（模块方式）。

SSE / Streamable HTTP（远程部署）

远程部署时，服务端与客户端配置如下。注意：以下 URL 仅用于本地回环调试；生产环境必须使用 HTTPS， 详见下方 传输安全。

# 本地调试（仅回环地址，不对外暴露）
export DATABASE_URI="kingbase://user:password@host:port/dbname"
uv run kingbase-mcp --transport sse --sse-host 127.0.0.1 --sse-port 8000
uv run kingbase-mcp --transport streamable-http --streamable-http-host 127.0.0.1 --streamable-http-port 8000

{
  "mcpServers": {
    "mydb-kingbase-mcp-sse": {
      "type": "sse",
      "url": "https://<your-mcp-host>/sse"
    },
    "mydb-kingbase-mcp-http": {
      "type": "streamableHttp",
      "url": "https://<your-mcp-host>/mcp"
    }
  }
}

传输安全

Stdio 传输由客户端以子进程启动，进程边界即安全边界。HTTP 传输是网络服务，部署时请注意：

1. 生产环境必须使用 HTTPS。 本版本不内置 TLS，sse / streamable-http 端点不提供证书。 对外提供服务时，请在反向代理（nginx / haproxy / 云网关）之后运行并由反代终止 TLS， 客户端配置使用 https:// 地址；http:// 仅允许用于 127.0.0.1 / localhost 本地回环调试。

   # 参考：反代终止 TLS，后端走回环
   server {
       listen 443 ssl;
       server_name mcp.example.com;
       ssl_certificate     /etc/ssl/certs/mcp.crt;
       ssl_certificate_key /etc/ssl/private/mcp.key;
   
       location /mcp {
           proxy_pass http://127.0.0.1:8000/mcp;
           proxy_set_header Host $host;
           proxy_set_header X-Forwarded-Proto https;
       }
   }
   

2. 保持默认 loopback 绑定。 SDK 仅在绑定 127.0.0.1 / localhost / ::1 时自动开启 Host / Origin 头校验（DNS rebinding 防护）；绑定 0.0.0.0 时该防护不生效。

   绑定地址	DNS rebinding 防护
   localhost / 127.0.0.1 / ::1（默认）	自动开启
   0.0.0.0 / :: / 其他地址	不生效

3. 本版本未内置认证。 任何能访问该端口的客户端都可调用全部工具，生产部署必须由反代承担 访问控制（mTLS / OAuth / IP 白名单 / API Key 网关）。

4. 受限模式安全边界。 restricted 模式为 AST 白名单 + 只读事务约束 + 30s 超时 + 500+ 白名单函数 + 连接池上限 5；建议配合最小权限数据库账号使用。

开发与测试

# 单元测试（无需数据库）
uv run pytest tests/unit --ignore=tests/unit/explain/test_explain_plan_real_db.py \
    --ignore=tests/unit/database_health/test_database_health_tool.py -v

# 全量测试（需设置 DATABASE_URI）
uv run pytest -v

# 代码检查
uv run ruff check . && uv run ruff format . && uv run pyright

# 快捷命令
just test   # 运行测试
just build  # 构建发行包

项目结构

mydb-kingbase-mcp/
├── src/kingbase_mcp/
│   ├── server.py                MCP Server 入口、工具注册与 CLI 解析
│   ├── artifacts.py             执行计划结果数据模型
│   ├── sql/                     驱动封装与 SQL 安全控制
│   │   ├── sql_driver.py        连接池与 SQL 执行
│   │   ├── safe_sql.py          AST 白名单与受限执行约束
│   │   ├── bind_params.py       $N 占位符与统计信息解析
│   │   ├── index.py             索引定义数据结构
│   │   └── extension_utils.py   扩展可用性与版本检测
│   ├── explain/explain_plan.py  执行计划分析与假设索引模拟
│   ├── index/                   索引推荐（DTA / LLM / 基类 / 展示）
│   ├── top_queries/             慢查询提取与排序
│   ├── database_health/         7 类健康检查
│   └── db_config/               配置参数分析
├── connector/mydb-kingbase-mcp/ WorkBuddy 连接器包（plugin.json / mcp.json / SKILL.md）
├── tests/                       单元测试
└── imgs/                        架构图

许可证

Apache License 2.0，详见 LICENSE；派生来源声明见 NOTICE。

主页：https://shawnyan.cn