# gaussdb-ro-mcp

[简体中文] | [English](README_en.md)

[![CI](https://github.com/gxc/gaussdb-ro-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/gxc/gaussdb-ro-mcp/actions/workflows/ci.yml)
[![Glama](https://glama.ai/mcp/servers/gxc/gaussdb-ro-mcp/badges/score.svg)](https://glama.ai/mcp/servers/gxc/gaussdb-ro-mcp)
[![Release](https://img.shields.io/github/v/release/gxc/gaussdb-ro-mcp)](https://github.com/gxc/gaussdb-ro-mcp/releases/latest)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)

> [!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:
> [README_en.md](README_en.md).

面向 Coding Agent（Claude Code、OpenCode 等）的 **GaussDB 只读 MCP 服务器**。基于
[GaussDB 官方 Go 驱动](https://github.com/huaweicloud-samples/database-gaussdb-go)
（华为云官方开源的 pgx v5 适配版，源码随仓库内置于 `third_party/gaussdb-go`，支持离线构建），
通过 stdio 传输提供数据库只读探查工具。

专为**内网非 SSL 环境**设计：默认 `sslmode=disable`，配置文件支持同时管理多个 GaussDB 实例。

## 只读保障（三层纵深防御）

| 层级 | 机制 | 说明 |
| --- | --- | --- |
| 1. SQL 静态校验 | `internal/guard` | 仅放行**单条** `SELECT`/`WITH` 查询：拒绝 DML/DDL（含 CTE 内写语句）、`SELECT ... INTO`、`FOR UPDATE/SHARE` 行锁、多语句、危险函数（`dblink*`、`set_config`、`setval`、`pg_read_file*`、`pg_terminate_backend`、`pg_advisory_*`、大对象写等，可配置）。词法分析正确跳过字符串/注释/引号标识符，避免误报 |
| 2. 事务级强制 | `internal/db` | 所有查询统一在显式只读事务中执行：`BEGIN` → `SET LOCAL TRANSACTION READ ONLY` → 查询 → `COMMIT`（失败回滚）。GaussDB 分布式版仅支持事务级只读设置，该方式在集中式/主备与分布式实例上通用；另设 `SET statement_timeout`。即使第 1 层被绕过，服务端也会拒绝事务内一切写入（包括函数内部的写） |
| 3. 部署建议 | README | 建议使用仅授予 `SELECT` 权限的数据库账号（见下文），实现权限最小化 |

## 提供的 MCP 工具

| 工具 | 功能 |
| --- | --- |
| `test_connection` | 连通性测试：服务器版本、当前库/用户、只读状态、延迟；可选 `instance` 参数 |
| `list_schemas` | schema（模式）清单：对象数、注释；`include_system` 控制是否含系统模式 |
| `list_tables` | 表/视图清单：类型（表/视图/物化视图/分区表/外表）、估算行数、注释；可按 `schema` 过滤 |
| `describe_table` | 表结构：列（类型/可空/默认值/注释）、主键与约束、**全部索引及定义**；视图返回视图定义 SQL；分区表返回分区清单（GaussDB `pg_partition`） |
| `execute_select` | 执行 SELECT：仅接受单条 SELECT/WITH，受 `max_rows`/超时限制，返回列名+行数据+是否截断 |

所有工具均接受可选 `instance` 参数以选择数据源，缺省使用 `default_instance`。全部实例名（含默认标注）会写入该参数的 schema 描述，agent 在获取工具列表阶段即可发现可选实例，无需试错。

## 与同类项目对比

| | gaussdb-ro-mcp（本项目） | [GaussDB-MCP](https://github.com/mengqi1436/GaussDB-MCP) | [Multi DB MCP](https://github.com/the-Rings/universal-db-mcp) | 通用 PostgreSQL MCP 服务器 |
| --- | --- | --- | --- | --- |
| 定位 | GaussDB 专用**只读**探查 | GaussDB 全功能访问：查询、写入、事务、诊断运维、用户权限 | 17 种数据库通用连接器（含 GaussDB/openGauss），MCP + REST API | 原生 PostgreSQL |
| GaussDB 适配 | 官方 Go 驱动，集中式/主备/分布式均适配 | 官方 Node.js 驱动（gaussdb-node） | 走 PostgreSQL 通用协议 | 未适配 GaussDB 专有系统目录（如 `pg_partition`） |
| 只读保障 | 三层纵深防御：SQL 静态校验 + 事务级 READ ONLY 强制 + 最小权限建议 | 无只读模式（默认 root 管理员账号，按设计支持写入） | 应用层默认只读 | 各项目实现不一 |
| GaussDB 特有元数据 | 分区表（`pg_partition`）、外表、物化视图、视图定义 SQL、全部索引定义 | 部分支持 | 按 PG 协议探测，部分支持 | 无 |
| 运行时依赖 | 无（静态编译单二进制，可离线部署） | Node.js ≥ 20 | Node.js（npx） | 各异 |
| 多实例管理 | 配置文件集中管理多实例，工具按 `instance` 参数切换 | 单实例（环境变量） | 单连接（启动参数） | 一般单实例 |
| 内网非 SSL | 默认 `sslmode=disable` | 支持（默认关闭 SSL） | 支持 | 支持 |
| 许可证 | Apache-2.0 | 未声明 | 未声明 | 各异 |

各项目定位不同：需要完整读写与运维能力时，全功能服务器是合理选择；如果目标是让
Coding Agent **安全地**探查数据（尤其在生产库上），只读约束与纵深防御是本项目的价值所在。
以上信息基于各项目公开 README 整理（2026-10），如有出入欢迎
[提 Issue 指正](https://github.com/gxc/gaussdb-ro-mcp/issues)。

## 安装

从 [Releases](https://github.com/gxc/gaussdb-ro-mcp/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 目录后即可直接调用）：

```powershell
Invoke-WebRequest -Uri "https://github.com/gxc/gaussdb-ro-mcp/releases/latest/download/gaussdb-ro-mcp-windows-amd64.exe" -OutFile "gaussdb-ro-mcp.exe"
Move-Item .\gaussdb-ro-mcp.exe "$env:LOCALAPPDATA\Microsoft\WindowsApps\"  # 该目录默认在 PATH 中
gaussdb-ro-mcp --version
```

各产物校验值见 Release 页的 `SHA256SUMS.txt`。

## 构建

要求 Go 1.26.10+（与 go.mod 一致）。驱动源码已内置于 `third_party/gaussdb-go`（通过 `replace` 指令引用），
正常联网环境下 `go build` 会自动解析其余依赖；纯内网环境请先在有网环境执行 `go mod vendor`
后携带 `vendor/` 目录，用 `go build -mod=vendor` 构建。

```bash
go build -o gaussdb-ro-mcp ./cmd/gaussdb-ro-mcp
sudo install -Dm 755 gaussdb-ro-mcp /usr/local/bin/gaussdb-ro-mcp
gaussdb-ro-mcp --version
```

交叉编译其他平台（纯 Go，`CGO_ENABLED=0` 即可）：`CGO_ENABLED=0 GOOS=<os> GOARCH=<arch> go build -o ... ./cmd/gaussdb-ro-mcp`。

## 配置

复制 [gaussdb-ro-mcp.example.yaml](gaussdb-ro-mcp.example.yaml) 为 `gaussdb-ro-mcp.yaml` 并修改。
配置文件查找顺序：`-config` 参数 > 环境变量 `GAUSSDB_RO_MCP_CONFIG` > `./gaussdb-ro-mcp.yaml`。

```yaml
server:
  max_rows: 500          # execute_select 默认行数上限
  max_rows_cap: 10000    # 单次调用可放宽的硬上限
  statement_timeout: 30s
  connect_timeout: 10s

instances:
  - name: prod                    # 实例名称，工具调用时用 instance 参数引用
    host: 192.168.0.10
    port: 8000
    database: postgres
    user: readonly_user
    password: "****"
    sslmode: disable              # 内网非 SSL 默认值
  - name: dev
    dsn: "gaussdb://readonly_user:****@192.168.1.20:5432/appdb?sslmode=disable"

default_instance: prod
```

## 接入 Coding Agent

### Claude Code

方式一：项目根目录 `.mcp.json`（或 `claude mcp add` 命令）：

```json
{
  "mcpServers": {
    "gaussdb-readonly": {
      "command": "/usr/local/bin/gaussdb-ro-mcp",
      "args": ["-config", "/path/to/gaussdb-ro-mcp.yaml"]
    }
  }
}
```

```bash
claude mcp add gaussdb-readonly -- /usr/local/bin/gaussdb-ro-mcp -config /path/to/gaussdb-ro-mcp.yaml
```

### OpenCode

`opencode.json`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gaussdb-readonly": {
      "type": "local",
      "command": ["/usr/local/bin/gaussdb-ro-mcp", "-config", "/path/to/gaussdb-ro-mcp.yaml"]
    }
  }
}
```

## 数据库侧只读账号（强烈建议）

```sql
CREATE USER readonly_user WITH PASSWORD 'your-strong-password';
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly_user;
-- 其他模式按需逐个授权
```

即使数据库账号被限定为只读，本服务的 SQL 校验与会话强制仍会拦截
锁行（`FOR UPDATE`）、`SELECT INTO`、危险函数调用、长查询等行为。

## 日志

所有运行日志输出到 **stderr**（stdout 为 MCP 协议通道），包括配置加载、
数据源就绪、会话只读校验结果等，便于在代理客户端的 MCP 日志中排障。

## 开发与测试

```bash
go test ./...                       # 单元测试（SQL 校验、配置解析）
GAUSSDB_RO_MCP_TEST_DSN="host=... port=... user=... password=... dbname=... sslmode=disable" \
  go test -count=1 ./...            # 集成测试（需 GaussDB/openGauss 实例）
```

可用 Docker 快速起一个 openGauss 测试实例并灌入测试数据：

```bash
docker run -d --name opengauss-ro-test -e GS_PASSWORD='Gaussdb@123' \
  -p 127.0.0.1:15433:5432 --privileged docker.m.daocloud.io/enmotech/opengauss:latest

go run ./scripts/devseed "host=127.0.0.1 port=15433 user=gaussdb password=Gaussdb@123 dbname=postgres sslmode=disable"
```

集成测试覆盖：只读会话强制（服务端拒绝写入）、5 个工具的端到端行为、
真实二进制 stdio 子进程冒烟。注意：本驱动使用 GaussDB 扩展协议（3.51），
无法连接原生 PostgreSQL，集成测试需要真实的 GaussDB / openGauss 实例。

## 目录结构

```
cmd/gaussdb-ro-mcp/     程序入口（stdio MCP 服务器）
internal/config/        YAML 配置：多实例数据源、行数/超时等
internal/guard/         第 1 层防护：SQL 只读静态校验器
internal/db/            多实例连接池 + 第 2 层防护：会话级 READ ONLY 强制、元数据查询
internal/tools/         MCP 工具注册与实现
scripts/devseed/        集成测试数据灌入工具（开发用）
third_party/gaussdb-go/ GaussDB 官方 Go 驱动源码（go.mod replace 引用）
```

## 反馈与贡献

欢迎提交 Issue 和 Pull Request：

- 问题反馈 / 功能建议：<https://github.com/gxc/gaussdb-ro-mcp/issues>
- 获取最新版本：<https://github.com/gxc/gaussdb-ro-mcp/releases/latest>
- 提交 PR 前，请确保 `go vet ./...` 与 `go test ./...` 通过；涉及安全防护逻辑（SQL 静态校验 / 只读强制）的改动请附带回归测试