tools

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 24, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package tools provides MCP tool handler constructors for the SQL tools. The Tier 1 (zero-config) tools are parse_sql, validate_sql, format_sql, detect_risky_sql, and summarize_sql; the Tier 2 (schema_file) tools are list_tables and describe_table; the Tier 3 (connected) tools are explain_sql, simulate_sql, and execute_sql, which require a per-call DSN since the MCP server holds no per-session connection state. explain_sql auto-dispatches DDL to EXPLAIN (DDL, SHAPE) and SELECT/DML to plain EXPLAIN, so a single tool covers the full "plan without executing" surface.

Each handler returns the same output.Envelope JSON shape that the CLI emits under --output=json, so MCP clients get structured errors, parser version, and tier metadata consistent with the CLI surface.

Tool-level errors (mcp.NewToolResultError) are reserved for infrastructure problems — missing or invalid parameters. SQL errors (syntax, type mismatch) are returned as successful tool results with the envelope's Errors array populated, because the tool itself succeeded; the SQL is simply invalid.

Index

Constants

View Source 
const (
	ParseSQLToolName       = "parse_sql"
	ValidateSQLToolName    = "validate_sql"
	FormatSQLToolName      = "format_sql"
	DetectRiskySQLToolName = "detect_risky_sql"
	SummarizeSQLToolName   = "summarize_sql"
	ExplainSQLToolName     = "explain_sql"
	SimulateSQLToolName    = "simulate_sql"
	ExecuteSQLToolName     = "execute_sql"
	ListTablesToolName     = "list_tables"
	DescribeTableToolName  = "describe_table"
)

Registered MCP tool names.

View Source 
const (
	SSLModeParamName     = "sslmode"
	SSLRootCertParamName = "sslrootcert"
	SSLCertParamName     = "sslcert"
	SSLKeyParamName      = "sslkey"
)

SSLModeParamName / SSLRootCertParamName / SSLCertParamName / SSLKeyParamName are the optional MCP tool parameter names that let a client supply libpq TLS knobs alongside the dsn. They are merged into the dsn via conn.MergeTLSParams, which fails loudly if the dsn already carries a non-empty value for the same key. Names match libpq spelling so an agent that already knows the URI form can reach for them by the same identifier.

View Source 
const (
	SSLModeParamDescription     = `` /* 151-byte string literal not displayed */
	SSLRootCertParamDescription = "" /* 134-byte string literal not displayed */
	SSLCertParamDescription     = "" /* 140-byte string literal not displayed */
	SSLKeyParamDescription      = "" /* 138-byte string literal not displayed */
)

SSL*ParamDescription strings document each TLS knob in the wire schema. Per-field rather than a single shared blurb because the agent picks them individually; a generic description would not tell it which field controls verification depth vs. CA path vs. client auth. The conflict policy is named in each one so a caller reading just one description still sees the failure mode.

View Source 
const MaxRowsParamDescription = "" /* 167-byte string literal not displayed */

MaxRowsParamDescription is the shared MCP-schema description for the max_rows parameter. Default mirrors the CLI's --max-rows.

View Source 
const MaxRowsParamName = "max_rows"

MaxRowsParamName is the optional MCP tool parameter name for the row cap applied to execute_sql results. The cap drives both the AST-level LIMIT injection on read_only SELECTs and the runtime row-scan truncation in conn.Manager.Execute.

View Source 
const ModeParamDescription = `` /* 369-byte string literal not displayed */

ModeParamDescription is the shared MCP-schema description for the mode parameter so every Tier 3 tool documents the argument identically. The accepted set is the same across tools, but the modes that any given tool actually admits depend on the tool: execute_sql and explain_sql wire safe_write and full_access today. For explain_sql, "read_only" rejects DDL — use "safe_write" or "full_access" to plan a DDL statement (the auto-dispatch routes it to EXPLAIN (DDL, SHAPE), which compiles a plan without executing the wrapped DDL). The per-tool wording stays accurate via the envelope's safety_violation Reason.

View Source 
const ModeParamName = "mode"

ModeParamName is the optional MCP tool parameter name that lets a client override the safety mode applied before any cluster contact. Mirrors the CLI's --mode flag. Tier 3 tools that accept it run the safety.Check allowlist before opening a connection.

View Source 
const SharedParserBehaviorTag = "" /* 167-byte string literal not displayed */

SharedParserBehaviorTag is the trailing fragment appended to every parser-only tool's WithDescription. It documents two behaviors that every tool in this group inherits from the shared SQL preprocessing path: keyword "did you mean?" suggestions on syntax errors (see diag.FromParseError) and tolerance of cockroach sql REPL paste artifacts (see preprocessSQL). Hoisting it into one constant keeps the per-tool descriptions short and prevents per-tool drift; the bracketed tag form makes it visually distinct from the use-case prose that precedes it.

