feat: add MCP server exposing GoSQLX SQL tools over streamable HTTP

Adds a Model Context Protocol server that wraps GoSQLX's SQL processing
capabilities as MCP tools accessible to AI assistants and MCP clients.

## New packages
- `pkg/mcp/` — importable library (Config, Server, 7 tool handlers)
- `cmd/gosqlx-mcp/` — standalone binary with graceful shutdown

## Tools
- validate_sql — syntax validation with optional dialect (7 dialects)
- format_sql — formatting with indent/case/semicolon options
- parse_sql — AST summary (statement count + types)
- extract_metadata — extract tables, columns, functions
- security_scan — SQL injection pattern detection (8 pattern types)
- lint_sql — style rules L001–L010
- analyze_sql — concurrent fan-out across all 6 tools

## Transport & auth
- Streamable HTTP transport (mark3labs/mcp-go v0.45.0)
- Optional bearer token auth via GOSQLX_MCP_AUTH_TOKEN env var

## Tasks added
- task mcp — run server
- task mcp:build — build binary
- task mcp:test — race-detected tests
- task mcp:install — install globally

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

.gitignore

@@ -10,6 +10,7 @@
 
 # Built binary executables (only in root directory)
 /gosqlx
+/gosqlx-mcp
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out

Taskfile.yml

@@ -298,6 +298,33 @@ tasks:
     cmds:
       - go run ./cmd/gosqlx lsp --log /tmp/gosqlx-lsp.log
 
+  # =============================================================================
+  # MCP SERVER
+  # =============================================================================
+  mcp:
+    desc: Run the MCP server (env vars GOSQLX_MCP_HOST, GOSQLX_MCP_PORT, GOSQLX_MCP_AUTH_TOKEN)
+    cmds:
+      - go run ./cmd/gosqlx-mcp
+
+  mcp:build:
+    desc: Build the MCP server binary to build/gosqlx-mcp
+    cmds:
+      - echo "Building MCP server binary..."
+      - go build -v -o {{.BUILD_DIR}}/gosqlx-mcp ./cmd/gosqlx-mcp
+    generates:
+      - '{{.BUILD_DIR}}/gosqlx-mcp'
+
+  mcp:test:
+    desc: Run MCP package tests with race detection
+    cmds:
+      - echo "Testing MCP package..."
+      - go test -race -timeout 60s ./pkg/mcp/... ./cmd/gosqlx-mcp/...
+
+  mcp:install:
+    desc: Install gosqlx-mcp binary globally
+    cmds:
+      - go install ./cmd/gosqlx-mcp
+
   # =============================================================================
   # EXAMPLES
   # =============================================================================

cmd/gosqlx-mcp/main.go

@@ -0,0 +1,58 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package main is the entry point for the gosqlx-mcp MCP server.
+//
+// The server exposes GoSQLX SQL processing capabilities as MCP tools
+// accessible over streamable HTTP transport.
+//
+// # 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
+//
+// # Usage
+//
+//	gosqlx-mcp
+//	GOSQLX_MCP_PORT=9090 gosqlx-mcp
+//	GOSQLX_MCP_AUTH_TOKEN=secret gosqlx-mcp
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+
+	gosqlxmcp "github.com/ajitpratap0/GoSQLX/pkg/mcp"
+)
+
+func main() {
+	cfg, err := gosqlxmcp.LoadConfig()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gosqlx-mcp: configuration error: %v\n", err)
+		os.Exit(1)
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	srv := gosqlxmcp.New(cfg)
+	if err := srv.Start(ctx); err != nil {
+		fmt.Fprintf(os.Stderr, "gosqlx-mcp: %v\n", err)
+		os.Exit(1)
+	}
+}

docs/plans/2026-03-08-mcp-server-design.md

