mcp

Documentation

Overview

Package mcp provides a Model Context Protocol (MCP) server for GoSQLX. It exposes SQL parsing, validation, formatting, linting, and security scanning as MCP tools accessible over streamable HTTP transport.

Quick start

cfg, err := mcp.LoadConfig()
if err != nil {
    log.Fatal(err)
}
srv := mcp.New(cfg)
srv.Start(context.Background())

Environment variables

GOSQLX_MCP_HOST        bind host (default: 127.0.0.1)
GOSQLX_MCP_PORT        bind port (default: 8080)
GOSQLX_MCP_AUTH_TOKEN  bearer token; empty disables auth

Index

• func BearerAuthMiddleware(cfg *Config, next http.Handler) http.Handler
• func NewRateLimiter() *rateLimiter
• func RateLimitMiddleware(next http.Handler) http.Handler
• type Config
  • func DefaultConfig() *Config
  • func LoadConfig() (*Config, error)
  • func (c *Config) Addr() string
  • func (c *Config) AuthEnabled() bool
• type Server
  • func New(cfg *Config) *Server
  • func (s *Server) Cfg() *Config
  • func (s *Server) Handler() http.Handler
  • func (s *Server) Start(ctx context.Context) error

Functions

func BearerAuthMiddleware

func BearerAuthMiddleware(cfg *Config, next http.Handler) http.Handler

BearerAuthMiddleware returns an http.Handler that enforces bearer token authentication when cfg.AuthEnabled() is true. When auth is disabled it passes all requests through unchanged. On failure it responds 401 with a WWW-Authenticate header.

func NewRateLimiter

func NewRateLimiter() *rateLimiter

NewRateLimiter creates a new rateLimiter, initializes all shards, and starts the background cleanup goroutine.

func RateLimitMiddleware

func RateLimitMiddleware(next http.Handler) http.Handler

RateLimitMiddleware creates a rate limiter and returns an http.Handler that enforces the three-layer rate limiting strategy. Requests that exceed limits receive an HTTP 200 response with a JSON-RPC error (MCP clients expect JSON-RPC responses, not HTTP 429).

Types

type Config

type Config struct {
	// Host is the interface to bind to.
	// Source: GOSQLX_MCP_HOST (default: "127.0.0.1")
	Host string

	// Port is the TCP port to listen on (1–65535).
	// Source: GOSQLX_MCP_PORT (default: 8080)
	Port int

	// AuthToken is the optional bearer token for request authentication.
	// When non-empty every request must carry "Authorization: Bearer <token>".
	// Source: GOSQLX_MCP_AUTH_TOKEN (default: "" - auth disabled)
	AuthToken string
}

Config holds all MCP server configuration loaded from environment variables. Use LoadConfig or DefaultConfig to obtain a valid Config; the zero value is not valid.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with all defaults applied (auth disabled).

func LoadConfig

func LoadConfig() (*Config, error)

LoadConfig reads configuration from environment variables, applying defaults for any variables that are unset or empty.

func (*Config) Addr

func (c *Config) Addr() string

Addr returns the "host:port" string suitable for net/http ListenAndServe.

func (*Config) AuthEnabled

func (c *Config) AuthEnabled() bool

AuthEnabled reports whether bearer token authentication is configured.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server wraps the MCP server with all GoSQLX tools registered.

func New

func New(cfg *Config) *Server

New creates a Server with all 7 GoSQLX tools registered.

func (*Server) Cfg

func (s *Server) Cfg() *Config

Cfg returns the server configuration.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the HTTP handler chain (MCP server + auth middleware) without starting an HTTP server. Use this when you need to wrap the handler with additional middleware (e.g., rate limiting).

func (*Server) Start

func (s *Server) Start(ctx context.Context) error

Start binds to cfg.Addr() and serves using streamable HTTP transport. It blocks until ctx is cancelled or a fatal error occurs.