sqlmcp

package module
v0.1.13 Latest Latest
Warning

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

 Go to latest Published: Oct 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.26.9+ 和一个已验证数据库版本：

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
evalcoverage command
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.
bus
Package bus is the process's execution bus: every piece of work that reaches a database runs on one of its lanes, and every background task is started through it, so what the process runs is bounded, visible and stopped together.
 Package bus is the process's execution bus: every piece of work that reaches a database runs on one of its lanes, and every background task is started through it, so what the process runs is bounded, visible and stopped together.
cache
Package cache defines a generic read-result cache with per-relation invalidation.
 Package cache defines a generic read-result cache with per-relation 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.
cost/costtest
Package costtest holds hand-written fakes of the cost interfaces for tests: an Explainer and an EXPLAIN ANALYZE sampler answering as configured.
 Package costtest holds hand-written fakes of the cost interfaces for tests: an Explainer and an EXPLAIN ANALYZE sampler answering as configured.
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 matching configured entities to it.
 Package introspect defines schema introspection: discovering entity metadata from a live database and matching configured entities to it.
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).
relalg/interp
Package interp is the reference interpreter for the committed read-path subset of the relalg IR.
 Package interp is the reference interpreter for the committed read-path subset of the relalg IR.
revision
Package revision defines the persisted configuration revision model and the Store boundary.
 Package revision defines the persisted configuration revision model and the Store boundary.
revision/revisiontest
Package revisiontest provides the conformance suite every revision.Store implementation must pass, so SQL stores keep the MemoryStore semantics.
 Package revisiontest provides the conformance suite every revision.Store implementation must pass, so SQL stores keep the MemoryStore semantics.
store
Package store defines the database execution abstraction used by core tools.
 Package store defines the database execution abstraction used by core tools.
store/storetest
Package storetest holds hand-written fakes of the store interfaces for tests: a DB, a Tx and Rows whose answers the test configures and whose calls it reads back, without a mocking library.
 Package storetest holds hand-written fakes of the store interfaces for tests: a DB, a Tx and Rows whose answers the test configures and whose calls it reads back, without a mocking library.
tool
Package tool defines the DML tool components and their registry.
 Package tool defines the DML tool components and their registry.
workspace
Package workspace is the working-copy half of configuration versioning (the history half is core/revision): each administrator has one workspace, edited by them (in any console) and by their agents, and committed as a revision.
 Package workspace is the working-copy half of configuration versioning (the history half is core/revision): each administrator has one workspace, edited by them (in any console) and by their agents, and committed as a revision.
workspace/workspacetest
Package workspacetest is the conformance suite every workspace.Store implementation runs: in memory and on each configuration store database.
 Package workspacetest is the conformance suite every workspace.Store implementation runs: in memory and on each configuration store database.
eval
runner command
Diagnostic track (-track diagnostic): v5 task set with dimensions, prompt levels, expected behaviors, and counterfactual oracles.
 Diagnostic track (-track diagnostic): v5 task set with dimensions, prompt levels, expected behaviors, and counterfactual oracles.
fixtures
v4/generator
Package workload generates the v4 realistic business workload fixture (docs/design/business-workload-model.md): four business modules rendered from one set of table specs into per-dialect DDL/seed SQL, entity configuration, and expected task results.
 Package workload generates the v4 realistic business workload fixture (docs/design/business-workload-model.md): four business modules rendered from one set of table specs into per-dialect DDL/seed SQL, entity configuration, and expected task results.
v4/generator/cmd/workloadgen command
Command workloadgen renders the checked-in fixtures/v4 artifacts from the deterministic generator: per-module DDL and seed SQL for every dialect, expected task results (CSV), per-module entity policies, and the runnable combined profile.
 Command workloadgen renders the checked-in fixtures/v4 artifacts from the deterministic generator: per-module DDL and seed SQL for every dialect, expected task results (CSV), per-module entity policies, and the runnable combined profile.
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.
buscheck
Package buscheck keeps the process's goroutines on the execution bus (core/bus): its test fails on a go statement, a sync.WaitGroup or errgroup Go call, or time.AfterFunc in the production code of core/, x/ and cmd/, outside the bus itself and the engine's singleflight, which the Serve lane bounds.
 Package buscheck keeps the process's goroutines on the execution bus (core/bus): its test fails on a go statement, a sync.WaitGroup or errgroup Go call, or time.AfterFunc in the production code of core/, x/ and cmd/, outside the bus itself and the engine's singleflight, which the Serve lane bounds.
