mcpapi

package
v0.511.0 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

README

MCP Interface Module

Thin MCP adapter for exposing DeltaScope audit and rule-discovery capabilities to agent clients.

Files

File Responsibility
audit_tool.go Implements audit_sql on the shared DeltaScope path, including catalog-aware metadata audits, and passes full partial public results and context into bounded diagnostic tool errors
audit_tool_test.go Verifies audit_sql compact text, structured result without CLI-only fail_on_triggered, empty-SQL bad_request, and offline context.note / context.unproven
audit_impact_postgresql_tag_test.go Verifies PostgreSQL offline primary-key equality impact in MCP structured output
audit_dml_table_existence_test.go Verifies metadata-aware MySQL/TiDB INSERT/UPDATE/DELETE missing-target findings and stable MCP structured-result shape
audit_tool_postgresql_tag_test.go Verifies compact review-verdict text on the PostgreSQL-capable build
server_metadata_postgresql_tag_test.go Verifies PostgreSQL metadata-aware MCP result behavior and separate database/schema propagation
connection.go Resolves connection_ref inputs, delegates direct connection validation/password lookup to internal/interfaces/metadata, and assembles MCP connection state while preserving separate database/catalog and schema values
connection_test.go Verifies MCP connection normalization and safety rules
output_schema.go Publishes explicit success output schemas for official MCP tools
rule_tools.go Builds structured payloads and compact list_rules text for MCP rule-discovery tools, including query_access unavailability on get_capabilities, database-aware connection inputs, and note / unproven on get_capabilities context_fields
rule_tools_test.go Verifies compact list_rules rows, the text-only surface, describe_rule, default-disabled dml.impact.* catalog rows, and get_capabilities including Query Access unavailability
server.go Builds the MCP server and registers the official DeltaScope tools
server_test.go Verifies MCP bootstrap, registration, metadata-aware context, and parser-error partial-result preservation
server_unsupported_diagnostics_evidence_test.go Verifies MCP parser errors preserve review-floored partial results, audited siblings/findings, context, structured error signaling, locations, and no-leak boundaries
server_unsupported_verdict_floor_postgresql_tag_test.go Verifies MCP PostgreSQL SELECT 1 keeps tool-error signaling and serializes the review-floored unsupported result
tool_errors.go Shapes stable structured MCP tool errors; connection-open failures go through connresolve.Classify then MCP codes

Exports

  • AuditSQLParams
  • Config
  • NewServer(config)
  • ResolveAuditConnection(params, options)

Notes

  • The MCP layer stays thin and reuses shared DeltaScope audit, rule-catalog, metadata-preparation, and direct-connection helper logic.
  • audit_sql content[0].text is a compact finding summary (verdict, counts, offline existence caveat when present, [level] rule_id: message, suggestion). structuredContent stays the full public result plus MCP context. Offline context includes note / unproven; metadata-aware context omits them. The text is not a second JSON copy and does not dump skipped rules or echo the audited SQL.
  • list_rules returns compact catalog rows (rule_id, level, dialect, kind, summary) plus a text table. describe_rule remains the full-body tool. content[0].text is the text-only surface and is not a second JSON copy of structuredContent.
  • query_access_surface_contract_test.go is the MCP proof that Query Access remains absent from the tool list; no Query Access MCP tool is introduced. get_capabilities declares the gap as query_access: { available: false, surfaces: ["cli", "http"] }.
  • The current scope supports stdio MCP bootstrap, offline audit for MySQL, TiDB, and PostgreSQL, plus metadata-aware audit for MySQL/TiDB-compatible instances and PostgreSQL on the PG-capable builds.
  • Connection-backed PostgreSQL MCP audit requests follow the same shared metadata-preparation path as the other transports and should preserve explicit metadata-aware context rather than downgrading silently.
  • get_capabilities is MCP-client-facing and summarizes transport, official tool names, Query Access unavailability on MCP (query_access.available is false; query_access.surfaces is the stable list cli, then http), audit modes, dialect support, top-level and connection inputs (including connection.database and connection.connect_timeout), audit result fields, context fields (mode, dialect, dialect_source, schema, schema_source, metadata_source, note, unproven), metadata features, and the stable structured error codes the server advertises (bad_request, connection_invalid, connection_failed, config_invalid).
  • Audit results also carry additive unsupported ([]spec.UnsupportedDetail) and diagnostics ([]spec.Diagnostic) arrays. Parser-error tool results retain valid audited statements/findings, the shared partial-result review floor, and normal MCP context inside structuredContent, add a bounded code/message, and remain errors so clients cannot treat a partial audit as success; empty arrays are omitted and are not listed in result_fields.
  • connect_timeout is an accepted direct and named connection input (duration string like 5s) and is advertised as connection.connect_timeout; empty/omitted/0s falls back to runtime config default, invalid/negative values return connection_invalid.
  • In addition to the structured errors get_capabilities advertises, recovered tool panics return internal_error; this code is not part of the advertised structured_errors list.
  • tool_errors.go maps connection connect_timeout validation errors to connection_invalid.

Dependencies

  • Upstream: cmd/deltascope-mcp
  • Downstream: shared audit/rule-catalog layers under pkg/deltascope, metadata helpers under internal/interfaces/metadata, internal/application/connresolve, and other internal/... adapter layers

Update Rule

  • If members/interfaces/dependencies change, update this file in same change.

Documentation

Overview

