kingbase-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NekoTarou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# KingBase MCP Server
+
+[English](#english) | 中文
+
+直连 [KingBase](https://www.kingbase.com.cn/)（PostgreSQL 兼容）数据库的 MCP Server，让 AI 助手（Claude 等）能够直接查询和管理 KingBase 数据库。
+
+## 快速使用
+
+无需克隆代码，直接在 MCP 客户端中配置即可使用：
+
+```json
+{
+  "mcpServers": {
+    "kingbase": {
+      "command": "npx",
+      "args": ["-y", "kingbase-mcp-server"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_PORT": "54321",
+        "DB_USER": "system",
+        "DB_PASSWORD": "your_password",
+        "DB_NAME": "kingbase",
+        "DB_SCHEMA": "public",
+        "ACCESS_MODE": "readonly"
+      }
+    }
+  }
+}
+```
+
+也可以全局安装后使用：
+
+```bash
+npm install -g kingbase-mcp-server
+kingbase-mcp-server
+```
+
+## 功能
+
+| Tool | 说明 | 类型 |
+|------|------|------|
+| `kb_query` | 执行只读查询 (SELECT/WITH/SHOW) | 只读 |
+| `kb_execute` | 执行 DML (INSERT/UPDATE/DELETE) | 读写 |
+| `kb_execute_ddl` | 执行 DDL (CREATE/ALTER/DROP) | 读写 |
+| `kb_list_schemas` | 列出所有 schema | 只读 |
+| `kb_list_tables` | 列出表和视图 | 只读 |
+| `kb_describe_table` | 查看表结构（列、类型、约束、注释） | 只读 |
+| `kb_list_indexes` | 查看索引信息 | 只读 |
+| `kb_list_constraints` | 查看约束信息 | 只读 |
+| `kb_explain` | 查看执行计划 (EXPLAIN) | 只读 |
+| `kb_table_data` | 预览表数据（带分页和过滤） | 只读 |
+| `kb_table_stats` | 查看表统计信息（大小、行数等） | 只读 |
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `DB_HOST` | 数据库主机 | `localhost` |
+| `DB_PORT` | 数据库端口 | `54321` |
+| `DB_USER` | 用户名 | `system` |
+| `DB_PASSWORD` | 密码 | (空) |
+| `DB_NAME` | 数据库名 | `kingbase` |
+| `DB_SCHEMA` | 默认 schema | `public` |
+| `TRANSPORT` | 传输模式：`stdio` 或 `http` | `stdio` |
+| `MCP_PORT` | HTTP 模式监听端口 | `3000` |
+| `MCP_HOST` | HTTP 模式监听地址 | `0.0.0.0` |
+| `ACCESS_MODE` | 权限模式（见下方说明） | `readonly` |
+
+## 权限模式
+
+通过 `ACCESS_MODE` 环境变量控制数据库操作权限，分为 4 个递增级别：
+
+| 级别 | 值 | 允许的操作 |
+|------|------|-----------|
+| 只读 | `readonly`（默认） | SELECT 查询、查看 schema/表结构/索引/约束/统计/执行计划 |
+| 允许修改 | `readwrite` | 只读 + INSERT / UPDATE |
+| 允许删除 | `full` | 读写 + DELETE |
+| 管理员 | `admin` | 完全权限 + DDL（CREATE / ALTER / DROP / TRUNCATE） |
+
+**默认为 `readonly`（只读模式）**，防止误操作。根据实际需要调整。
+
+### 二次确认机制
+
+`kb_execute`（DML）和 `kb_execute_ddl`（DDL）工具内置二次确认：
+
+1. **首次调用**（不传 `confirmed` 或 `confirmed: false`）→ 不执行 SQL，返回操作预览和确认提示
+2. **确认调用**（`confirmed: true`）→ 真正执行 SQL
+
+这确保 LLM 在执行写操作前必须向用户确认，避免意外修改数据。
+
+### 配置示例
+
+```bash
+# 只读模式（默认，推荐用于日常查询）
+ACCESS_MODE=readonly
+
+# 允许增改（适用于数据维护）
+ACCESS_MODE=readwrite
+
+# 允许删除（适用于数据清理）
+ACCESS_MODE=full
+
+# 管理员模式（适用于 DDL 操作，如建表/改表）
+ACCESS_MODE=admin
+```
+
+## 传输模式
+
+### stdio 模式（默认）
+
+适用于本地使用，客户端直接启动 MCP Server 进程。
+
+### HTTP 模式
+
+适用于远程部署，团队成员通过网络连接。使用 MCP Streamable HTTP 传输协议。
+
+启动 HTTP 模式：
+
+```bash
+TRANSPORT='http' MCP_PORT='3000' DB_HOST='你的数据库地址' DB_PASSWORD='你的密码' node dist/index.js
+# 或
+npm run start:http
+```
+
+验证：
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+```
+
+## 在 Claude Code 中使用
+
+### stdio 模式（推荐）
+
+编辑 `~/.claude/settings.json`，添加：
+
+```json
+{
+  "mcpServers": {
+    "kingbase": {
+      "command": "npx",
+      "args": ["-y", "kingbase-mcp-server"],
+      "env": {
+        "DB_HOST": "你的数据库地址",
+        "DB_PORT": "54321",
+        "DB_USER": "system",
+        "DB_PASSWORD": "你的密码",
+        "DB_NAME": "数据库名",
+        "DB_SCHEMA": "public",
+        "ACCESS_MODE": "readonly"
+      }
+    }
+  }
+}
+```
+
+### HTTP 模式（远程连接）
+
+在服务器上启动 HTTP 模式后，客户端配置：
+
+```json
+{
+  "mcpServers": {
+    "kingbase": {
+      "url": "http://你的服务器地址:3000/mcp"
+    }
+  }
+}
+```
+
+## 构建
+
+```bash
+npm install
+npm run build
+```
+
+## 配置文件
+
+项目支持 `.env` 配置文件，**避免在 shell 中直接传入含特殊字符的密码导致解析失败**。
+
+```bash
+# 复制模板
+cp .env.example .env
+
+# 编辑配置（密码中的特殊字符无需转义）
+vi .env
+```
+
+`.env` 文件示例：
+
+```
+DB_HOST=192.168.1.100
+DB_PORT=54321
+DB_USER=system
+DB_PASSWORD=P@ss(w0rd)!#$
+DB_NAME=mydb
+DB_SCHEMA=public
+TRANSPORT=http
+MCP_PORT=3000
+ACCESS_MODE=readonly
+```
+
+配置好后直接启动即可，无需在命令行传递环境变量：
+
+```bash
+node dist/index.js
+# 或
+npm start
+```
+
+> `.env` 已在 `.gitignore` 中，不会被提交到仓库。命令行传入的环境变量优先级高于 `.env` 文件。
+
+## 服务器部署（HTTP 模式）
+
+### 1. 安装
+
+```bash
+# 方式一：npm 全局安装（推荐）
+npm install -g kingbase-mcp-server
+
+# 方式二：从源码安装
+git clone https://github.com/NekoTarou/kingbase-mcp-server.git
+cd kingbase-mcp-server
+npm install
+npm run build
+```
+
+### 2. 直接启动
+
+```bash
+TRANSPORT='http' \
+MCP_PORT='3000' \
+ACCESS_MODE='readonly' \
+DB_HOST='192.168.1.100' \
+DB_PORT='54321' \
+DB_USER='system' \
+DB_PASSWORD='your_password' \
+DB_NAME='mydb' \
+node dist/index.js
+```
+
+### 3. 使用 systemd 管理（推荐）
+
+创建环境变量文件 `/etc/kingbase-mcp-server.env`：
+
+```
+TRANSPORT=http
+MCP_PORT=3000
+MCP_HOST=0.0.0.0
+ACCESS_MODE=readonly
+DB_HOST=192.168.1.100
+DB_PORT=54321
+DB_USER=system
+DB_PASSWORD=your_password
+DB_NAME=mydb
+DB_SCHEMA=public
+```
+
+创建服务文件 `/etc/systemd/system/kingbase-mcp.service`：
+
+```ini
+[Unit]
+Description=KingBase MCP Server
+After=network.target
+
+[Service]
+Type=simple
+EnvironmentFile=/etc/kingbase-mcp-server.env
+WorkingDirectory=/opt/kingbase-mcp-server
+ExecStart=/usr/bin/node dist/index.js
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启动服务：
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable kingbase-mcp
+sudo systemctl start kingbase-mcp
+sudo systemctl status kingbase-mcp   # 查看状态
+sudo journalctl -u kingbase-mcp -f   # 查看日志
+```
+
+### 4. 验证
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+```
+
+成功会返回 JSON 响应，response header 中包含 `mcp-session-id`。
+
+### 5. 安全提示
+
+当前未内置认证机制。如果服务暴露在公网，建议：
+
+- 通过防火墙限制访问来源 IP
+- 在前面加 nginx 反向代理 + 基础认证
+- 后续可按需添加 OAuth 认证
+
+---
+
+<a id="english"></a>
+
+## English
+
+MCP (Model Context Protocol) server for [KingBase](https://www.kingbase.com.cn/) — a PostgreSQL-compatible enterprise database widely used in Chinese government and enterprise environments.
+
+### Quick Start
+
+```json
+{
+  "mcpServers": {
+    "kingbase": {
+      "command": "npx",
+      "args": ["-y", "kingbase-mcp-server"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_PORT": "54321",
+        "DB_USER": "system",
+        "DB_PASSWORD": "your_password",
+        "DB_NAME": "kingbase",
+        "ACCESS_MODE": "readonly"
+      }
+    }
+  }
+}
+```
+
+### Features
+
+- 11 database tools: query, DML, DDL, schema inspection, statistics
+- Two transport modes: stdio (local) and Streamable HTTP (remote)
+- Fine-grained access control: `readonly` / `readwrite` / `full` / `admin`
+- Two-phase confirmation for write operations
+- Auto schema qualification for table names
+- Parameterized queries for safe value substitution
+
+See above sections for detailed documentation (in Chinese).
+
+## License
+
+[MIT](./LICENSE)