mcpapi

package
v0.370.0 Latest Latest
Warning

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

 Go to latest Published: Jun 23, 2026 License: Apache-2.0 Imports: 20 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 the MCP audit_sql tool on top of the shared DeltaScope audit path
connection.go Resolves connection_ref inputs, delegates direct connection validation/password lookup to internal/interfaces/metadata, and assembles MCP connection state
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 for MCP rule-discovery tools
rule_tools_test.go Verifies describe_rule, list_rules, and get_capabilities behavior
server.go Builds the MCP server and registers the official DeltaScope tools
server_test.go Verifies MCP bootstrap metadata and core tool registration
tool_errors.go Shapes stable structured MCP tool errors and error-code mapping

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.
  • 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, audit modes, dialect support, top-level and connection inputs, audit result fields, context fields, 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 for partial-support and parser-error outcomes; both are omitted when empty and are not listed in the result_fields summary.
  • connect_timeout is an accepted direct and named connection input (duration string like 5s); empty/omitted/0s falls back to runtime config default, invalid/negative values return connection_invalid. It is not listed in the connection_inputs summary.
  • 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, 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 that preserve DeltaScope's public audit result body 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, and password lookup sources output: normalized metadata-aware connection settings for MCP audit requests 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: structured payload builders for describe_rule, list_rules, and get_capabilities 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 arising during MCP tool execution output: stable MCP tool error payloads with machine-readable codes and human-readable messages 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"`
}

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
	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.