[go-fan] Go Module Review: go-sdk (v1.3.0 upgrade available)

[github-actions]

🐹 Go Fan Report: modelcontextprotocol/go-sdk

Module Overview

The official Go SDK for Model Context Protocol servers and clients, maintained in collaboration with Google. This is our most critical dependency - it enables awmg to act as an MCP gateway by connecting to backend MCP servers and proxying their capabilities.

Repository: https://github.com/modelcontextprotocol/go-sdk
Current Version: v1.2.0 (released 2025-12-22)
Latest Version: v1.3.0 (released 2026-02-09) ⚡ UPDATE AVAILABLE
Last Updated: 2026-02-16T15:53:09Z (1 day ago!)

Current Usage in gh-aw-mcpg

Scale of Usage

• Files: 22 files import and use this SDK
• Import Count: 17 direct SDK API calls in internal/mcp/connection.go alone
• Key APIs Used:
  • Client/Session: NewClient, Client, ClientSession, Implementation
  • Transports: CommandTransport, StreamableClientTransport, SSEClientTransport
  • MCP Methods: ListTools, CallTool, ListResources, ReadResource, ListPrompts, GetPrompt

Usage Pattern

// Current initialization (2 locations)
client := sdk.NewClient(&sdk.Implementation{
    Name:    "awmg",
    Version: version.Get(),
}, nil)  // ⚠️ Passing nil for options

Transport Strategy:

• Stdio: CommandTransport for Docker-based MCP servers
• HTTP Streamable: StreamableClientTransport for 2025-03-26 spec
• HTTP SSE: SSEClientTransport for 2024-11-05 spec
• Plain JSON-RPC: Custom implementation for legacy backends

Research Findings

v1.3.0 Release Highlights (2026-02-09)

🚀 Major Enhancements

1. Schema Caching - Significant performance boost for stateless server deployments (avoids repeated reflection)
2. DisableListening Option - New option for StreamableClientTransport to better control connection lifecycle
3. Improved Logger API - Logger now configured via ClientOption (old API deprecated gracefully)
4. Better Error Export - GetError and SetError methods now exported for advanced error handling

🐛 Critical Bugfixes

• Content-Type header parsing - Now case-insensitive (affects our HTTP backends!)
• SSEClientTransport error reporting - Better HTTP error propagation
• RFC 9110 compliance - Added Allow header to 405 responses
• Race condition - Fixed logging race condition (improves stability)

📦 Dependencies

• Upgraded to jsonschema v0.4.2

v1.2.0 Features (Our Current Version)

MCP Spec 2025-11-25 Support:

• ✅ Icons and metadata (SEP-973)
• ✅ Tool name validation (SEP-986)
• ✅ Elicitation defaults (SEP-1024)
• ✅ URL mode elicitation (SEP-1036)
• ✅ SSE polling (SEP-1699)
• ✅ Elicitation enum improvements (SEP-1330)

New APIs Available (Not Yet Used):

• Common error codes via sentinel jsonrpc.Error
• OAuth 2.0 Protected Resource Metadata support
• ClientCapabilities.RootsV2 and RootCapabilities
• Capabilities fields in ServerOptions and ClientOptions

Recent Activity

Repository was updated yesterday (2026-02-16) with:

• Content-Length header case-insensitivity fix
• Transport improvements
• Bug fixes and stability enhancements

Improvement Opportunities

🏃 Quick Wins

1. Upgrade to v1.3.0 (HIGH PRIORITY)

Why: Critical bug fixes + performance improvements
Impact: Fixes HTTP header parsing bug that affects our backends
Risk: Low - stable release, no breaking changes
Effort: 15 minutes

Benefits:

• ✅ Case-insensitive Content-Length parsing (fixes potential HTTP backend issues)
• ✅ Race condition fix in logging (improves stability)
• ✅ Schema caching (automatic performance boost)
• ✅ Better error handling capabilities

Steps:

go get -u github.com/modelcontextprotocol/go-sdk@v1.3.0
go mod tidy
make test-all

2. Use ClientOptions Pattern

Current: Passing nil for options everywhere
Better: Use ClientOptions for future-proofing and better control

Locations to fix:

• internal/mcp/connection.go:94-97 (newMCPClient)
• internal/testutil/mcptest/validator.go:19-22 (NewValidatorClient)

Example refactor:

// Before
client := sdk.NewClient(&sdk.Implementation{
    Name:    "awmg",
    Version: version.Get(),
}, nil)

// After
client := sdk.NewClient(&sdk.Implementation{
    Name:    "awmg",
    Version: version.Get(),
}, &sdk.ClientOptions{
    Capabilities: &sdk.ClientCapabilities{
        // Explicit capability configuration
    },
})

Benefit: Better control over capabilities, prepares for future SDK enhancements
Effort: 30 minutes

✨ Feature Opportunities

1. Leverage Schema Caching (v1.3.0)

• What: New feature that caches JSON schemas to avoid repeated reflection
• Impact: Significant performance improvement for stateless server scenarios
• Code changes: None! Automatically enabled after v1.3.0 upgrade
• Best for: High-traffic gateway deployments

2. OAuth 2.0 Support

• What: v1.2.0 added OAuth 2.0 Protected Resource Metadata support
• Current: Using simple API key authentication
• Opportunity: Implement OAuth for enterprise deployments
• SDK provides: auth package with OAuth utilities
• Effort: 2-4 hours

