feat: add MCP server exposing GoSQLX SQL tools over streamable HTTP (#358)

* chore: add .worktrees/ to .gitignore for git worktree support

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

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

* fix: resolve CI failures — lint and Go 1.21 incompatibility

- cmd/gosqlx-mcp/main.go: extract run() helper so os.Exit is not called
  after defer stop() — fixes gocritic exitAfterDefer lint error
- .github/workflows/test.yml: bump minimum Go from 1.21 to 1.23 since
  mark3labs/mcp-go requires go 1.23.0
- CLAUDE.md: document new minimum Go version requirement

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

* chore: remove junk files and outdated archived docs

- Delete local artifacts: binaries (gosqlx, gosqlx-mcp), test binaries
  (parser.test, tokenizer.test), .out files, coverage files, .sarif
- Remove .worktrees/feature-mcp-server (PR #358 already pushed)
- git rm archive/ — explicitly labeled "should not be considered current"
  and "OUTDATED"; adds noise with no current value
- git rm docs/plans/ — LLM internal planning artifact, not user-facing doc

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

* docs: add comprehensive MCP server guide (docs/MCP_GUIDE.md)

* docs: update README with MCP server feature, installation block, and Go 1.23+ requirement

* docs: update Go version to 1.23+ and add MCP link in getting started

* docs: add MCP server to architecture diagram and MCP Architecture section

* docs: add pkg/mcp to API reference package tree and MCP Package section

* docs: add MCP server environment variables to configuration guide

* docs: add [Unreleased] MCP server entry to CHANGELOG

* test(mcp): comprehensive test suite — 95.8% coverage with race, integration, protocol tests

Add 6 test files covering all MCP server code paths:
- tools_internal_test.go: 27 direct tests for internal functions
- server_integration_test.go: 5 HTTP auth middleware tests
- concurrency_test.go: 3 race condition tests (270+ goroutines)
- protocol_test.go: 11 MCP protocol round-trip tests via in-process client
- tools_test.go: 12 edge-case SQL tests (CTEs, window functions, injections)
- server_test.go: 3 server lifecycle tests (start, shutdown, port-in-use)
- scripts/mcp-e2e-test.sh: JSON-RPC E2E shell script

Also fix go vet in Taskfile to exclude CGo-dependent pkg/cbinding.

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

* fix(mcp): add Mcp-Session-Id header to E2E test script

Streamable HTTP transport requires session ID on all requests after
initialization. Capture the header from the initialize response and
pass it on all subsequent JSON-RPC calls.

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

---------

Co-authored-by: Ajit Pratap Singh <ajitpratapsingh@Ajits-Mac-mini-2655.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: ['1.21', '1.24']
+        go-version: ['1.23', '1.24']
 
     steps:
     - uses: actions/checkout@v4
@@ -34,7 +34,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        go: ['1.21', '1.24']
+        go: ['1.23', '1.24']
     env:
       # Prevent Go from auto-downloading toolchain which conflicts with setup-go cache
       GOTOOLCHAIN: local

.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
@@ -54,3 +55,6 @@ build/
 # Python version files (not needed for Go project)
 .python-version
 sql-validator
+
+# Git worktrees
+.worktrees/

CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to GoSQLX will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased] — MCP Server
+
+### ✨ New Features
+- **MCP Server** (`pkg/mcp/`, `cmd/gosqlx-mcp/`): All GoSQLX SQL capabilities as Model Context Protocol tools over streamable HTTP
+  - 7 tools: `validate_sql`, `format_sql`, `parse_sql`, `extract_metadata`, `security_scan`, `lint_sql`, `analyze_sql`
+  - Optional bearer token auth via `GOSQLX_MCP_AUTH_TOKEN`
+  - `analyze_sql` fans out all 6 tools concurrently via `sync.WaitGroup`
+  - Multi-dialect validation: postgresql, mysql, sqlite, sqlserver, oracle, snowflake, generic
+
+### 📝 Documentation
+- `docs/MCP_GUIDE.md` — comprehensive MCP server guide
+- `README.md` — MCP feature bullet, installation block, docs table entry
+- `docs/ARCHITECTURE.md` — MCP in application layer diagram, new MCP Architecture section
+- `docs/API_REFERENCE.md` — pkg/mcp package docs
+- `docs/CONFIGURATION.md` — MCP env vars reference
+- Go version references updated from 1.21+ to 1.23+ (required by mark3labs/mcp-go)
+
+### 🔧 Build
+- Go minimum bumped to 1.23.0 (required by `github.com/mark3labs/mcp-go v0.45.0`)
+- Taskfile: `mcp`, `mcp:build`, `mcp:test`, `mcp:install` tasks added
+
+---
+
 ## [1.9.3] - 2026-03-08 — License Detection Fix
 
 ### 🐛 Bug Fixes

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 GoSQLX is a **production-ready**, **race-free**, high-performance SQL parsing SDK for Go that provides lexing, parsing, and AST generation with zero-copy optimizations. The library is designed for enterprise use with comprehensive object pooling for memory efficiency.
 
-**Requirements**: Go 1.21+
+**Requirements**: Go 1.23+ (upgraded from 1.21 when MCP server was added; `mark3labs/mcp-go` requires 1.23)
 
 **Production Status**: ✅ Validated for production deployment (v1.6.0+, current: v1.9.0)
 - Thread-safe with zero race conditions (20,000+ concurrent operations tested)

README.md

@@ -6,7 +6,7 @@
 
 <h3>⚡ High-Performance SQL Parser for Go ⚡</h3>
 
-[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=for-the-badge&logo=go)](https://go.dev)
+[![Go Version](https://img.shields.io/badge/Go-1.23+-00ADD8?style=for-the-badge&logo=go)](https://go.dev)
 [![Release](https://img.shields.io/github/v/release/ajitpratap0/GoSQLX?style=for-the-badge&color=orange)](https://github.com/ajitpratap0/GoSQLX/releases)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg?style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](http://makeapullrequest.com)
@@ -65,6 +65,7 @@ GoSQLX is a high-performance SQL parsing library designed for production use. It
 - **Zero-Copy**: Direct byte slice operations, <1μs latency
 - **Intelligent Errors**: Structured error codes with typo detection, context highlighting, and helpful hints
 - **Python Bindings**: [PyGoSQLX](python/README.md) — use GoSQLX from Python via ctypes FFI, 100x+ faster than pure Python parsers
+- **MCP Server** (v1.10.0): `gosqlx-mcp` exposes all 7 SQL tools as [Model Context Protocol](https://modelcontextprotocol.io) tools over streamable HTTP — integrate GoSQLX into Claude, Cursor, and any MCP-compatible AI assistant
 - **Production Ready**: Battle-tested with 0 race conditions detected, ~85% SQL-99 compliance, Apache-2.0 licensed
 
 ### Performance & Quality Highlights (v1.9.0)
@@ -153,8 +154,19 @@ print(tables)  # ['users', 'orders']
 
 See the full [PyGoSQLX documentation](python/README.md) for the complete API.
 
+### MCP Server
+
+Use GoSQLX SQL tools from any MCP-compatible AI assistant (Claude, Cursor, etc.):
+
+```bash
+go install github.com/ajitpratap0/GoSQLX/cmd/gosqlx-mcp@latest
+gosqlx-mcp   # starts on 127.0.0.1:8080
+```
+
+See the full [MCP Server Guide](docs/MCP_GUIDE.md) for configuration, authentication, and AI assistant integration.
+
 **Requirements:**
-- Go 1.21 or higher
+- Go 1.23 or higher
 - Python 3.8+ (for Python bindings)
 - No external dependencies for the Go library
 
@@ -402,6 +414,7 @@ func main() {
 | [**Usage Guide**](docs/USAGE_GUIDE.md) | Detailed patterns and best practices |
 | [**Architecture**](docs/ARCHITECTURE.md) | System design and internal architecture |
 | [**Python Bindings**](python/README.md) | PyGoSQLX — Python API, installation, and examples |
+| [**MCP Server Guide**](docs/MCP_GUIDE.md) | `gosqlx-mcp` — 7 SQL tools for AI assistant integration |
 | [**Troubleshooting**](docs/TROUBLESHOOTING.md) | Common issues and solutions |
 
 ### Getting Started

Taskfile.yml

@@ -194,7 +194,7 @@ tasks:
     desc: Run go vet
     cmds:
       - echo "Running go vet..."
-      - go vet ./...
+      - go vet $(go list ./... | grep -v 'pkg/cbinding')
 
   lint:
     desc: Run golangci-lint
@@ -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
   # =============================================================================