gxc/gaussdb-ro-mcp

[简体中文] | English
> [!NOTE]
> English: A read-only MCP server for Huawei GaussDB (centralized & distributed), built for
> coding agents (Claude Code, OpenCode, etc.). Three layers of read-only enforcement — static SQL
> validation, server-side READ ONLY transactions, and least-privilege account guidance — in a
> single static binary designed for non-SSL intranet environments. Full documentation:
> READMEen.md.
面向 Coding Agent（Claude Code、OpenCode 等）的 GaussDB 只读 MCP 服务器。基于
GaussDB 官方 Go 驱动
（华为云官方开源的 pgx v5 适配版，源码随仓库内置于 thirdparty/gaussdb-go，支持离线构建），
通过 stdio 传输提供数据库只读探查工具。
专为内网非 SSL 环境设计：默认 sslmode=disable，配置文件支持同时管理多个 GaussDB 实例。
## 只读保障（三层纵深防御）
| 层级 | 机制 | 说明 |
| 1. SQL 静态校验 | internal/guard | 仅放行单条 SELECT/WITH 查询：拒绝 DML/DDL（含 CTE 内写语句）、SELECT ... INTO、FOR UPDATE/SHARE 行锁、多语句、危险函数（dblink、setconfig、setval、pgreadfile、pgterminatebackend、pgadvisory、大对象写等，可配置）。词法分析正确跳过字符串/注释/引号标识符，避免误报 |
| 2. 事务级强制 | internal/db | 所有查询统一在显式只读事务中执行：BEGIN → SET LOCAL TRANSACTION READ ONLY → 查询 → COMMIT（失败回滚）。GaussDB 分布式版仅支持事务级只读设置，该方式在集中式/主备与分布式实例上通用；另设 SET statementtimeout。即使第 1 层被绕过，服务端也会拒绝事务内一切写入（包括函数内部的写） |
| 3. 部署建议 | README | 建议使用仅授予 SELECT 权限的数据库账号（见下文），实现权限最小化 |
## 提供的 MCP 工具
| 工具 | 功能 |
| testconnection | 连通性测试：服务器版本、当前库/用户、只读状态、延迟；可选 instance 参数 |
| listschemas | schema（模式）清单：对象数、注释；includesystem 控制是否含系统模式 |
| listtables | 表/视图清单：类型（表/视图/物化视图/分区表/外表）、估算行数、注释；可按 schema 过滤 |
| describetable | 表结构：列（类型/可空/默认值/注释）、主键与约束、全部索引及定义；视图返回视图定义 SQL；分区表返回分区清单（GaussDB pgpartition） |
| executeselect | 执行 SELECT：仅接受单条 SELECT/WITH，受 maxrows/超时限制，返回列名+行数据+是否截断 |
所有工具均接受可选 instance 参数以选择数据源，缺省使用 defaultinstance。全部实例名（含默认标注）会写入该参数的 schema 描述，agent 在获取工具列表阶段即可发现可选实例，无需试错。
## 与同类项目对比
| | gaussdb-ro-mcp（本项目） | GaussDB-MCP | Multi DB MCP | 通用 PostgreSQL MCP 服务器 |
| 定位 | GaussDB 专用只读探查 | GaussDB 全功能访问：查询、写入、事务、诊断运维、用户权限 | 17 种数据库通用连接器（含 GaussDB/openGauss），MCP + REST API | 原生 PostgreSQL |
| GaussDB 适配 | 官方 Go 驱动，集中式/主备/分布式均适配 | 官方 Node.js 驱动（gaussdb-node） | 走 PostgreSQL 通用协议 | 未适配 GaussDB 专有系统目录（如 pgpartition） |
| 只读保障 | 三层纵深防御：SQL 静态校验 + 事务级 READ ONLY 强制 + 最小权限建议 | 无只读模式（默认 root 管理员账号，按设计支持写入） | 应用层默认只读 | 各项目实现不一 |
| GaussDB 特有元数据 | 分区表（pgpartition）、外表、物化视图、视图定义 SQL、全部索引定义 | 部分支持 | 按 PG 协议探测，部分支持 | 无 |
| 运行时依赖 | 无（静态编译单二进制，可离线部署） | Node.js ≥ 20 | Node.js（npx） | 各异 |
| 多实例管理 | 配置文件集中管理多实例，工具按 instance 参数切换 | 单实例（环境变量） | 单连接（启动参数） | 一般单实例 |
| 内网非 SSL | 默认 sslmode=disable | 支持（默认关闭 SSL） | 支持 | 支持 |
| 许可证 | Apache-2.0 | 未声明 | 未声明 | 各异 |
各项目定位不同：需要完整读写与运维能力时，全功能服务器是合理选择；如果目标是让
Coding Agent 安全地探查数据（尤其在生产库上），只读约束与纵深防御是本项目的价值所在。
以上信息基于各项目公开 README 整理（2026-10），如有出入欢迎
提 Issue 指正。
## 安装
从 Releases 下载对应平台的二进制
（linux-amd64 / linux-arm64 / darwin-arm64 / windows-amd64.exe；其他平台或内网环境可自行构建，见下节）。
Linux：
bash
curl -LO https://github.com/gxc/gaussdb-ro-mcp/releases/latest/download/gaussdb-ro-mcp-linux-amd64
sudo install -Dm 755 gaussdb-ro-mcp-linux-amd64 /usr/local/bin/gaussdb-ro-mcp
gaussdb-ro-mcp --version
macOS（Apple Silicon）：
bash
curl -LO https://github.com/gxc/gaussdb-ro-mcp/releases/latest/download/gaussdb-ro-mcp-darwin-arm64
sudo install -Dm 755 gaussdb-ro-mcp-darwin-arm64 /usr/local/bin/gaussdb-ro-mcp
gaussdb-ro-mcp --version
Windows（PowerShell；放入 PATH 目录后即可直接调用）：