Metadata-Version: 2.5
Name: mydb-kingbase-mcp
Version: 1.0.0
Summary: KingbaseES MCP Server - database structure exploration, SQL execution, execution plan analysis, index optimization, health check and slow query analysis for KingbaseES
Project-URL: Homepage, https://shawnyan.cn
Project-URL: Repository, https://gitee.com/king-db/kes-mcp-server
Project-URL: Issues, https://gitee.com/king-db/kes-mcp-server/issues
Author-email: 严少安 / 少安事务所 <admin@shawnyan.cn>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: database,health-check,index,kes,kingbase,kingbasees,mcp,mcp-server,model-context-protocol,performance,sql
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: attrs>=25.4.0
Requires-Dist: humanize>=4.15.0
Requires-Dist: instructor>=1.14.4
Requires-Dist: ksycopg2>=2.9.0
Requires-Dist: mcp[cli]<3,>=2.2.0
Requires-Dist: pglast==7.11
Description-Content-Type: text/markdown

# mydb-kingbase-mcp

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

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

[![MCP](https://img.shields.io/badge/MCP_SDK-2.x-green)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![KingbaseES](https://img.shields.io/badge/KingbaseES-V8R6%2B-orange)](https://www.kingbase.com.cn/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue)](LICENSE)

## 作者

| 项目 | 署名 |
| --- | --- |
| 作者 | 严少安 |
| 事务所 | 少安事务所 |
| 主页 | <https://shawnyan.cn> |
| 联系 | admin@shawnyan.cn |
| PyPI | [mydb-kingbase-mcp](https://pypi.org/project/mydb-kingbase-mcp/) |

> 本项目派生自 [KingbaseES MCP Server](https://gitee.com/king-db/kes-mcp-server)（Apache-2.0），
> 上游著作权人 Johann Schleier-Smith / 人大金仓保留原始权利，详见 [NOTICE](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` | 不安装则索引/慢查询分析不可用 |

## 架构

<div align="left">
  <img src="./imgs/readme_framework.drawio.png" alt="KingbaseES + MCP + LLM 架构" width="640">
</div>

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 直接运行

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

### 方式三：源码安装

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

> **驱动说明**
>
> - ksycopg2 在 PyPI 仅发布 Linux x86_64/AArch64 与 Windows 版本，其他平台需从
>   [Kingbase 官网下载页](https://www.kingbase.com.cn/download.html#drive) 手动安装。
> - 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 连接器默认方式）

```json
{
  "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**，
详见下方 [传输安全](#传输安全)。

```bash
# 本地调试（仅回环地址，不对外暴露）
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
```

```json
{
  "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` 本地回环调试。

   ```nginx
   # 参考：反代终止 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；建议配合最小权限数据库账号使用。

## 开发与测试

```bash
# 单元测试（无需数据库）
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](LICENSE)；派生来源声明见 [NOTICE](NOTICE)。

主页：<https://shawnyan.cn>