View Source 
const StatementTimeoutParamDescription = "" /* 161-byte string literal not displayed */

StatementTimeoutParamDescription is the shared MCP-schema description for the statement_timeout_ms parameter so every Tier 3 tool documents the argument identically. Wording is mode-agnostic because execute_sql's txn is read-only only when mode=read_only; safe_write/full_access use a read-write txn but the timeout still applies.

View Source 
const StatementTimeoutParamName = "statement_timeout_ms"

StatementTimeoutParamName is the optional MCP tool parameter name that lets a client override the per-call SET LOCAL statement_timeout applied inside the cluster-side transaction wrapper. The value is in milliseconds (numeric) so the wire format matches MCP's JSON type-system without parsing duration strings.

View Source 
const TargetVersionParamDescription = "" /* 148-byte string literal not displayed */

TargetVersionParamDescription is the shared MCP-schema description for the target_version parameter so every tool documents the argument identically.

View Source 
const TargetVersionParamName = "target_version"

TargetVersionParamName is the optional MCP tool parameter name that lets a client override the server's default target CockroachDB version on a per-call basis. Tools that accept it follow the same validation rules as the CLI's --target-version flag (see output.ValidateTargetVersion).

Variables

This section is empty.

Functions

func DescribeTableHandler 

func DescribeTableHandler(parserVersion string) server.ToolHandlerFunc

DescribeTableHandler returns the handler for the describe_table tool. As in list_tables, exactly one of schemas / dsn must be supplied; the live path additionally accepts qualified table names and surfaces ambiguity as a 42P09 envelope error.

func DescribeTableTool 

func DescribeTableTool() mcp.Tool

DescribeTableTool returns the MCP tool definition for describe_table. Like ListTablesTool, it accepts either an inline `schemas` array or a `dsn`; on the live path the table argument may be qualified ("schema.table") or left bare and resolved across non-system schemas.

func DetectRiskySQLHandler 

func DetectRiskySQLHandler(parserVersion, defaultTargetVersion string) server.ToolHandlerFunc

DetectRiskySQLHandler returns the handler for the detect_risky_sql tool. It delegates to risk.Analyze and wraps the result in the standard output.Envelope used by all tools in this package. defaultTargetVersion is the server-level default; per-call target_version arguments override it.

func DetectRiskySQLTool 

func DetectRiskySQLTool() mcp.Tool

DetectRiskySQLTool returns the MCP tool definition for detect_risky_sql.

func ExecuteSQLHandler 

func ExecuteSQLHandler(parserVersion, defaultTargetVersion string) server.ToolHandlerFunc

ExecuteSQLHandler returns the handler for the execute_sql tool. The envelope's ConnectionStatus starts disconnected and flips to connected only after a successful Execute, so partial-failure envelopes report the actual reached state. Cluster-side errors (timeouts, syntax errors, perm denied) populate env.Errors via diag.FromClusterError; tool-level errors (missing parameters) come back as mcp.NewToolResultError per the discipline in tools.go.

func ExecuteSQLTool 

func ExecuteSQLTool() mcp.Tool

ExecuteSQLTool returns the MCP tool definition for execute_sql. Like explain_sql, the dsn parameter is required because MCP sessions are stateless. The mode/timeout/max_rows knobs all carry the same semantics as the CLI's --mode/--timeout/--max-rows flags.

func ExplainSQLHandler 

func ExplainSQLHandler(parserVersion, defaultTargetVersion string) server.ToolHandlerFunc

ExplainSQLHandler returns the handler for the explain_sql tool. The envelope's ConnectionStatus starts disconnected and flips to connected only after a successful EXPLAIN, so partial-failure envelopes report the actual reached state. Cluster-side errors (timeouts, syntax in the wrapped statement, perm denied) populate env.Errors; tool-level errors (missing parameters) are returned as mcp.NewToolResultError per the discipline documented in tools.go.

defaultTargetVersion is the server-level default; per-call target_version arguments override it. The resolved value is stamped onto the envelope (and may add a mismatch warning) per the contract documented on connectedEnvelope.

func ExplainSQLTool 

func ExplainSQLTool() mcp.Tool

ExplainSQLTool returns the MCP tool definition for explain_sql. The `dsn` parameter is required because MCP sessions are stateless: the server has no per-client connection to reuse, so each call carries the connection string. Credentials are never logged or echoed back.

func FormatSQLHandler 

func FormatSQLHandler(parserVersion, defaultTargetVersion string) server.ToolHandlerFunc

FormatSQLHandler returns the handler for the format_sql tool. It delegates to sqlformat.Format and wraps the result in the standard output.Envelope used by all Tier 1 tools. defaultTargetVersion is the server-level default; per-call target_version arguments override it.

func FormatSQLTool 

func FormatSQLTool() mcp.Tool