conformance
Package conformance is the cross-provider differential conformance suite for the committed read-path IR subset.
 Package conformance is the cross-provider differential conformance suite for the committed read-path IR subset.
coveragecheck command
docscheck command
Command docscheck enforces documentation consistency (roadmap v0.1.9 accompanying item): every relative markdown link resolves to an existing file, and the pinned version references (README GA line, roadmap baseline, release notes, CHANGELOG) agree with each other.
 Command docscheck enforces documentation consistency (roadmap v0.1.9 accompanying item): every relative markdown link resolves to an existing file, and the pinned version references (README GA line, roadmap baseline, release notes, CHANGELOG) agree with each other.
evalcoverage
fmtcheck command
kit
Package kit holds the small value helpers the x/ packages share: pointer and slice conveniences that adapters (GraphQL, MCP, the store) need when mapping between optional API fields and Go values.
 Package kit holds the small value helpers the x/ packages share: pointer and slice conveniences that adapters (GraphQL, MCP, the store) need when mapping between optional API fields and Go values.
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
schemagen command
Command schemagen generates core/config/schema.json, the field reference in docs/configuration.md and the Specs (core/config/spec_gen.go) from the configuration structs (their `schema` tags and ApplyDefaults) and the help text in core/config/fields.yaml.
 Command schemagen generates core/config/schema.json, the field reference in docs/configuration.md and the Specs (core/config/spec_gen.go) from the configuration structs (their `schema` tags and ApplyDefaults) and the help text in core/config/fields.yaml.
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
admin
Package admin serves the admin API under /admin: sign-in with local accounts, cookie sessions with CSRF tokens, the GraphQL endpoint, and the configuration MCP endpoint at /admin/mcp for administrators' tokens.
 Package admin serves the admin API under /admin: sign-in with local accounts, cookie sessions with CSRF tokens, the GraphQL endpoint, and the configuration MCP endpoint at /admin/mcp for administrators' tokens.
admin/accounts
Package accounts holds the business rules for administrator accounts.
 Package accounts holds the business rules for administrator accounts.
admin/auth
Package auth holds what the admin HTTP layer and the GraphQL resolvers share: argon2id password hashing, admin permissions and the signed-in principal on a request context.
 Package auth holds what the admin HTTP layer and the GraphQL resolvers share: argon2id password hashing, admin permissions and the signed-in principal on a request context.
admin/configapp
Package configapp is the configuration service of the admin plane: the scanned catalog, schema scans and scan batches, plans and their previews, plan templates, pending work and administrators' MCP tokens.
 Package configapp is the configuration service of the admin plane: the scanned catalog, schema scans and scan batches, plans and their previews, plan templates, pending work and administrators' MCP tokens.
admin/configmcp
Package configmcp serves the configuration MCP endpoint at /admin/mcp: an agent, signed in with one of an administrator's tokens, acts for the administrator: it searches the scanned catalog, scans schemas, previews plans against the administrator's workspace and writes them into it (the one copy the administrator edits in the console, so they see the changes as if made there), and diffs and simulates configurations.
 Package configmcp serves the configuration MCP endpoint at /admin/mcp: an agent, signed in with one of an administrator's tokens, acts for the administrator: it searches the scanned catalog, scans schemas, previews plans against the administrator's workspace and writes them into it (the one copy the administrator edits in the console, so they see the changes as if made there), and diffs and simulates configurations.
admin/graph
Package graph implements the admin GraphQL API.
 Package graph implements the admin GraphQL API.
admin/scanjobs
Package scanjobs runs long administrative work, such as schema scans, on the Scan lane of the execution bus, off the request path: a request starts a job and polls it, so a slow database ties up neither the request nor the service.
 Package scanjobs runs long administrative work, such as schema scans, on the Scan lane of the execution bus, off the request path: a request starts a job and polls it, so a slow database ties up neither the request nor the service.
admin/ui
Package ui embeds the built admin console (web/admin).
 Package ui embeds the built admin console (web/admin).
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.
catalog
Package catalog keeps what schema scans found, per database a datasource reads, so the console can search and plan over every scanned schema after a restart and on every replica.
 Package catalog keeps what schema scans found, per database a datasource reads, so the console can search and plan over every scanned schema after a restart and on every replica.
catalog/catalogtest
Package catalogtest provides the conformance suite every catalog.Store implementation must pass, so SQL stores keep the MemoryStore semantics.
 Package catalogtest provides the conformance suite every catalog.Store implementation must pass, so SQL stores keep the MemoryStore semantics.
configedit
Package configedit applies edits to a stored configuration: it replaces whole sections of a base configuration with typed values and runs the result through the same chain as `store import` (defaults, validation, the store secret rule and the deterministic encoding).
 Package configedit applies edits to a stored configuration: it replaces whole sections of a base configuration with typed values and runs the result through the same chain as `store import` (defaults, validation, the store secret rule and the deterministic encoding).
configplan
Package configplan turns a plan, a scope of scanned tables and rules to apply to them, into a proposal: the configuration changes and a report of what they cover, what changes, the exceptions to look at, and when the changes take effect.
 Package configplan turns a plan, a scope of scanned tables and rules to apply to them, into a proposal: the configuration changes and a report of what they cover, what changes, the exceptions to look at, and when the changes take effect.
configrefs
Package configrefs holds the rules for references among a configuration's entities as entities change: what an existing reference names afterwards and how it is written.
 Package configrefs holds the rules for references among a configuration's entities as entities change: what an existing reference names afterwards and how it is written.
configstore
Package configstore persists configuration revisions in SQLite or in a PostgreSQL, MySQL or OceanBase database.
 Package configstore persists configuration revisions in SQLite or in a PostgreSQL, MySQL or OceanBase database.
configyaml
Package configyaml decodes YAML runtime configuration.
 Package configyaml decodes YAML runtime configuration.
leasing
Package leasing runs scan batches across processes.
 Package leasing runs scan batches across processes.
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.
providers/sqladapter
Package sqladapter adapts a database/sql pool to the core store interfaces.
 Package sqladapter adapts a database/sql pool to the core store interfaces.
revisionops
Package revisionops holds the configuration store operations shared by the `store`/`migrate` CLI and the admin API: normalizing payloads, creating drafts, publishing, rolling back and diffing.
 Package revisionops holds the configuration store operations shared by the `store`/`migrate` CLI and the admin API: normalizing payloads, creating drafts, publishing, rolling back and diffing.
revisionops/revisionopstest
Package revisionopstest stresses the revision operations on a store: many administrators editing and publishing at once, and the edge cases of the fast-forward rule.
 Package revisionopstest stresses the revision operations on a store: many administrators editing and publishing at once, and the edge cases of the fast-forward rule.
telemetry
Package telemetry provides the metrics of tool calls: a call counter by tool and outcome, a duration histogram by tool, and the audit events dropped, as OpenTelemetry instruments on a meter provider of their own, served in the Prometheus exposition format at /metrics.
 Package telemetry provides the metrics of tool calls: a call counter by tool and outcome, a duration histogram by tool, and the audit events dropped, as OpenTelemetry instruments on a meter provider of their own, served in the Prometheus exposition format at /metrics.
workspaceops
Package workspaceops is the working-copy half of configuration versioning as a service: reading a workspace, writing items of it (several writers racing merge three ways), updating it onto a newer published revision, taking a draft in, resolving conflicts, saving a checkpoint (a draft to share) and committing (publishing it as a new revision), each write logged.
 Package workspaceops is the working-copy half of configuration versioning as a service: reading a workspace, writing items of it (several writers racing merge three ways), updating it onto a newer published revision, taking a draft in, resolving conflicts, saving a checkpoint (a draft to share) and committing (publishing it as a new revision), each write logged.

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.