feat(mcp): add stdio transport for Glama registry compatibility

[ajitpratap0]

Summary

• Adds --stdio flag to gosqlx-mcp binary to serve MCP protocol over stdin/stdout
• Exposes MCPServer() accessor on pkg/mcp.Server for use with stdio transport
• Enables Glama registry to inspect tools and run server checks (unlocks AAA score)

Why

Glama's test infrastructure automatically wraps any CMD with mcp-proxy --, which expects a stdio-based MCP subprocess. The existing HTTP-only server couldn't work in this mode, causing all builds to fail with ENOENT.

With --stdio, mcp-proxy spawns gosqlx-mcp --stdio, which reads JSON-RPC from stdin and writes responses to stdout — exactly what mcp-proxy expects.

The Glama Dockerfile CMD will be:

CMD ["mcp-proxy","--","/app/gosqlx-mcp","--stdio"]

Transport modes

Mode	How to invoke	Use case
HTTP (default)	gosqlx-mcp	Production, mcp.gosqlx.dev
stdio	gosqlx-mcp --stdio	Glama builds, mcp-proxy, local tools

Test plan

• go test -race ./... — all packages pass
• Pre-commit hooks pass (fmt, vet, short tests)
• Binary builds cleanly

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
gosqlx-website	Error		Mar 17, 2026 3:27pm

[github-actions]

Claude finished @ajitpratap0's task —— View job

---

Code Review for stdio Transport Addition

I'm reviewing this PR for code quality, best practices, potential bugs, performance considerations, security concerns, and test coverage.

Review Checklist:

• Read and analyze all changed files
• Review main.go stdio implementation
• Check server.go MCPServer accessor
• Examine glama.json configuration
• Assess adherence to project conventions
• Provide comprehensive feedback

Detailed Code Review

Overall Assessment: This is a well-implemented addition that cleanly adds stdio transport support for Glama registry compatibility. The changes are minimal, focused, and follow good practices.

✅ Strengths

Clean Architecture & Design

• Single Responsibility: The run() function elegantly routes between HTTP and stdio modes based on command-line flags
• Proper Separation: runStdio() and runHTTP() are well-separated with clear responsibilities
• Minimal Surface Area: Only exposes necessary MCPServer() accessor without breaking encapsulation

Code Quality

• Clear Documentation: Both new functions have proper godoc comments explaining their purpose
• Consistent Error Handling: Follows existing patterns using fmt.Errorf() for error wrapping
• Signal Handling: Proper graceful shutdown with signal.NotifyContext() in both modes
• Logging: Appropriate error logging to stderr in stdio mode

✅ Security Analysis

No Security Concerns

• Input Validation: Simple flag parsing with no user input processing
• No Network Exposure: stdio mode actually reduces attack surface by removing HTTP transport
• Same Authorization: Uses same config and tools as HTTP mode, maintaining existing security posture
• Process Isolation: stdio mode provides better isolation when used with mcp-proxy

✅ Performance Considerations

Excellent Performance Design

• Zero Overhead: Flag checking is O(n) where n = number of args (typically 1-2)
• Shared Infrastructure: Both modes use same underlying MCP server and tools
• Early Exit: Flag check happens before any heavy initialization
• Context Cancellation: Proper cleanup prevents resource leaks

✅ Best Practices Adherence

Follows Project Conventions

• Import Style: Uses aliased import mcpserver following existing patterns
• Error Handling: Consistent with project's error handling (line 83: fmt.Errorf("configuration error: %w", err))
• Memory Management: Proper defer cleanup and signal handling
• Code Style: Matches existing function structure and documentation style

✅ API Design

Well-Designed Public API

// Good: Clear purpose, minimal exposure
func (s *Server) MCPServer() *mcpserver.MCPServer {
    return s.mcpSrv
}

• Minimal Exposure: Only exposes what's needed for stdio transport
• Type Safety: Returns concrete type with well-defined interface
• Clear Documentation: Explicitly mentions stdio use case

⚠️ Minor Considerations

Test Coverage Gap

• Missing Tests: No tests for new runStdio() function or MCPServer() method
• Integration Testing: No validation that stdio mode works end-to-end with mcp-proxy
• Flag Parsing: Simple loop could be tested with various flag combinations

Recommendation: Add tests in cmd/gosqlx-mcp/main_test.go:

func TestRunStdioFlag(t *testing.T) {
    oldArgs := os.Args
    defer func() { os.Args = oldArgs }()
    
    os.Args = []string{"gosqlx-mcp", "--stdio"}
    // Test flag detection logic
}

func TestMCPServerAccessor(t *testing.T) {
    srv := gosqlxmcp.New(gosqlxmcp.DefaultConfig())
    mcpSrv := srv.MCPServer()
    assert.NotNil(t, mcpSrv)
}

Error Handling Edge Case

• Signal Context: Both modes use same context pattern, which is good
• Graceful Degradation: No fallback if stdin/stdout are unavailable (acceptable for intended use case)

✅ Glama.json Configuration

Comprehensive and Professional

• Complete Metadata: All required fields present with accurate descriptions
• Tool Definitions: Matches exactly with server implementation (7 tools)
• Performance Claims: Accurately reflects codebase benchmarks ("1380000+ ops/sec")
• Multi-dialect Support: Correctly lists all 7 supported dialects
• Security Features: Properly documents injection detection and severity levels

🎯 Recommendations

1. Add Basic Tests (Low Priority):

   # Add to test suite
   go test -v ./cmd/gosqlx-mcp/

2. Consider CLI Library (Future Enhancement):
   For more complex flag handling, consider using flag package or cobra, but current simple approach is perfectly adequate.

3. Documentation Update (Consider):
   Update CLI usage documentation to mention --stdio flag.

📊 Summary

Aspect	Score	Notes
Code Quality	⭐⭐⭐⭐⭐	Clean, well-structured, follows conventions
Security	⭐⭐⭐⭐⭐	No concerns, actually improves isolation
Performance	⭐⭐⭐⭐⭐	Zero overhead, efficient implementation
Maintainability	⭐⭐⭐⭐⭐	Clear separation, good documentation
Test Coverage	⭐⭐⭐⭐	Existing tests pass, minor gap for new features

Verdict: ✅ Ready to merge - This is a high-quality implementation that achieves its goal with minimal, clean changes. The code is production-ready and follows all project conventions.

---