3. Better Error Handling with Sentinel Errors

• What: v1.2.0 added common error codes via jsonrpc.Error
• Current: Using string matching in isHTTPConnectionError()
• Better: Use SDK error types for robust error detection
• Code location: internal/mcp/connection.go:30 (TODO comment already exists!)
• Effort: 1-2 hours

4. Icon and Metadata Support (SEP-973)

• What: Expose tool/resource icons in gateway responses
• Benefit: Richer user experience when displaying tools
• Use case: UI clients that want to display tool icons
• Effort: 3-5 hours

5. Tool Name Validation (SEP-986)

• What: SDK validates tool names per MCP spec
• Benefit: Better error messages, catch invalid tool names early
• Current: No explicit validation
• Effort: 1 hour

📐 Best Practice Alignment

1. Remove Nil Options (Code Smell)

Issue: Always passing nil for options parameter
Fix: Use &sdk.ClientOptions{} even if empty
Why: Future-proofs code, makes explicit configuration visible
Locations: 2 places (connection.go, validator.go)

2. Leverage SDK Error Types

Issue: String matching for error detection (fragile)
Example: isHTTPConnectionError() checks strings.Contains(errMsg, "connection refused")
Fix: Use errors.Is() or type assertions with SDK error types
Note: Code comment at line 29 already suggests this improvement!

3. Use DisableListening Option (v1.3.0)

What: New option for StreamableClientTransport
Benefit: Better control over HTTP connection lifecycle
Use case: Review if beneficial for our HTTP backend scenarios
Effort: 2 hours to investigate and test

4. Adopt v1.3.0 Logger Pattern

Old: Logger configured in Client constructor (deprecated)
New: Logger configured via ClientOption
Current: Using debug logging via internal/logger
Opportunity: Better integration between SDK and our logging framework
Effort: 2-3 hours

🔧 General Improvements

1. Connection Pooling Awareness

• v1.2.0 PR [agentics] Multi-Device Docs Tester failed #709: "allow re-using connections in more cases"
• Opportunity: Review if awmg can benefit from connection reuse
• Impact: Performance improvement for frequently-accessed backends
• Effort: 4-6 hours investigation

2. Enhanced Context Cancellation

• v1.2.0 improved streamable context cancellation handling
• Benefit: More robust connection management
• Action: Review custom cancellation logic after upgrade
• Effort: 2 hours

3. SSE Polling Support (SEP-1699)

• v1.2.0 added SSE polling support
• Benefit: Better reliability for SSE backends
• Current: Using SSEClientTransport
• Opportunity: Leverage polling features if needed
• Effort: 3 hours

4. Windows CRLF Handling

• v1.2.0 fixed Windows CRLF in MCP client
• Benefit: Better cross-platform compatibility
• Action: Automatically included in upgrade
• Impact: Windows users benefit immediately

Recommendations

🔴 Priority 1: Upgrade to v1.3.0 (Immediate)

Why: Contains critical bug fixes that affect HTTP backends
Risk: Very low - stable release
Effort: 15 minutes
Impact: High - fixes potential production issues

Action Items:

1. Update go.mod to v1.3.0
2. Run full test suite
3. Deploy to staging for validation
4. Monitor logs for improvements

🟡 Priority 2: Adopt ClientOptions Pattern (This Sprint)

Why: Code quality improvement, future-proofing
Risk: None
Effort: 30 minutes
Impact: Medium - better code maintainability

Action Items:

1. Replace nil with &sdk.ClientOptions{} in 2 locations
2. Consider explicit capability configuration
3. Add unit tests for options handling

🟢 Priority 3: SDK Error Types (Next Sprint)

Why: Replace fragile string matching
Risk: Low - improves reliability
Effort: 1-2 hours
Impact: Medium - more robust error handling

Action Items:

1. Research available SDK error types
2. Replace isHTTPConnectionError() with type assertions
3. Update tests for new error handling

🔵 Future Exploration (Backlog)

• OAuth 2.0 implementation for enterprise auth
• Icon/metadata exposure for richer tool displays
• Connection reuse patterns for performance
• SSE polling for improved reliability

Next Steps

1. ✅ This week: Upgrade to v1.3.0
2. ✅ This sprint: Refactor ClientOptions usage
3. 🔄 Next sprint: Implement SDK error types
4. 📋 Backlog: Explore OAuth 2.0, icons, connection pooling

Summary Statistics

• Current Version: v1.2.0 (51 days old)
• Latest Version: v1.3.0 (8 days old)
• Files Using SDK: 22
• Quick Wins Identified: 2
• Feature Opportunities: 5
• Best Practice Improvements: 4
• General Improvements: 4
• Total Recommendations: 15

---

Module Summary: A comprehensive markdown summary will be saved to specs/mods/go-sdk.md for future reference.

Generated by Go Fan 🐹 - Your enthusiastic Go module reviewer!
Review Date: 2026-02-17
Next Review: After v1.3.0 upgrade (or in 7 days)

Generated by Go Fan

• expires on Feb 24, 2026, 7:33 AM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this Go module upgrade as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the SDK upgrade requirements and create a pull request to upgrade go-sdk to v1.3.0 with the recommended improvements.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster