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

[ajitpratap0]

Summary

• Adds a Model Context Protocol (MCP) server so AI assistants and MCP-compatible clients can use GoSQLX's SQL processing capabilities over streamable HTTP — no subprocess required
• Implements pkg/mcp/ as an importable library and cmd/gosqlx-mcp/ as a standalone binary with graceful shutdown
• All 7 tools are thin wrappers over existing GoSQLX packages — zero new business logic

Tools

Tool	Wraps	Description
validate_sql	gosqlx.Validate / ParseWithDialect	Syntax validation, 7 dialects
format_sql	gosqlx.Format	Indent, keyword case, semicolon options
parse_sql	gosqlx.Parse	AST summary: statement count + types
extract_metadata	gosqlx.ExtractMetadata	Tables, columns, functions
security_scan	security.Scanner.ScanSQL	8 injection pattern types
lint_sql	linter.Linter.LintString	Style rules L001–L010
analyze_sql	All 6 above (concurrent)	One-call composite analysis

Configuration

GOSQLX_MCP_HOST=127.0.0.1   # default
GOSQLX_MCP_PORT=8080         # default
GOSQLX_MCP_AUTH_TOKEN=secret # optional bearer auth

Usage

task mcp:build              # build binary
./build/gosqlx-mcp          # run server
task mcp:test               # run tests with race detection

Test Plan

• 38 unit tests across pkg/mcp/ — all pass with -race -count=1
• All packages pass: go test -race ./... (full suite, zero failures)
• Pre-commit hooks pass: go fmt, go vet, short tests
• MCP Inspector CLI: all 7 tools verified with real HTTP calls
• Auth enforcement: 401 without token, 401 with wrong token, 200 with correct token
• Edge cases: empty SQL, invalid SQL, RECURSIVE CTEs, injection attempts
• Concurrent load: 10 parallel sessions, no race conditions

🤖 Generated with Claude Code

[claude]

Claude finished @ajitpratap0's task —— View job

---

Code Review Complete

I've thoroughly reviewed the MCP server implementation. Here's my detailed analysis:

Overall Assessment ⭐⭐⭐⭐⭐

This is a high-quality implementation that follows Go best practices and integrates well with the existing GoSQLX codebase. The code is production-ready with excellent test coverage and proper error handling.

✅ Strengths

Architecture & Design

• Clean separation of concerns with config, server, middleware, and tools modules
• Excellent use of existing GoSQLX APIs - zero new business logic as intended
• Proper dependency injection with the Config struct
• HTTP-based MCP server is more accessible than subprocess-based alternatives

Code Quality

• Consistent Go conventions and clear, well-documented code
• Excellent error handling with proper parameter validation
• All 22 test functions provide comprehensive coverage including edge cases
• Race condition testing with -race flag (critical for production)

Security Implementation

• Clean bearer token auth middleware with proper 401 responses and WWW-Authenticate headers
• Input validation prevents empty SQL injection in all handlers
• Uses existing security scanner for SQL injection detection
• Auth bypass when token is unset (good for development)

Performance Design

• analyze_sql tool uses goroutines with WaitGroup for concurrent execution
• Direct API calls to existing GoSQLX functions avoid overhead
• Object pooling handled by underlying GoSQLX library

Repository Integration

• Follows established patterns from CLAUDE.md guidelines
• Proper Task integration with mcp:build, mcp:test, mcp:install
• Clean module boundaries respecting the existing architecture

🔍 Detailed Code Review

pkg/mcp/config.go:95-102 ✅

Configuration management is excellent:

• Environment variable parsing with validation
• Sensible defaults (127.0.0.1:8080)
• Port range validation (1-65535)
• Token trimming prevents whitespace issues

pkg/mcp/middleware.go:30-37 ✅

Auth middleware is clean and secure:

if extractBearerToken(r) != cfg.AuthToken {
    w.Header().Set("WWW-Authenticate", `Bearer realm="gosqlx-mcp"`)
    http.Error(w, "Unauthorized", http.StatusUnauthorized)
    return
}

pkg/mcp/tools.go:337-391 ⭐ Outstanding

The concurrent analyze_sql implementation is excellent:

• Proper goroutine management with WaitGroup
• Error aggregation without failing fast
• All 6 tools run in parallel for maximum performance
• Clean channel-based result collection

pkg/mcp/server.go:45-66 ✅

Server lifecycle management:

• Context-based graceful shutdown
• Proper HTTP server wrapping
• Clean logging with auth status

🚀 Performance Considerations

Concurrent Analysis: The analyze_sql tool is particularly well-designed, running all 6 analyses concurrently which should provide significant performance benefits for comprehensive SQL analysis.

Memory Efficiency: By using existing GoSQLX APIs, this leverages all the object pooling optimizations already in place (ast.NewAST/ReleaseAST, tokenizer pools, etc.).

🔐 Security Analysis

• ✅ Bearer token authentication properly implemented
• ✅ Input validation prevents protocol-level attacks
• ✅ No credentials logged or exposed
• ✅ Uses existing security scanner for SQL injection detection
• ✅ 401 responses include proper WWW-Authenticate headers

🧪 Test Coverage

Excellent test suite with 22 test functions covering:

• Configuration loading and validation
• Authentication middleware (auth enabled/disabled/wrong token)
• All 7 MCP tools with valid/invalid inputs
• Race condition testing (-race flag)
• Edge cases like empty SQL, malformed requests

📋 Minor Suggestions

Enhancement Opportunities

1. Context Timeout: Consider adding configurable request timeouts for long-running SQL analysis
2. Metrics: Could add basic request/error metrics for production monitoring
3. Rate Limiting: Production deployments might benefit from rate limiting

Documentation

The inline documentation is excellent. Consider adding examples to the package-level docs showing typical MCP client integration.

✅ Final Verdict

Approve with confidence. This implementation:

• ✅ Follows all repository guidelines from CLAUDE.md
• ✅ Maintains high code quality standards
• ✅ Provides excellent test coverage with race detection
• ✅ Integrates cleanly with existing codebase
• ✅ Uses production-ready patterns

The PR delivers exactly what it promises: a clean, well-tested MCP server exposing GoSQLX functionality with zero new business logic. Ready for merge!

---

[claude]

Claude finished @ajitpratap0's task —— View job

---

MCP Server Implementation Review

I'll conduct a thorough code review of the MCP server implementation focusing on:

Review Checklist:

• Read and analyze core MCP package files
• Review configuration management (config.go)
• Examine authentication middleware implementation
• Analyze server setup and lifecycle management
• Review tool implementations and API integration
• Assess test coverage and quality
• Check security considerations
• Evaluate performance aspects
• Verify integration with existing GoSQLX patterns
• Provide comprehensive feedback and recommendations

---

Overall Assessment ⭐⭐⭐⭐⭐

This is a high-quality implementation that follows Go best practices and integrates excellently with the existing GoSQLX codebase. The code is production-ready with comprehensive test coverage and proper error handling.

✅ Strengths

Architecture & Design

• Clean separation of concerns with config, middleware, server, and tools modules
• Excellent use of existing GoSQLX APIs - zero new business logic as intended
• Proper dependency injection with the Config struct
• HTTP-based MCP server is more accessible than subprocess-based alternatives

Code Quality

• Consistent Go conventions and clear, well-documented code
• Excellent error handling with proper parameter validation (pkg/mcp/tools.go:44-47)
• 22 test functions providing comprehensive coverage including edge cases
• Race condition testing with -race flag (critical for production readiness)

Security Implementation

• Clean bearer token auth middleware (pkg/mcp/middleware.go:30-37) with proper 401 responses
• Proper WWW-Authenticate headers for HTTP auth standards compliance
• Input validation prevents empty SQL injection in all handlers (pkg/mcp/tools.go:45-47)
• Auth bypass when token is unset (good for development)

Performance Design

• analyze_sql concurrent execution (pkg/mcp/tools.go:337-391) uses goroutines with WaitGroup for all 6 tools
• Direct API calls to existing GoSQLX functions avoid overhead
• Object pooling handled by underlying GoSQLX library

Repository Integration

• Follows CLAUDE.md guidelines perfectly with proper Task integration
• Clean module boundaries respecting the existing architecture
• Proper version handling (v1.9.3 in server registration)

🔍 Detailed Code Review

pkg/mcp/config.go:95-102 ✅

Configuration management is excellent:

• Environment variable parsing with validation
• Sensible defaults (127.0.0.1:8080)
• Port range validation (1-65535)
• Token trimming prevents whitespace issues

pkg/mcp/middleware.go:30-37 ✅

Auth middleware is clean and secure:

if extractBearerToken(r) != cfg.AuthToken {
    w.Header().Set("WWW-Authenticate", `Bearer realm="gosqlx-mcp"`)
    http.Error(w, "Unauthorized", http.StatusUnauthorized)
    return
}

pkg/mcp/tools.go:337-391 ⭐ Outstanding

The concurrent analyze_sql implementation is excellent:

• Proper goroutine management with WaitGroup
• Error aggregation without failing fast
• All 6 tools run in parallel for maximum performance
• Clean channel-based result collection

pkg/mcp/server.go:45-66 ✅

Server lifecycle management:

• Context-based graceful shutdown
• Proper HTTP server wrapping
• Clean logging with auth status

🧪 Test Coverage Analysis

22 test functions across 4 test files with excellent coverage:

config_test.go (6 tests)

• Default configuration loading
• Environment variable parsing
• Port validation (including edge cases)
• Auth token handling

middleware_test.go (6 tests)

• Auth disabled passthrough
• Valid token acceptance
• Invalid/missing token rejection (proper 401 responses)
• Malformed header handling

tools_test.go (7 tests)

• All 7 MCP tools with valid/invalid inputs
• Empty SQL parameter validation
• Concurrent analyze_sql execution
• Error handling for malformed SQL

server_test.go (3 tests)

• Server creation and configuration
• Tool registration verification

🚀 Performance Considerations

Concurrent Analysis: The analyze_sql tool is particularly well-designed, running all 6 analyses concurrently which should provide significant performance benefits for comprehensive SQL analysis.

Memory Efficiency: By using existing GoSQLX APIs, this leverages all the object pooling optimizations already in place (ast.NewAST/ReleaseAST, tokenizer pools, etc.).

🔐 Security Analysis

• ✅ Bearer token authentication properly implemented
• ✅ Input validation prevents protocol-level attacks
• ✅ No credentials logged or exposed
• ✅ Uses existing security scanner for SQL injection detection
• ✅ 401 responses include proper WWW-Authenticate headers

📋 Minor Enhancement Opportunities

1. Context Timeout: Consider adding configurable request timeouts for long-running SQL analysis
2. Metrics: Could add basic request/error metrics for production monitoring
3. Rate Limiting: Production deployments might benefit from rate limiting
4. Documentation: Consider adding examples to package-level docs showing typical MCP client integration

✅ Final Verdict

Approve with confidence. This implementation:

• ✅ Follows all repository guidelines from CLAUDE.md
• ✅ Maintains high code quality standards
• ✅ Provides excellent test coverage with race detection
• ✅ Integrates cleanly with existing codebase
• ✅ Uses production-ready patterns

The PR delivers exactly what it promises: a clean, well-tested MCP server exposing GoSQLX functionality with zero new business logic. Ready for merge!

---

[claude]

Claude finished @ajitpratap0's task —— View job

---

MCP Server Implementation Review

I'll conduct a thorough code review of the MCP server implementation focusing on:

Review Checklist:

• Read and analyze core MCP package files
• Review configuration management (config.go)
• Examine authentication middleware implementation
• Analyze server setup and lifecycle management
• Review tool implementations and API integration
• Assess test coverage and quality
• Check security considerations
• Evaluate performance aspects
• Verify integration with existing GoSQLX patterns
• Provide comprehensive feedback and recommendations

---

Overall Assessment ⭐⭐⭐⭐⭐

This is a high-quality implementation that follows Go best practices and integrates excellently with the existing GoSQLX codebase. The code is production-ready with comprehensive test coverage and proper error handling.

✅ Strengths

Architecture & Design

• Clean separation of concerns with config, middleware, server, and tools modules
• Excellent use of existing GoSQLX APIs - zero new business logic as intended
• Proper dependency injection with the Config struct
• HTTP-based MCP server is more accessible than subprocess-based alternatives

Code Quality

• Consistent Go conventions and clear, well-documented code
• Excellent error handling with proper parameter validation (pkg/mcp/tools.go:44-47)
• 22 test functions providing comprehensive coverage including edge cases
• Race condition testing with -race flag (critical for production readiness)

Security Implementation

• Clean bearer token auth middleware (pkg/mcp/middleware.go:30-37) with proper 401 responses
• Proper WWW-Authenticate headers for HTTP auth standards compliance
• Input validation prevents empty SQL injection in all handlers (pkg/mcp/tools.go:45-47)
• Auth bypass when token is unset (good for development)

Performance Design

• analyze_sql concurrent execution (pkg/mcp/tools.go:337-391) uses goroutines with WaitGroup for all 6 tools
• Direct API calls to existing GoSQLX functions avoid overhead
• Object pooling handled by underlying GoSQLX library

Repository Integration

• Follows CLAUDE.md guidelines perfectly with proper Task integration
• Clean module boundaries respecting the existing architecture
• Proper version handling (v1.9.3 in server registration)

🔍 Detailed Code Review

pkg/mcp/config.go:95-102 ✅

Configuration management is excellent:

• Environment variable parsing with validation
• Sensible defaults (127.0.0.1:8080)
• Port range validation (1-65535)
• Token trimming prevents whitespace issues

pkg/mcp/middleware.go:30-37 ✅

Auth middleware is clean and secure:

if extractBearerToken(r) != cfg.AuthToken {
    w.Header().Set("WWW-Authenticate", `Bearer realm="gosqlx-mcp"`)
    http.Error(w, "Unauthorized", http.StatusUnauthorized)
    return
}

pkg/mcp/tools.go:337-391 ⭐ Outstanding

The concurrent analyze_sql implementation is excellent:

• Proper goroutine management with WaitGroup
• Error aggregation without failing fast
• All 6 tools run in parallel for maximum performance
• Clean channel-based result collection

pkg/mcp/server.go:45-66 ✅

Server lifecycle management:

• Context-based graceful shutdown
• Proper HTTP server wrapping
• Clean logging with auth status

🧪 Test Coverage Analysis

22 test functions across 4 test files with excellent coverage:

config_test.go (6 tests)

• Default configuration loading
• Environment variable parsing
• Port validation (including edge cases)
• Auth token handling

middleware_test.go (6 tests)

• Auth disabled passthrough
• Valid token acceptance
• Invalid/missing token rejection (proper 401 responses)
• Malformed header handling

tools_test.go (7 tests)

• All 7 MCP tools with valid/invalid inputs
• Empty SQL parameter validation
• Concurrent analyze_sql execution
• Error handling for malformed SQL

server_test.go (3 tests)

• Server creation and configuration
• Tool registration verification

🚀 Performance Considerations

Concurrent Analysis: The analyze_sql tool is particularly well-designed, running all 6 analyses concurrently which should provide significant performance benefits for comprehensive SQL analysis.

Memory Efficiency: By using existing GoSQLX APIs, this leverages all the object pooling optimizations already in place (ast.NewAST/ReleaseAST, tokenizer pools, etc.).

🔐 Security Analysis

• ✅ Bearer token authentication properly implemented
• ✅ Input validation prevents protocol-level attacks
• ✅ No credentials logged or exposed
• ✅ Uses existing security scanner for SQL injection detection
• ✅ 401 responses include proper WWW-Authenticate headers

📋 Minor Enhancement Opportunities

1. Context Timeout: Consider adding configurable request timeouts for long-running SQL analysis
2. Metrics: Could add basic request/error metrics for production monitoring
3. Rate Limiting: Production deployments might benefit from rate limiting
4. Documentation: Consider adding examples to package-level docs showing typical MCP client integration

✅ Final Verdict

Approve with confidence. This implementation:

• ✅ Follows all repository guidelines from CLAUDE.md
• ✅ Maintains high code quality standards
• ✅ Provides excellent test coverage with race detection
• ✅ Integrates cleanly with existing codebase
• ✅ Uses production-ready patterns

The PR delivers exactly what it promises: a clean, well-tested MCP server exposing GoSQLX functionality with zero new business logic. Ready for merge!

---

[claude]

Claude finished @ajitpratap0's task —— View job

---

MCP Server Code Review

Review Checklist:

• Read and analyze core MCP package files
• Review configuration management (config.go)
• Examine authentication middleware implementation
• Analyze server setup and lifecycle management
• Review tool implementations and API integration
• Assess test coverage and quality
• Check security considerations
• Evaluate performance aspects
• Verify integration with existing GoSQLX patterns
• Provide comprehensive feedback and recommendations

---

Overall Assessment ⭐⭐⭐⭐⭐

This is a high-quality implementation that follows Go best practices and integrates excellently with the existing GoSQLX codebase. The code is production-ready with comprehensive test coverage and proper error handling.

✅ Strengths

Architecture & Design

• Clean separation of concerns with config, middleware, server, and tools modules
• Excellent use of existing GoSQLX APIs - zero new business logic as intended
• Proper dependency injection with the Config struct
• HTTP-based MCP server is more accessible than subprocess-based alternatives

Code Quality

• Consistent Go conventions and clear, well-documented code
• Excellent error handling with proper parameter validation (pkg/mcp/tools.go:44-47)
• 22 test functions providing comprehensive coverage including edge cases
• Race condition testing with -race flag (critical for production readiness)

Security Implementation

• Clean bearer token auth middleware (pkg/mcp/middleware.go:30-37) with proper 401 responses
• Proper WWW-Authenticate headers for HTTP auth standards compliance
• Input validation prevents empty SQL injection in all handlers (pkg/mcp/tools.go:45-47)
• Auth bypass when token is unset (good for development)

Performance Design

• analyze_sql concurrent execution (pkg/mcp/tools.go:337-391) uses goroutines with WaitGroup for all 6 tools
• Direct API calls to existing GoSQLX functions avoid overhead
• Object pooling handled by underlying GoSQLX library

Repository Integration

• Follows CLAUDE.md guidelines perfectly with proper Task integration
• Clean module boundaries respecting the existing architecture
• Proper version handling (v1.9.3 in server registration)

🔍 Detailed Code Review

pkg/mcp/config.go:95-102 ✅

Configuration management is excellent:

• Environment variable parsing with validation
• Sensible defaults (127.0.0.1:8080)
• Port range validation (1-65535)
• Token trimming prevents whitespace issues

pkg/mcp/middleware.go:30-37 ✅

Auth middleware is clean and secure:

if extractBearerToken(r) != cfg.AuthToken {
    w.Header().Set("WWW-Authenticate", `Bearer realm="gosqlx-mcp"`)
    http.Error(w, "Unauthorized", http.StatusUnauthorized)
    return
}

pkg/mcp/tools.go:337-391 ⭐ Outstanding

The concurrent analyze_sql implementation is excellent:

• Proper goroutine management with WaitGroup
• Error aggregation without failing fast
• All 6 tools run in parallel for maximum performance
• Clean channel-based result collection

pkg/mcp/server.go:45-66 ✅

Server lifecycle management:

• Context-based graceful shutdown
• Proper HTTP server wrapping
• Clean logging with auth status

🧪 Test Coverage Analysis

22 test functions across 4 test files with excellent coverage:

config_test.go (6 tests)

• Default configuration loading
• Environment variable parsing
• Port validation (including edge cases)
• Auth token handling

middleware_test.go (6 tests)

• Auth disabled passthrough
• Valid token acceptance
• Invalid/missing token rejection (proper 401 responses)
• Malformed header handling

tools_test.go (7 tests)

• All 7 MCP tools with valid/invalid inputs
• Empty SQL parameter validation
• Concurrent analyze_sql execution
• Error handling for malformed SQL

server_test.go (3 tests)

• Server creation and configuration
• Tool registration verification

🚀 Performance Considerations

Concurrent Analysis: The analyze_sql tool is particularly well-designed, running all 6 analyses concurrently which should provide significant performance benefits for comprehensive SQL analysis.

Memory Efficiency: By using existing GoSQLX APIs, this leverages all the object pooling optimizations already in place (ast.NewAST/ReleaseAST, tokenizer pools, etc.).

🔐 Security Analysis

• ✅ Bearer token authentication properly implemented
• ✅ Input validation prevents protocol-level attacks
• ✅ No credentials logged or exposed
• ✅ Uses existing security scanner for SQL injection detection
• ✅ 401 responses include proper WWW-Authenticate headers

📋 Minor Enhancement Opportunities

1. Context Timeout: Consider adding configurable request timeouts for long-running SQL analysis
2. Metrics: Could add basic request/error metrics for production monitoring
3. Rate Limiting: Production deployments might benefit from rate limiting
4. Documentation: Consider adding examples to package-level docs showing typical MCP client integration

✅ Final Verdict

Approve with confidence. This implementation:

• ✅ Follows all repository guidelines from CLAUDE.md
• ✅ Maintains high code quality standards
• ✅ Provides excellent test coverage with race detection
• ✅ Integrates cleanly with existing codebase
• ✅ Uses production-ready patterns

The PR delivers exactly what it promises: a clean, well-tested MCP server exposing GoSQLX functionality with zero new business logic. Ready for merge!

---