sqlmcp

package module
v0.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 11, 2026 License: MIT Imports: 0 Imported by: 0

README

SQL MCP Server

The governed SQL gateway for untrusted AI agents.

面向不可信 AI Agent 的受控 SQL 数据访问网关。通过显式 Entity、关系代数 IR 和 参数化 codegen 访问 PostgreSQL、MySQL 与 OceanBase，不接受任意 SQL，不提供 DDL。

核心差异

  • 确定性执行：Agent 只能组合受控工具和白名单 IR；
  • 字段与行治理：RBAC、字段 ACL、row policy 和 mask 统一强制；
  • 成本可控：EXPLAIN 预筛、结果上限、超时和 session/tenant 预算；
  • 默认拒绝：安全能力无法证明时 fail closed；
  • 可审计：配置热重载、异步审计和 OpenTelemetry hook。

运行时安全行为以安全模型为准；Provider 验证边界与证据层级 以兼容矩阵为准；威胁、控制与剩余风险见 威胁模型。所有对外声明的证据汇总见 架构、安全边界与证据索引。不以本页摘要为准。

五分钟体验

只需 Docker 与 Docker Compose：

docker compose -f examples/quickstart/compose.yaml up -d --wait
curl -fsS http://127.0.0.1:8080/healthz

完整的 MCP Inspector 调用、tenant 隔离、mask 和拒绝场景见 五分钟快速体验。

安装与接入

源码构建要求 Go 1.25.12+ 和一个已验证数据库版本：

git clone https://github.com/nethinwei/sql-mcp-server.git
cd sql-mcp-server
make build

按角色阅读

首次体验与集成
部署与安全
开发与维护
版本与规划

许可

MIT

Documentation

Overview

Package sqlmcp provides a SQL MCP server: a relationally complete data access surface for AI agents over PostgreSQL, MySQL, and OceanBase, modeled on Microsoft's Data API Builder SQL MCP Server.

Design pillars:

  • Relational algebra IR (core/relalg + core/codegen) — dialect-neutral, mathematically complete; new databases plug in through core/provider.
  • Defense-in-depth cost & resource gate — EXPLAIN is one optional layer, not a leash; deterministic LIMIT/timeout and DB-native resource limits backstop unreliable estimates.
  • Enterprise safety — RBAC with row-level security, non-blocking audit, and field masking.
  • Bounded concurrency with backpressure — no unbounded goroutines.

The core packages depend only on the standard library. External dependencies (the MCP SDK, database drivers, OpenTelemetry, YAML) live under x/ and depend on core, never the reverse. See CONTRIBUTING.md for the coding standard.

Source Files

View all Source files

Directories

Path Synopsis
cmd
sql-mcp-server command
Command sql-mcp-server is the entry point.
 Command sql-mcp-server is the entry point.
core
audit
Package audit defines a best-effort, non-blocking audit sink.
 Package audit defines a best-effort, non-blocking audit sink.
budget
Package budget provides role/tenant scoped execution budgets.
 Package budget provides role/tenant scoped execution budgets.
cache
Package cache defines a generic read-result cache with per-table invalidation.
 Package cache defines a generic read-result cache with per-table invalidation.
codegen
Package codegen renders a relalg.Expr (logical plan) into dialect-specific, fully parameterized SQL.
 Package codegen renders a relalg.Expr (logical plan) into dialect-specific, fully parameterized SQL.
config
Package config defines the runtime configuration model: database, entities, per-tool toggles, cost thresholds, cache, rate limits, and audit.
 Package config defines the runtime configuration model: database, entities, per-tool toggles, cost thresholds, cache, rate limits, and audit.
cost
Package cost implements the defense-in-depth cost & resource gate.
 Package cost implements the defense-in-depth cost & resource gate.
dialect
Package dialect abstracts SQL dialect differences: identifier quoting, parameter placeholders, EXPLAIN wrapping, and capability negotiation.
 Package dialect abstracts SQL dialect differences: identifier quoting, parameter placeholders, EXPLAIN wrapping, and capability negotiation.
engine
Package engine enforces bounded concurrency with backpressure, request deduplication (singleflight), and integration with adaptive limiting and the circuit breaker.
 Package engine enforces bounded concurrency with backpressure, request deduplication (singleflight), and integration with adaptive limiting and the circuit breaker.
entity
Package entity defines the entity abstraction layer: configured tables, views, and procedures exposed to MCP tools, with aliases, field projection, masking, descriptions, role permissions, row-level security, and keys.
 Package entity defines the entity abstraction layer: configured tables, views, and procedures exposed to MCP tools, with aliases, field projection, masking, descriptions, role permissions, row-level security, and keys.