Package mcpapi exposes the MCP adapter for DeltaScope. input: audit_sql MCP requests, shared DeltaScope public audit API, and resolved run-context metadata output: structured MCP audit_sql responses, partial parser-error results, and compact finding summaries with offline existence caveats and resolved catalog-aware metadata audits pos: MCP audit tool adapter between tool invocations and the shared audit engine note: if this file changes, update this header and module README.md.

Package mcpapi exposes the MCP adapter for DeltaScope. input: audit tool connection parameters, local connection config files, password lookup sources, and optional database/catalog selection output: normalized metadata-aware connection settings for MCP audit requests with database and schema preserved separately pos: MCP connection resolution layer between tool inputs and metadata provider wiring note: if this file changes, update this header and module README.md.

Package mcpapi exposes the MCP adapter for DeltaScope. input: MCP success payload types that need explicit output-schema publication output: resolved JSON Schema objects for official DeltaScope MCP tool outputs pos: schema publication helpers for MCP tool registration metadata note: if this file changes, update this header and module README.md.

Package mcpapi exposes the MCP adapter for DeltaScope. input: shipped rule catalog entries and DeltaScope capability metadata for MCP rule tools output: full describe_rule bodies, compact list_rules rows plus text catalog, and get_capabilities summaries including query_access unavailability, the public connection.connect_timeout capability, and offline existence context_fields pos: MCP rule-discovery helpers above the domain rule catalog note: if this file changes, update this header and module README.md.

Package mcpapi exposes the MCP adapter for DeltaScope. input: MCP server construction inputs, DeltaScope version metadata, and tool registration definitions output: ready-to-run MCP server instances that expose the official DeltaScope tool surface pos: interface adapter between the Go MCP SDK and DeltaScope audit/rule capabilities note: if this file changes, update this header and module README.md.

Package mcpapi exposes the MCP adapter for DeltaScope. input: adapter and audit errors plus partial audit results arising during MCP tool execution; connection-open errors classified by connresolve output: stable MCP tool error payloads with machine-readable codes, messages, and partial results when available pos: shared error-shaping helpers for MCP tool handlers note: if this file changes, update this header and module README.md.

Index

Constants

View Source 
const DefaultConnectionsPath = "~/.config/deltascope/connections.yaml"

DefaultConnectionsPath is the default local path used to resolve MCP connection_ref names.

Variables

This section is empty.

Functions

func NewServer 

func NewServer(config Config) *sdkmcp.Server

NewServer returns a configured MCP server with the core DeltaScope tools registered.

Types

type AuditContext 

type AuditContext struct {
	Mode           string         `json:"mode,omitempty"`
	Dialect        string         `json:"dialect,omitempty"`
	DialectSource  string         `json:"dialect_source,omitempty"`
	Schema         string         `json:"schema,omitempty"`
	SchemaSource   string         `json:"schema_source,omitempty"`
	MetadataSource MetadataSource `json:"metadata_source,omitempty"`
	Note           string         `json:"note,omitempty"`
	Unproven       []string       `json:"unproven,omitempty"`
}

AuditContext describes how one MCP audit_sql result was produced.

type AuditSQLParams 

type AuditSQLParams struct {
	SQL           string           `json:"sql"`
	Dialect       string           `json:"dialect,omitempty"`
	ConfigPath    string           `json:"config_path,omitempty"`
	ConnectionRef string           `json:"connection_ref,omitempty"`
	Connection    *ConnectionInput `json:"connection,omitempty"`
}

AuditSQLParams describes the MCP-facing audit_sql request contract.

type AuditSQLResult 

type AuditSQLResult struct {
	publicapi.Result
	Context AuditContext `json:"context"`
}

AuditSQLResult preserves the public DeltaScope result body and adds MCP context.

type Config 

type Config struct {
	Version                string
	ConnectionsPath        string
	Logger                 *slog.Logger // Optional structured logger. Defaults to stderr JSON if nil.
	MetadataConnectTimeout time.Duration
}

Config configures the DeltaScope MCP server bootstrap.

type ConnectionInput 

type ConnectionInput = ifaceconn.ConnectionInput

type MetadataSource 

type MetadataSource string

MetadataSource identifies how one metadata-aware audit connection was selected. 

const (
	// MetadataSourceNone indicates the request stayed offline.
	MetadataSourceNone MetadataSource = "none"
	// MetadataSourceConnectionRef indicates the request used a named connection reference.
	MetadataSourceConnectionRef MetadataSource = "connection_ref"
	// MetadataSourceDirect indicates the request used direct inline connection settings.
	MetadataSourceDirect MetadataSource = "direct"
)

type ResolveConnectionOptions 

type ResolveConnectionOptions struct {
	ConnectionsPath string
	LookupEnv       func(string) (string, bool)
	ReadFile        func(string) ([]byte, error)
}

ResolveConnectionOptions configures connection resolution dependencies.

type ResolvedConnection 

type ResolvedConnection struct {
	Enabled        bool
	Source         MetadataSource
	RefName        string
	RefPath        string
	Host           string
	Port           int
	Socket         string
	User           string
	Database       string
	Schema         string
	Dialect        string
	Password       string
	ConnectTimeout string
}

ResolvedConnection is the normalized metadata-aware connection used by MCP audit flows.

func ResolveAuditConnection 

func ResolveAuditConnection(params AuditSQLParams, options ResolveConnectionOptions) (ResolvedConnection, error)

ResolveAuditConnection validates and normalizes the MCP audit_sql connection inputs.

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.