v1.2.2 - MCP Protocol Compliance Fix

🔧 Critical Protocol Compliance Fix

What Changed

Fixed a critical MCP protocol compliance issue where the framework was registering notification handlers with incorrect method names.

🐛 Problem Solved

• Protocol Non-Compliance: Framework registered "initialized" instead of "notifications/initialized"
• Client Compatibility: MCP clients following the specification received "No handler for notification" errors
• Specification Mismatch: Framework did not match the official MCP TypeScript SDK specification

✅ Solution

Updated notification handler registration to use the correct MCP protocol method names:

// Before (incorrect)
if s.GetNotificationHandler("initialized") == nil {
    s.RegisterNotificationHandler("initialized", s.handleInitialized)
}

// After (correct)
if s.GetNotificationHandler("notifications/initialized") == nil {
    s.RegisterNotificationHandler("notifications/initialized", s.handleInitialized)
}

🎯 Benefits

1. ✅ Protocol Compliant - Now follows MCP specification exactly
2. ✅ Client Compatible - Works with all MCP clients that follow the spec
3. ✅ Future Proof - Aligns with official MCP TypeScript SDK patterns
4. ✅ Backward Compatible - Maintains all existing functionality

📋 Changes

• server.go: Changed notification handler registration from "initialized" to "notifications/initialized"
• server_test.go: Updated test to verify correct method name registration
• All tests pass: Comprehensive test coverage ensures no regressions

🔗 References

• MCP TypeScript SDK Specification
• MCP Reference Servers - Use the same pattern

🧪 Testing

• ✅ All Framework Tests Pass - No regressions introduced
• ✅ Protocol Compliance Verified - Correct method names registered
• ✅ Integration Ready - Compatible with MCP clients

📦 Upgrade Notes

This is a recommended upgrade for all users. The change is backward compatible and fixes a critical protocol compliance issue that could cause problems with MCP clients.

Full Diff: v1.2.1...v1.2.2

v1.2.1 - Custom Handler Preservation Fix

🔧 Bug Fix Release

What Changed

Fixed a critical issue where registerDefaultHandlers() was unconditionally overriding custom handlers that servers had already registered.

🐛 Problem Solved

• Custom Handler Override: The framework was overwriting custom tools/list, prompts/list, and resources/list handlers
• Claude Desktop Compatibility: Servers couldn't provide custom tool lists, causing "Method not found" errors
• Framework Principle Violation: Custom handlers should take precedence over defaults

✅ Solution

Modified registerDefaultHandlers() to check if handlers already exist before registering defaults:

func (s *Server) registerDefaultHandlers() {
    // Only register default handlers if custom ones don't exist
    if s.toolsListHandler == nil {
        s.toolsListHandler = s.handleToolsList
    }
    if s.promptsListHandler == nil {
        s.promptsListHandler = s.handlePromptsList  
    }
    if s.resourcesListHandler == nil {
        s.resourcesListHandler = s.handleResourcesList
    }
}

🎯 Benefits

1. ✅ Preserves Custom Handlers - Servers can register custom handlers before calling Start()
2. ✅ Backward Compatible - Servers not using custom handlers continue to work unchanged
3. ✅ Follows Best Practices - Custom implementations take precedence over defaults
4. ✅ Enables Advanced Use Cases - Servers can now provide dynamic tool lists, custom prompts, etc.

🧪 Testing

• ✅ All Transport Tests Pass - STDIO, SSE, and HTTP Streams
• ✅ Comprehensive Test Coverage - Added TestServerCustomHandlersPreserved
• ✅ Integration Tests - Echo tool compatibility maintained
• ✅ Backward Compatibility - Existing servers continue to work

📦 What's Included

• Handler Override Fix - Custom handlers are now preserved
• Enhanced Test Coverage - Comprehensive testing for handler preservation
• Echo Tool Fix - Improved compatibility with integration tests
• Full Transport Support - STDIO, SSE, and HTTP Streams all working

🔗 Related Projects

This fix enables projects like mcp-server-devpod to provide custom tools/list handlers that include both framework tools and project-specific tools, resolving Claude Desktop compatibility issues.

📋 Full Changelog

• Fix registerDefaultHandlers() to check for existing handlers before registering defaults
• Add comprehensive test coverage for handler override functionality
• Fix echo tool to prepend "Echo: " to message for test compatibility
• Ensure backward compatibility while enabling custom handler preservation

Full Diff: v1.2.0...v1.2.1

🎉 MCP Server Framework v1.2.0 - Complete HTTP Streams Transport

🎉 Major Feature Release

This release completes the HTTP Streams transport implementation that was documented in v1.1.0 but never fully committed to the repository.

✨ What's New

🔧 HTTP Streams Transport (/mcp endpoint)

• Full MCP Protocol Compliance: Complete implementation of HTTP Streams transport as per MCP specification
• Session Management: Secure session-based communication with UUID session IDs
• Bidirectional Communication: POST for client→server, SSE for server→client responses
• Health Endpoint: /health endpoint for service monitoring
• CORS Support: Full CORS headers for web client compatibility
• Security: ReadHeaderTimeout configuration, proper error handling

🧪 Comprehensive Testing Infrastructure

• 42 Unit Tests: All passing with race detection
• 3 Integration Test Scripts: Complete end-to-end testing for all transports
  • test_stdio_integration.py - STDIO transport testing
  • test_sse_integration.py - SSE transport testing
  • test_http_streams_integration.py - HTTP Streams transport testing
• Parallel Testing: GitHub Actions matrix strategy for concurrent transport testing
• Make Targets: Individual and combined test targets for all transports

🔄 CI/CD Enhancements

• GitHub Actions Workflow: Matrix strategy testing all three transports in parallel
• Python Dependencies: Proper requests package configuration
• Go 1.21+ Support: Updated build requirements
• Linting Integration: golangci-lint with comprehensive checks
• Security Scan: Trivy vulnerability scanner with SARIF upload
• 3-Phase Workflow: Core tests → Builds → Release

🏗️ Architecture

HTTP Streams Transport Flow:

1. Initialize: POST /mcp with MCP initialize message → Returns session ID
2. SSE Stream: GET /mcp with session ID → Establishes server→client stream
3. Messages: POST /mcp with session ID → Responses via SSE stream
4. Health: GET /health → Service status monitoring

Session Management:

• Cryptographically secure UUID session IDs
• Thread-safe session storage with mutex protection
• Automatic cleanup on client disconnect
• Session validation for all requests

🧹 Code Quality Improvements

Major Refactoring:

• Reduced Complexity: Broke down complex functions into smaller helpers
  • handleMessage → 7 helper functions
  • handleSSEStream → 4 helper functions
• Error Handling: Comprehensive error checking for all operations
• Security: Added HTTP server timeouts, proper CORS handling
• Formatting: Applied gofmt to all files
• Linting: Fixed all golangci-lint issues (line length, error messages, style)

🧪 Test Results

✅ All Tests Passing:

Unit Tests: 42/42 PASSING
Integration Tests: 3/3 PASSING
- STDIO Transport: ✅ WORKING
- SSE Transport: ✅ WORKING  
- HTTP Streams Transport: ✅ WORKING
Build: ✅ PASSING
Lint: ✅ PASSING (0 issues)
Security Scan: ✅ PASSING

📋 Transport Comparison

Feature	STDIO	SSE	HTTP Streams
Use Case	CLI tools	Web apps	Web apps
Communication	Bidirectional	Bidirectional	Bidirectional
Client→Server	stdin	POST /message	POST /mcp
Server→Client	stdout	SSE /sse	SSE /mcp
Session Management	Process-based	Session ID	Session ID
CORS Support	N/A	✅	✅
Health Check	N/A	/health	/health

🔧 Usage Examples

HTTP Streams Transport:

# Start server
./mcp-server -transport http-streams -port 8080

# Initialize session
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

# Connect to SSE stream (use session ID from above)
curl -N http://localhost:8080/mcp?session=SESSION_ID

# Send messages
curl -X POST http://localhost:8080/mcp?session=SESSION_ID \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

All Transport Testing:

# Test all transports
make test-all-transports

# Test individual transports
make test-stdio
make test-sse  
make test-http-streams

🚀 Breaking Changes

None - this is a purely additive release that completes missing functionality.

📦 Assets

This release includes pre-built binaries for:

• Linux (amd64, arm64)
• macOS (amd64, arm64)
• Windows (amd64, arm64)

All binaries are statically linked and ready to use.

---

Full Changelog: v1.1.0...v1.2.0

v1.1.0

What's Changed

• Update README.md with comprehensive HTTP Streams transport documentation by @aatchison in #6

Full Changelog: v1.0.0...v1.1.0

🚀 MCP Server Framework v1.0.0 - Production Ready

🎉 First Release: Production-Ready MCP Server Framework

We are excited to announce the first release of the MCP Server Framework! This release transforms the framework into a production-ready solution with comprehensive functionality, testing, and documentation.

✨ Key Features

🧪 Comprehensive Test Coverage

• 42 Tests Total: Complete test coverage across all components
• SSE Transport (14 tests): Health checks, message handling, session management, error handling
• MCP Server (14 tests): Server creation, handler registration, tools functionality, capabilities
• Client (14 tests): All client functionality with proper error handling

🔧 Complete MCP Protocol Implementation

• ✅ Initialize/Initialized: Proper capability negotiation and notification handling
• ✅ Tools Support: Complete tools/list and tools/call handlers
• ✅ Echo Tool: Built-in example tool for testing and demonstration
• ✅ Error Handling: JSON-RPC compliant error responses
• ✅ Session Management: Proper SSE session validation and management

🐳 Docker Ready

• SSE by Default: Docker container uses SSE transport out of the box
• User-Friendly Configuration: Simple port format (8080 instead of :8080)
• Production Ready: Optimized for deployment and scaling

📚 Comprehensive Documentation

• API Documentation (docs/API.md): Complete endpoint reference with curl examples
• Testing Guide (docs/TESTING.md): Detailed test coverage documentation
• SSE Documentation (docs/SSE.md): SSE-specific transport guide
• Updated README: Correct examples and usage instructions

🔧 Integration Testing

• Bash Test Script: Comprehensive integration testing with cleanup
• Python SSE Client: Proper SSE integration with request/response correlation
• Curl Examples: Working examples for all endpoints and MCP methods

🚀 Quick Start

Docker (Recommended)

docker build -t mcp-server .
docker run -p 8080:8080 mcp-server

Binary

go build -o bin/mcp-server cmd/mcp-server/main.go
./bin/mcp-server -transport=sse -addr=8080

Health Check

curl http://localhost:8080/health
# {"status":"ok","transport":"sse","clients":0,"timestamp":1749244000}

📊 API Endpoints

Endpoint	Method	Purpose	Status
/health	GET	Server health check	✅ Working
/sse	GET	SSE connection	✅ Working
/message	POST	Send MCP messages	✅ Working

🧪 Testing

# Run all tests
go test ./...

# Integration tests
./scripts/test-examples.sh

# Python SSE integration
python3 scripts/test_sse_integration.py 8080

🔄 MCP Protocol Support

• Protocol Version: 2024-11-05
• Transport: SSE (Server-Sent Events) and STDIO
• Capabilities: Tools support with list and call operations
• Error Handling: Full JSON-RPC error compliance

📈 What's New

• Complete Tools Implementation: Full tools/list and tools/call support
• Fixed Notification Handling: Proper distinction between requests and notifications
• Enhanced Session Management: Robust SSE session validation
• Production Docker Setup: SSE transport by default with user-friendly configuration
• Comprehensive Testing: 42 tests covering all functionality and edge cases
• Complete Documentation: API docs, testing guides, and usage examples
• Integration Testing: Bash and Python integration test suites

🐛 Bug Fixes

• Fixed SSE notification handling (was treating all messages as requests)
• Enhanced port format handling (accepts 8080 instead of requiring :8080)
• Improved error handling and JSON-RPC compliance
• Fixed session management and validation

📝 Breaking Changes

None! This release maintains full backward compatibility while adding new functionality.

🔗 Links

• Documentation: docs/
• Examples: scripts/
• Docker Hub: Coming soon!
• Go Module: github.com/protobomb/mcp-server-framework

🙏 Acknowledgments

Thanks to the MCP community for the excellent protocol specification and the Go community for the robust tooling that made this framework possible.

---

Full Changelog: https://github.com/Protobomb/mcp-server-framework/commits/v1.0.0