hook
Package hook defines nil-safe lifecycle callbacks for observability.
 Package hook defines nil-safe lifecycle callbacks for observability.
introspect
Package introspect defines schema introspection: discovering entity metadata from a live database, and detecting drift between configured and discovered schemas.
 Package introspect defines schema introspection: discovering entity metadata from a live database, and detecting drift between configured and discovered schemas.
mask
Package mask defines field masking for sensitive data.
 Package mask defines field masking for sensitive data.
provider
Package provider defines the database adapter contract consumed by the application assembly layer.
 Package provider defines the database adapter contract consumed by the application assembly layer.
ratelimit
Package ratelimit provides adaptive concurrency control (AIMD) and a circuit breaker.
 Package ratelimit provides adaptive concurrency control (AIMD) and a circuit breaker.
rbac
Package rbac defines authorization with row-level security.
 Package rbac defines authorization with row-level security.
relalg
Package relalg defines a dialect-neutral relational algebra intermediate representation (IR).
 Package relalg defines a dialect-neutral relational algebra intermediate representation (IR).
store
Package store defines the database execution abstraction used by core tools.
 Package store defines the database execution abstraction used by core tools.
tool
Package tool defines the DML tool components and their registry.
 Package tool defines the DML tool components and their registry.
eval
runner command
Command runner executes the Agent Eval pilot: a fixed task set (eval/tasks.yaml) against a deterministic fixture, driven by any OpenAI-compatible chat-completions endpoint with tool calling.
 Command runner executes the Agent Eval pilot: a fixed task set (eval/tasks.yaml) against a deterministic fixture, driven by any OpenAI-compatible chat-completions endpoint with tool calling.
internal
benchoverhead command
Command benchoverhead measures the data-plane overhead of the governed tool path against a direct database query on the same connection pool and fixture.
 Command benchoverhead measures the data-plane overhead of the governed tool path against a direct database query on the same connection pool and fixture.
coveragecheck command
fmtcheck command
modelscopesmoke command
protocolsmoke command
Command protocolsmoke verifies the two supported MCP transports against a real database: it runs the server binary over stdio and over streamable HTTP, and asserts initialize, tools/list, one allowed read (with masking), and one machine-readable denial on each.
 Command protocolsmoke verifies the two supported MCP transports against a real database: it runs the server binary over stdio and over streamable HTTP, and asserts initialize, tools/list, one allowed read (with masking), and one machine-readable denial on each.
quickstartsmoke command
testdialect
Package testdialect provides dialect implementations for core package tests.
 Package testdialect provides dialect implementations for core package tests.
Package version exposes build metadata shared by every server surface.
 Package version exposes build metadata shared by every server surface.
x
bootstrap
Package bootstrap loads configuration and assembles the application: it resolves secret placeholders, opens the database provider, converts config entities to the core entity model, and wires the registry, authorizer, cost gate, engine, and tools.
 Package bootstrap loads configuration and assembles the application: it resolves secret placeholders, opens the database provider, converts config entities to the core entity model, and wires the registry, authorizer, cost gate, engine, and tools.
configyaml
Package configyaml decodes YAML runtime configuration.
 Package configyaml decodes YAML runtime configuration.
mcpserver
Package mcpserver bridges core DML tools to the MCP go-sdk.
 Package mcpserver bridges core DML tools to the MCP go-sdk.
otel
Package otel adapts the core hook.Hooks callbacks to OpenTelemetry spans and attributes.
 Package otel adapts the core hook.Hooks callbacks to OpenTelemetry spans and attributes.
providerregistry
Package providerregistry maps database driver names to provider factories.
 Package providerregistry maps database driver names to provider factories.
providers/all
Package all registers every database provider built into the server binary.
 Package all registers every database provider built into the server binary.
providers/mysql
Package mysql adapts a MySQL database to the core interfaces.
 Package mysql adapts a MySQL database to the core interfaces.
providers/oceanbase
Package oceanbase adapts an OceanBase database (MySQL protocol) to the core interfaces.
 Package oceanbase adapts an OceanBase database (MySQL protocol) to the core interfaces.
providers/postgres
Package postgres adapts a PostgreSQL database to the core interfaces: store.DB/Tx, dialect.Dialect, cost.Explainer, and introspect.Introspector.
 Package postgres adapts a PostgreSQL database to the core interfaces: store.DB/Tx, dialect.Dialect, cost.Explainer, and introspect.Introspector.
telemetry
Package telemetry provides the minimal metrics set for tool calls: a call counter labeled by tool and outcome, a per-tool duration histogram, and an audit-drop counter, served in Prometheus text exposition format.
 Package telemetry provides the minimal metrics set for tool calls: a call counter labeled by tool and outcome, a per-tool duration histogram, and an audit-drop counter, served in Prometheus text exposition format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.