mcp

Documentation

Overview

Package mcp builds the crdb-sql Model Context Protocol server.

The server registers a health-check tool (ping), five Tier 1 SQL tools (parse_sql, validate_sql, format_sql, detect_risky_sql, summarize_sql), two Tier 2 catalog tools (list_tables, describe_table) that operate on inline CREATE TABLE schemas, and three Tier 3 connected tools (explain_sql, simulate_sql, execute_sql) that run against a live cluster. validate_sql is dual-tier: it runs Tier 1 by default and lifts to Tier 2 (name resolution) when the caller supplies inline schemas. Keeping construction pure (no transport, no I/O) lets the cmd layer pick a transport — currently just stdio — and lets tests exercise individual tool handlers directly.

Versions are passed in by the caller rather than read from debug.ReadBuildInfo here, so this package stays free of build-info plumbing. The cmd/version.go helpers own that resolution and feed the resolved strings to NewServer.

Index

• Constants
• func NewServer(crdbSQLVersion, parserVersion, defaultTargetVersion string, opts ...Option) *server.MCPServer
• type Option
  • func WithBuiltQuarter(q versionroute.Quarter) Option
  • func WithRouter(r proxy.Router) Option

Constants

const PingToolName = "ping"

PingToolName is the registered MCP tool name for the health-check tool. All other tool name constants live in the tools subpackage.

Functions

func NewServer

func NewServer(
	crdbSQLVersion, parserVersion, defaultTargetVersion string, opts ...Option,
) *server.MCPServer

NewServer constructs an MCP server for crdb-sql. The three string arguments name distinct concepts that flow through every tool response, and callers must resolve them before invoking NewServer:

• crdbSQLVersion is the crdb-sql binary version (typically cmd.Version). Reported in the MCP server handshake so clients can identify which build they are talking to.
• parserVersion is the resolved cockroachdb-parser module version (typically the result of cmd.parserVersion). Stamped into every tool's envelope so clients always know which SQL dialect this binary actually understands.
• defaultTargetVersion is the user-declared CockroachDB target version (typically state.targetVersion from the --target-version flag), or "" when the user did not supply one. Used as a default for every tool call; per-call target_version arguments override it.

The variadic Option values configure cross-cutting behavior — most notably the per-call target_version Router (see WithRouter). The returned server has no transport bound; callers wire it to stdio (or, in the future, sse/http) themselves.

Per-call routing wiring: the eight parser-dependent tool handlers (parse_sql, validate_sql, format_sql, detect_risky_sql, summarize_sql, explain_sql, simulate_sql, execute_sql) are wrapped with withRouting so a target_version whose quarter differs from the running binary forwards to a sibling backend. The three tools that don't take target_version (ping, list_tables, describe_table) are registered unwrapped.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option configures NewServer. The pattern matches CockroachDB's functional-options convention: each Option mutates a serverOptions holder so the public NewServer signature stays stable going forward as new knobs arrive. Today the configurable knobs are the per-call target_version Router (issue #129) and the built-quarter override used by tests; the same shape extends naturally to future server-wide options.

func WithBuiltQuarter

func WithBuiltQuarter(q versionroute.Quarter) Option

WithBuiltQuarter overrides the built quarter used for routing decisions. Production callers must not use this — versionroute.Built() is the source of truth for which sibling backend "this binary" is. Tests use it to construct a server with a known built quarter without having to fiddle with link-time stamps or fake the executable path.

func WithRouter

func WithRouter(r proxy.Router) Option

WithRouter installs the per-call target_version Router used by every parser-dependent tool handler. When omitted, NewServer wires proxy.NoopRouter, which returns a clear "routing not enabled" tool error rather than silently answering with the wrong parser. The production binary (cmd/mcp.go) installs proxy.NewSpawnRouter().