@@ -0,0 +1,71 @@
+# MCP Server Design: GoSQLX
+
+**Date:** 2026-03-08
+**Status:** Implemented
+
+## Overview
+
+GoSQLX MCP server exposes SQL processing capabilities as MCP tools over streamable HTTP transport, enabling AI assistants and MCP-compatible clients to parse, validate, format, lint, and security-scan SQL.
+
+## Design Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Transport | Streamable HTTP only | Required for non-subprocess clients |
+| MCP library | `mark3labs/mcp-go` | Mature HTTP transport; simpler API vs official SDK |
+| Auth | Optional bearer token (env var) | Secure by default when configured, zero-config for local use |
+| Structure | `pkg/mcp/` + `cmd/gosqlx-mcp/` | Library importable; binary for direct use |
+
+## Tools
+
+| Tool | Wraps | Purpose |
+|---|---|---|
+| `validate_sql` | `gosqlx.Validate` / `ParseWithDialect` | Syntax validation with dialect support |
+| `format_sql` | `gosqlx.Format` | Formatting with configurable options |
+| `parse_sql` | `gosqlx.Parse` | AST summary (statement count and types) |
+| `extract_metadata` | `gosqlx.ExtractMetadata` | Tables, columns, functions |
+| `security_scan` | `security.Scanner.ScanSQL` | SQL injection pattern detection |
+| `lint_sql` | `linter.Linter.LintString` | Style rules L001–L010 |
+| `analyze_sql` | All 6 above (concurrent) | Composite one-call analysis |
+
+## Configuration
+
+| Env Var | Default | Description |
+|---|---|---|
+| `GOSQLX_MCP_HOST` | `127.0.0.1` | Bind interface |
+| `GOSQLX_MCP_PORT` | `8080` | TCP port (1–65535) |
+| `GOSQLX_MCP_AUTH_TOKEN` | `""` | Bearer token; empty disables auth |
+
+## Architecture
+
+```
+cmd/gosqlx-mcp/main.go       → LoadConfig → New → Start
+pkg/mcp/
+  config.go                  → Config, LoadConfig, DefaultConfig
+  middleware.go              → BearerAuthMiddleware
+  tools.go                   → 7 handlers + internal result functions
+  server.go                  → Server, New, Start, registerTools
+```
+
+## Key Patterns
+
+- **Internal result functions**: Each tool has a `*Internal()` function returning `map[string]any` called by both the MCP handler and `analyze_sql`'s concurrent fan-out
+- **Fan-out**: `analyze_sql` uses `sync.WaitGroup` + buffered channel to run all 6 tools concurrently
+- **Thin wrappers**: Zero new business logic — all SQL processing delegates to existing GoSQLX packages
+- **Consistent imports**: Rule constructors mirror `cmd/gosqlx/cmd/lint.go:createLinter()` exactly
+
+## Quick Start
+
+```bash
+# Run server (default: localhost:8080, no auth)
+gosqlx-mcp
+
+# With auth
+GOSQLX_MCP_AUTH_TOKEN=secret gosqlx-mcp
+
+# Build binary
+task mcp:build
+
+# Run tests
+task mcp:test
+```

go.mod

@@ -1,16 +1,25 @@
 module github.com/ajitpratap0/GoSQLX
 
-go 1.21
+go 1.23.0
 
 require (
 	github.com/fsnotify/fsnotify v1.9.0
+	github.com/mark3labs/mcp-go v0.45.0
 	github.com/spf13/cobra v1.10.1
 	github.com/spf13/pflag v1.0.9
 	golang.org/x/term v0.20.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
+	github.com/bahlo/generic-list-go v0.2.0 // indirect
+	github.com/buger/jsonparser v1.1.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/invopop/jsonschema v0.13.0 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/spf13/cast v1.7.1 // indirect
+	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	golang.org/x/sys v0.20.0 // indirect
 )

go.sum

@@ -1,13 +1,48 @@
+github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
+github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
+github.com/buger/jsonparser v1.1.1 h1:2PnMjfWD7wBILjqQbt530v576A/cAbQvEW9gGIpYMUs=
+github.com/buger/jsonparser v1.1.1/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
+github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
+github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
+github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
+github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
+github.com/mark3labs/mcp-go v0.45.0 h1:s0S8qR/9fWaQ3pHxz7pm1uQ0DrswoSnRIxKIjbiQtkc=
+github.com/mark3labs/mcp-go v0.45.0/go.mod h1:YnJfOL382MIWDx1kMY+2zsRHU/q78dBg9aFb8W6Thdw=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cast v1.7.1 h1:cuNEagBQEHWN1FnbGEjCXL2szYEXqfJPbP2HNUaca9Y=
+github.com/spf13/cast v1.7.1/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
 github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
 github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=
+github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 golang.org/x/sys v0.20.0 h1:Od9JTbYCk261bKm4M/mw7AklTlFYIa0bIp9BgSm1S8Y=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/term v0.20.0 h1:VnkxpohqXaOBYJtBmEppKUG6mXpi+4O6purfc2+sMhw=

pkg/mcp/config.go

@@ -0,0 +1,102 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// 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
+package mcp
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+)
+
+// 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.
+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
+}
+
+// LoadConfig reads configuration from environment variables, applying defaults
+// for any variables that are unset or empty.
+func LoadConfig() (*Config, error) {
+	cfg := DefaultConfig()
+
+	if v := os.Getenv("GOSQLX_MCP_HOST"); v != "" {
+		cfg.Host = v
+	}
+
+	if v := os.Getenv("GOSQLX_MCP_PORT"); v != "" {
+		port, err := strconv.Atoi(v)
+		if err != nil {
+			return nil, fmt.Errorf("GOSQLX_MCP_PORT: expected integer, got %q", v)
+		}
+		if port < 1 || port > 65535 {
+			return nil, fmt.Errorf("GOSQLX_MCP_PORT: %d is out of range (1–65535)", port)
+		}
+		cfg.Port = port
+	}
+
+	if v := strings.TrimSpace(os.Getenv("GOSQLX_MCP_AUTH_TOKEN")); v != "" {
+		cfg.AuthToken = v
+	}
+
+	return cfg, nil
+}
+
+// DefaultConfig returns a Config with all defaults applied (auth disabled).
+func DefaultConfig() *Config {
+	return &Config{
+		Host: "127.0.0.1",
+		Port: 8080,
+	}
+}
+
+// Addr returns the "host:port" string suitable for net/http ListenAndServe.
+func (c *Config) Addr() string {
+	return fmt.Sprintf("%s:%d", c.Host, c.Port)
+}
+
+// AuthEnabled reports whether bearer token authentication is configured.
+func (c *Config) AuthEnabled() bool {
+	return c.AuthToken != ""
+}