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

.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

@@ -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
   # =============================================================================