[go-fan] Go Module Review: modelcontextprotocol/go-sdk

[github-actions[bot]]

🐹 Go Fan Report: MCP Go SDK

The official Go SDK for the Model Context Protocol (MCP) is a critical dependency that enables gh-aw to both expose its functionality as an MCP server and connect to external MCP servers. This review analyzes how gh-aw leverages the SDK and identifies opportunities to better utilize its latest features.

Module Overview

Repository: https://github.com/modelcontextprotocol/go-sdk
Current Version: v1.1.0 (latest)
Release Date: October 30, 2025

The MCP Go SDK provides a comprehensive implementation of the Model Context Protocol, enabling standardized communication between AI agents and tools. It supports multiple transport mechanisms (stdio, HTTP/SSE, custom I/O) and provides both client and server implementations.

Current Usage in gh-aw

gh-aw uses the SDK in two distinct roles:

Role 1: MCP Server (Exposing gh-aw Tools)

Primary implementation: pkg/cli/mcp_server.go

gh-aw runs as an MCP server exposing 7 tools to external MCP clients:

• status - Show workflow status
• compile - Compile workflows with validation
• logs - Download and analyze workflow logs
• audit - Investigate workflow runs
• mcp-inspect - Inspect MCP server capabilities
• add - Add workflows from remote repositories
• update - Update workflows and extension

Key patterns used:

• mcp.NewServer() with Implementation metadata
• mcp.AddTool() for automatic schema generation from Go structs
• mcp.NewStreamableHTTPHandler() for HTTP/SSE transport
• StdioTransport for subprocess communication
• Custom loggingHandler wrapping HTTP handler

Transport support:

• Stdio: Default transport for CLI integration
• HTTP: Optional HTTP server on configurable port

Role 2: MCP Client (Connecting to External Servers)

Primary implementation: pkg/cli/mcp_inspect_mcp.go

The mcp inspect command connects to external MCP servers to discover their capabilities:

• Supports stdio, Docker, and HTTP server types
• Lists available tools, resources, and roots
• Validates server configurations
• Uses 30-second connection timeout, 5-second operation timeouts

Key patterns used:

• mcp.NewClient() with Implementation metadata
• mcp.CommandTransport for stdio/Docker servers
• mcp.StreamableClientTransport for HTTP servers
• session.ListTools(), session.ListResources() for capability discovery

Research Findings

Recent Updates in v1.1.0 (October 30, 2025)

Major Behavior Change:

• 🔴 Stream resumption now disabled by default - Previously used in-memory event store, now requires explicit configuration via StreamableHTTPOptions.EventStore. This reduces memory usage for high-traffic servers.

New Features:

1. IOTransport - General-purpose transport from io.ReadCloser/io.WriteCloser
2. ServerOptions.Logger - Built-in structured logging support
3. StreamableHTTPOptions.Logger - HTTP transport-level logging
4. StreamableHTTPOptions.SessionTimeout - Automatic idle session cleanup
5. Experimental OAuth - Client-side OAuth support with mcp_go_client_oauth build tag

Recent Bug Fixes:

• URL mode elicitation support
• Tool name validation (SEP-986)
• SSE ping event filtering (prevents JSON decode errors on keep-alive events)
• Icon support (SEP-973) for prompts, tools, resources
• SSE streaming logging fix (moved from HTTP to MCP middleware layer)

Best Practices from SDK Documentation

The SDK documentation emphasizes:

1. Automatic schema generation - Use mcp.AddTool() with struct types for automatic JSON schema inference
2. Middleware pattern - Use mcp.Middleware for request/response logging instead of HTTP-level wrapping
3. Context propagation - Proper timeout and cancellation through context chain
4. Iterator pattern - Use session.Tools(), session.Resources() iterators for pagination
5. Structured logging - Use NewLoggingHandler() to get slog.Handler for server-side logging

Known Rough Edges (v2 Wishlist)

The SDK maintainers document several API rough edges to fix in v2:

• EventStore.Open is unnecessary (artifact from earlier version)
• Tool name validation only logs instead of panics (should panic in v2)
• Inconsistent naming: ResourceUpdatedNotificationsParams, ProgressNotificationParams
• AudioContent.MarshalJSON should have pointer receiver

Improvement Opportunities

🏃 Quick Wins

1. Use ServerOptions.Logger for structured logging

   // Current: pkg/cli/mcp_server.go:16
   var mcpLog = log.New(os.Stderr, "[MCP] ", log.LstdFlags)
   
   // Better: Leverage v1.1.0 feature
   server := mcp.NewServer(&mcp.Implementation{...}, &mcp.ServerOptions{
       Logger: slog.Default(),
   })

   Benefit: Structured logging, easier debugging, consistent log format

2. Add SessionTimeout to prevent resource leaks

   // pkg/cli/mcp_server.go:669
   handler := mcp.NewStreamableHTTPHandler(func(req *http.Request) *mcp.Server {
       return server
   }, &mcp.StreamableHTTPOptions{
       SessionTimeout: 5 * time.Minute, // NEW in v1.1.0
   })

   Benefit: Automatic cleanup of idle connections

3. Remove unnecessary defer cancel() after WithTimeout

   // pkg/cli/mcp_inspect_mcp.go:77, 134, 143, 222, 243, 252
   ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
   defer cancel() // ❌ Unnecessary - timeout cancels automatically

   Benefit: Cleaner code, prevent confusion

4. Validate tool names at startup

   // Validate against SEP-986: ^[a-zA-Z0-9_-]+$
   toolNames := []string{"status", "compile", "logs", "audit", "mcp-inspect", "add", "update"}
   for _, name := range toolNames {
       if !regexp.MustCompile(`^[a-zA-Z0-9_-]+$`).MatchString(name) {
           log.Fatalf("Invalid tool name: %s", name)
       }
   }

   Benefit: Catch configuration errors early (SDK only logs warnings)

✨ Feature Opportunities

1. Migrate to Middleware pattern for logging

   Current: HTTP-level logging wrapper blocks SSE streaming

   // pkg/cli/mcp_server.go:loggingHandler wraps HTTP handler
   handlerWithLogging := loggingHandler(handler)

   Better: Use MCP middleware (as fixed in SDK examples/http Fix text sanitization to preserve markdown bold notation #614)

   server.AddReceivingMiddleware(func(ctx context.Context, req *mcp.Request, next mcp.MiddlewareFunc) (*mcp.Response, error) {
       start := time.Now()
       resp, err := next(ctx, req)
       mcpLog.Printf("%s took %v", req.Method, time.Since(start))
       return resp, err
   })

   Benefit: Non-blocking SSE streams, protocol-level logging

2. Add Resource support for workflow files

   Opportunity: Expose workflow files as MCP resources

   server.AddResourceTemplate(&mcp.ResourceTemplate{
       URITemplate: "(redacted)}.md",
   }, workflowResourceHandler)

   Benefit: Clients could read workflow content directly through MCP protocol

3. Add Prompt support for common operations

   Use cases:

   • "Analyze failed workflow"
   • "Debug compilation error"
   • "Review security scan results"

   server.AddPrompt(&mcp.Prompt{
       Name: "analyze-failure",
       Arguments: []*mcp.PromptArgument{
           {Name: "run_id", Description: "workflow run ID", Required: true},
       },
   }, analyzeFailurePromptHandler)

   Benefit: LLM-friendly interaction patterns, guided workflows

4. Leverage IOTransport for custom transports

   New in v1.1.0: General-purpose transport from io.ReadCloser/WriteCloser

   Use case: Custom transport implementations (e.g., Unix sockets, named pipes)

   transport := &mcp.IOTransport{
       ReadCloser:  reader,
       WriteCloser: writer,
   }

5. Add health check endpoint for HTTP server

   Current: No health check mechanism

   http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
       w.WriteHeader(http.StatusOK)
       json.NewEncoder(w).Encode(map[string]string{"status": "healthy"})
   })
   http.Handle("/", handlerWithLogging)

   Benefit: Monitoring, load balancer integration

📐 Best Practice Alignment

1. Consolidate timeout values as constants

   Current: Hardcoded timeouts scattered throughout

   // pkg/cli/mcp_inspect_mcp.go
   ctx, cancel := context.WithTimeout(ctx, 10*time.Second)  // line 134
   ctx, cancel := context.WithTimeout(ctx, 5*time.Second)   // line 143
   ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) // line 77

   Better:

   const (
       MCPConnectionTimeout = 30 * time.Second // Overall connection attempt
       MCPOperationTimeout  = 10 * time.Second // Individual operation (connect)
       MCPListTimeout       = 5 * time.Second  // List operations
   )

2. Consistent error handling in tool handlers

   Current: Mix of returning errors in CallToolResult vs as function errors

   Best practice: Return errors directly, let AddTool handle wrapping

   // Good ✅
   return nil, nil, fmt.Errorf("error message")
   
   // Avoid ❌
   return &mcp.CallToolResult{
       Content: []mcp.Content{&mcp.TextContent{Text: "Error: ..."}},
   }, nil, nil

3. Extract test helper for MCP client creation

   Current: Repeated in every test file

   client := mcp.NewClient(&mcp.Implementation{
       Name:    "test-client",
       Version: "1.0.0",
   }, nil)

   Better: testutil.NewMCPTestClient() helper

   func NewMCPTestClient() *mcp.Client {
       return mcp.NewClient(&mcp.Implementation{
           Name:    "gh-aw-test-client",
           Version: GetVersion(),
       }, nil)
   }

4. Add graceful shutdown for HTTP server

   Current: Server blocks indefinitely

   // pkg/cli/mcp_server.go:682
   if err := httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
       return fmt.Errorf("HTTP server failed: %w", err)
   }

   Better: Handle shutdown signals

   go func() {
       if err := httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
           log.Fatalf("HTTP server failed: %v", err)
       }
   }()
   
   // Wait for interrupt signal
   sigChan := make(chan os.Signal, 1)
   signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
   <-sigChan
   
   // Graceful shutdown with 5-second timeout
   ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
   defer cancel()
   return httpServer.Shutdown(ctx)

5. Add connection retry logic for MCP clients

   Current: Single connection attempt

   // pkg/cli/mcp_inspect_mcp.go:135
   session, err := client.Connect(connectCtx, transport, nil)
   if err != nil {
       return nil, fmt.Errorf("failed to connect to MCP server: %w", err)
   }

   Enhancement: Exponential backoff retry

   var session *mcp.ClientSession
   err := retry.Do(
       func() error {
           var err error
           session, err = client.Connect(ctx, transport, nil)
           return err
       },
       retry.Attempts(3),
       retry.Delay(500*time.Millisecond),
       retry.DelayType(retry.BackOffDelay),
   )

Recommendations

🎯 Priority 1: Immediate Improvements (Next Sprint)

1. ✅ Add ServerOptions.Logger for structured logging
2. ✅ Add SessionTimeout to prevent resource leaks
3. ✅ Validate tool names at startup (SEP-986 compliance)
4. ✅ Clean up unnecessary defer cancel() calls

Estimated effort: 2-3 hours
Risk: Low
Impact: Better reliability and maintainability

🎯 Priority 2: Medium-term Enhancements (Next Month)

1. 🔧 Migrate to Middleware pattern for request logging
2. 🔧 Implement graceful HTTP server shutdown
3. 🔧 Consolidate timeout constants
4. 🔧 Standardize error handling in tool handlers
5. 🔧 Add connection retry logic for MCP clients

Estimated effort: 1-2 days
Risk: Medium (requires testing)
Impact: Better observability and robustness

🎯 Priority 3: Future Considerations (Backlog)

1. 💡 Add Resource support for workflow files
2. 💡 Add Prompt support for common operations
3. 💡 Add health check endpoint
4. 💡 Extract test utilities
5. 💡 Consider stream resumption if needed (currently disabled by default)

Estimated effort: 2-3 days
Risk: Low (additive features)
Impact: Enhanced functionality for MCP clients

Next Steps

1. Update to latest SDK patterns - Adopt v1.1.0 features (Logger, SessionTimeout)
2. Document MCP server usage - Help external clients connect to gh-aw
3. Add comprehensive integration tests - Test against official SDK examples
4. Consider Resource/Prompt support - Expand beyond tools for richer MCP interactions

---

Generated by Go Fan
Module summary saved to: specs/mods/go-sdk.md

AI generated by Go Fan

[github-actions[bot]]

⚓ Avast! This discussion be marked as outdated by Go Fan.
🗺️ A newer treasure map awaits ye at Discussion #5271.
Fair winds, matey! 🏴‍☠️