FormatSQLTool returns the MCP tool definition for format_sql.

func ListTablesHandler 

func ListTablesHandler(parserVersion string) server.ToolHandlerFunc

ListTablesHandler returns the handler for the list_tables tool. It dispatches to the schema-file path or the live-cluster path based on which of (schemas, dsn) is supplied — exactly one is required.

func ListTablesTool 

func ListTablesTool() mcp.Tool

ListTablesTool returns the MCP tool definition for list_tables. The tool now accepts either an inline `schemas` array (Tier 2, disconnected) or a `dsn` (Tier 3, live introspection); supplying both is a tool-level error so callers don't have to reason about precedence.

func ParseSQLHandler 

func ParseSQLHandler(parserVersion, defaultTargetVersion string) server.ToolHandlerFunc

ParseSQLHandler returns the handler for the parse_sql tool. It delegates to sqlparse.Classify and wraps the result in the standard output.Envelope used by all Tier 1 tools. defaultTargetVersion is the server-level default (typically the value of --target-version on the `crdb-sql mcp` invocation); per-call target_version arguments override it.

func ParseSQLTool 

func ParseSQLTool() mcp.Tool

ParseSQLTool returns the MCP tool definition for parse_sql.

func ResolveTargetVersion 

func ResolveTargetVersion(req mcp.CallToolRequest, defaultTargetVersion string) (string, *mcp.CallToolResult)

ResolveTargetVersion is the exported entry point used by the MCP per-call routing wrapper (internal/mcp/routing.go) to resolve the effective target_version for a single tool call without re-implementing the parameter-extraction contract. Handlers inside this package call the unexported resolveTargetVersion directly; keeping a thin wrapper means the wire-level contract — precedence, canonicalization, error messages — has exactly one definition.

func SimulateSQLHandler 

func SimulateSQLHandler(parserVersion, defaultTargetVersion string) server.ToolHandlerFunc

SimulateSQLHandler returns the handler for the simulate_sql tool. The envelope's ConnectionStatus starts disconnected and flips to connected only after a successful Simulate call, so partial-failure envelopes report the actual reached state. Per-statement failures (cluster reject, statement timeout, missing target table for stats) land on the corresponding SimulateStep.Error rather than aborting the whole call; method-level errors (parse failure, initial connect) populate env.Errors via diag.FromClusterError.

defaultTargetVersion is the server-level default; per-call target_version arguments override it. The resolved value is stamped onto the envelope (and may add a mismatch warning) per the contract documented on connectedEnvelope.

func SimulateSQLTool 

func SimulateSQLTool() mcp.Tool

SimulateSQLTool returns the MCP tool definition for simulate_sql. The dispatcher behind this tool routes each parsed statement to a non-executing EXPLAIN flavor (EXPLAIN ANALYZE for SELECT, plain EXPLAIN for DML writes, EXPLAIN (DDL, SHAPE) for DDL) and returns per-statement plan + (for DDL) row-count annotations. The `dsn` parameter is required because MCP sessions are stateless: the server has no per-client connection to reuse, so each call carries the connection string. Credentials are never logged or echoed back.

func SummarizeSQLHandler 

func SummarizeSQLHandler(parserVersion, defaultTargetVersion string) server.ToolHandlerFunc

SummarizeSQLHandler returns the handler for the summarize_sql tool. It parses the SQL once, runs version.Inspect on the AST so a per-call target_version emits feature warnings into the envelope, then delegates to summarize.Parsed and wraps the result in the standard output.Envelope used by all tools in this package. defaultTargetVersion is the server-level default; per-call target_version arguments override it.

func SummarizeSQLTool 

func SummarizeSQLTool() mcp.Tool

SummarizeSQLTool returns the MCP tool definition for summarize_sql.

func ValidateSQLHandler 

func ValidateSQLHandler(parserVersion, defaultTargetVersion string) server.ToolHandlerFunc

ValidateSQLHandler returns the handler for the validate_sql tool. On the success path the envelope's tier reflects whether schemas were supplied — schema_file when present, zero_config otherwise — and the data payload always carries a validateresult.Result so agents can branch on which phases ran. defaultTargetVersion is the server-level default; per-call target_version arguments override it. The resolved target is stamped onto the envelope on both tiers so that supplying schemas does not silently discard a target_version the client took the trouble to validate.

func ValidateSQLTool 

func ValidateSQLTool() mcp.Tool

ValidateSQLTool returns the MCP tool definition for validate_sql. The optional schemas parameter mirrors the CLI's --schema flag: when supplied, table references are resolved against the inline catalog (Tier 2); when omitted, name resolution is skipped and a capability_required warning is appended to the envelope so agents can detect the missing capability rather than silently trust a partial result. The optional target_version parameter follows the shared per-call convention documented on TargetVersionParamName.

Types

This section is empty.

Source Files

View all Source files

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.