gaussdb-ro-mcp

Servidor MCP de solo lectura para Huawei GaussDB (centralizado y distribuido), diseñado para agentes de codificación. Protección de escritura en tres capas, configuración multi-instancia, exploración de esquemas y ejecución de un solo SELECT.

GitHub
1

Documentación

gaussdb-ro-mcp

CI Glama

Servidor MCP de solo lectura para GaussDB, orientado a agentes de codificación (Claude Code, OpenCode, etc.). Basado en el controlador oficial de Go para GaussDB (adaptación oficial de pgx v5 de código abierto de Huawei Cloud, con el código fuente incluido en el repositorio en third_party/gaussdb-go, compatible con compilación sin conexión), proporciona herramientas de exploración de bases de datos de solo lectura mediante transporte stdio.

Diseñado específicamente para entornos de intranet sin SSL: por defecto sslmode=disable, y el archivo de configuración admite la gestión simultánea de múltiples instancias de GaussDB.

Garantía de solo lectura (defensa en profundidad de tres capas)

CapaMecanismoDescripción
1. Validación estática de SQLinternal/guardSolo permite consultas individuales SELECT/WITH: rechaza DML/DDL (incluidas sentencias de escritura dentro de CTE), SELECT ... INTO, bloqueos de fila FOR UPDATE/SHARE, múltiples sentencias, funciones peligrosas (dblink*, set_config, setval, pg_read_file*, pg_terminate_backend, pg_advisory_*, escritura de objetos grandes, etc., configurable). El análisis léxico omite correctamente cadenas, comentarios e identificadores entre comillas para evitar falsos positivos
2. Imposición a nivel de transaccióninternal/dbTodas las consultas se ejecutan de forma uniforme en transacciones de solo lectura explícitas: BEGIN → SET LOCAL TRANSACTION READ ONLY → consulta → COMMIT (reversión en caso de fallo). La versión distribuida de GaussDB solo admite la configuración de solo lectura a nivel de transacción; este método funciona tanto en instancias centralizadas/activo-pasivo como distribuidas; también se establece SET statement_timeout. Incluso si se omite la capa 1, el servidor rechazará cualquier escritura dentro de la transacción (incluidas las escrituras dentro de funciones)
3. Recomendación de implementaciónREADMESe recomienda usar una cuenta de base de datos con solo permisos SELECT (ver más abajo) para lograr el principio de privilegio mínimo

Herramientas MCP proporcionadas

HerramientaFunción
test_connectionPrueba de conectividad: versión del servidor, base de datos/usuario actual, estado de solo lectura, latencia; parámetro opcional instance
list_schemasListado de esquemas: número de objetos, comentarios; include_system controla si se incluyen esquemas del sistema
list_tablesListado de tablas/vistas: tipo (tabla/vista/vista materializada/tabla particionada/tabla externa), filas estimadas, comentarios; se puede filtrar por schema
describe_tableEstructura de tabla: columnas (tipo/nulabilidad/valor predeterminado/comentario), clave primaria y restricciones, todos los índices y sus definiciones; para vistas devuelve el SQL de definición de la vista; para tablas particionadas devuelve la lista de particiones (GaussDB pg_partition)
execute_selectEjecutar SELECT: solo acepta una única sentencia SELECT/WITH, sujeta a límites de max_rows/tiempo de espera, devuelve nombres de columnas + datos de filas + indicador de truncamiento

Todas las herramientas aceptan el parámetro opcional instance para seleccionar la fuente de datos; por defecto se usa default_instance.

Instalación

Descargue el binario correspondiente a su plataforma desde Releases (linux-amd64 / linux-arm64 / darwin-arm64 / windows-amd64.exe; para otras plataformas o entornos de intranet puede compilarlo usted mismo, consulte la siguiente sección).

Linux:

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):

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; colóquelo en un directorio del PATH para invocarlo directamente):

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

Los valores de verificación de cada artefacto se encuentran en la sección SHA256SUMS.txt de la página de Releases.

Compilación

Requiere Go 1.26+ (coincide con go.mod). El código fuente del controlador está incluido en third_party/gaussdb-go (referenciado mediante la directiva replace). En un entorno con conexión a internet, go build resolverá automáticamente las demás dependencias; en un entorno de intranet puro, ejecute primero go mod vendor en un entorno con conexión y luego lleve el directorio vendor/ y compile con go build -mod=vendor.

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

Compilación cruzada para otras plataformas (Go puro, basta con CGO_ENABLED=0): CGO_ENABLED=0 GOOS=<os> GOARCH=<arch> go build -o ... ./cmd/gaussdb-ro-mcp.

Configuración

Copie gaussdb-ro-mcp.example.yaml como gaussdb-ro-mcp.yaml y modifíquelo. Orden de búsqueda del archivo de configuración: parámetro -config > variable de entorno GAUSSDB_RO_MCP_CONFIG > ./gaussdb-ro-mcp.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

Integración con agentes de codificación

Claude Code

Opción 1: en el directorio raíz del proyecto, .mcp.json (o comando claude mcp add):

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

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

OpenCode

opencode.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"]
    }
  }
}

Cuenta de solo lectura en la base de datos (muy recomendado)

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;
-- 其他模式按需逐个授权

Incluso si la cuenta de base de datos está limitada a solo lectura, la validación de SQL y la imposición de sesión de este servicio seguirán bloqueando bloqueos de fila (FOR UPDATE), SELECT INTO, llamadas a funciones peligrosas, consultas largas y otros comportamientos.

Registros

Todos los registros de ejecución se envían a stderr (stdout es el canal del protocolo MCP), incluidos la carga de configuración, la preparación de fuentes de datos, los resultados de validación de sesión de solo lectura, etc., para facilitar la resolución de problemas en los registros MCP del cliente agente.

Desarrollo y pruebas

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

Puede usar Docker para iniciar rápidamente una instancia de prueba de openGauss y cargar datos de prueba:

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"

Las pruebas de integración cubren: imposición de sesión de solo lectura (el servidor rechaza escrituras), comportamiento de extremo a extremo de las 5 herramientas, prueba de humo del subproceso stdio del binario real. Nota: este controlador utiliza el protocolo extendido de GaussDB (3.51), no puede conectarse a PostgreSQL nativo; las pruebas de integración requieren una instancia real de GaussDB / openGauss.

Estructura de directorios

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 引用）

Comentarios y contribuciones

Las Issues y Pull Requests son bienvenidas: