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

[github-actions[bot]]

🐹 Go Fan Report: modelcontextprotocol/go-sdk (v1.6.0)

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go SDK for the Model Context Protocol (MCP) — the open standard for connecting AI models to external tools and data sources. In gh-aw, this is the most central dependency: the entire MCP server and client functionality is built on top of it.

The SDK provides:

• Generic, type-safe tool registration (mcp.AddTool)
• stdio and HTTP/SSE transports
• A middleware system for request/response pipeline transforms
• Progress notifications for long-running operations
• JSON-RPC 2.0 error handling via jsonrpc.Error

Current Usage in gh-aw

• Files: 26 files (11 source + 15 test)
• Import Count: 2 sub-packages (mcp, jsonrpc)
• Key APIs Used: mcp.NewServer, mcp.AddTool, mcp.Middleware, mcp.StdioTransport, mcp.StreamableHTTPHandler, mcp.NewClient, mcp.CommandTransport, jsonrpc.Error

gh-aw implements a 10-tool MCP server with:

• Read-only tools: status, compile, mcp-inspect, checks
• Privileged (write+) tools: logs, audit, audit-diff
• Management tools: add, update, fix
• An MCP client for inspecting third-party MCP servers

Research Findings

The SDK is at v1.6.0, which is solid and production-ready. The codebase is already leveraging several advanced features: automatic schema caching (v1.3.0+, noted in a comment), the middleware system, typed tool handlers via generics, tool annotations (ReadOnlyHint, IdempotentHint, etc.), and progress notifications for long-running tools.

The usage is generally idiomatic and well-structured. A few targeted improvements could sharpen it further:

Improvement Opportunities

🏃 Quick Wins

1. Add icons to all tools — Only status uses mcp.Icon{Source: "📊"}. IDE extensions and visual MCP clients display these; adding an emoji to each tool (📋 compile, 📝 logs, 🔍 audit, 🔧 fix, etc.) improves UX with trivial effort.

2. Document the any second return in handlers — Every tool handler signature returns (*mcp.CallToolResult, any, error) where the any is always nil. A one-line comment explaining this is a reserved SDK extension point would save future contributors from wondering why it exists.

3. Use jsonrpc.CodeMethodNotFound for tools with no param registry — When mcpToolParams() has no entry for a tool name, argumentValidationMiddleware returns CodeInvalidParams. For a completely unknown tool name, CodeMethodNotFound is semantically more correct per JSON-RPC 2.0.

✨ Feature Opportunities

1. Expose workflow files as MCP Resources — The SDK supports mcp.Resource and mcp.Root objects. The project imports and stores these types in MCPServerInfo but the server itself exposes no resources. Registering compiled .lock.yml files (or the agentic-workflows/ directory) as resources would let AI agents read workflow content without a tool call.

2. Progress notifications for the compile tool — The logs and audit tools already use req.Session.NotifyProgress() for streaming updates. Long compiles with security scanners (--zizmor, --poutine, --actionlint) could benefit from the same pattern.

3. Sending middleware for debug tracing — server.AddSendingMiddleware() could log all outgoing tool results in debug mode, providing end-to-end tracing without modifying individual handlers.

📐 Best Practice Alignment

1. Expand middleware to cover more schema error types — The current argumentValidationMiddleware only intercepts "unexpected additional properties" errors. MCP SDK also surfaces type-mismatch and missing-required-field errors that are equally cryptic. Extending the middleware to rewrite all schema validation errors would give users consistent friendly messages.

2. Replace LCP similarity with Levenshtein distance in findSimilarParam — The current "Did you mean?" logic uses longest-common-prefix ratio. This works for prefix matches (workflowname → workflow-name) but misses transpositions and insertions (e.g., worklfow → workflow). A normalized edit distance would improve suggestion quality.

🔧 General Improvements

1. Fail-fast on tool registration errors — createMCPServer returns a partially-configured server when schema generation fails for a tool. This silent partial failure is difficult to diagnose. The function should either treat registration errors as fatal or expose a health check mechanism.

2. Table-driven tool registration — The sequential register*Tool() calls in createMCPServer could be expressed as a slice of registrar closures, making the function easier to scan and reducing boilerplate.

Recommendations (Priority Order)

1. ✅ Extend argumentValidationMiddleware to handle type-mismatch and missing-required-field schema errors (biggest UX impact)
2. ✅ Add mcp.Icon to all 10 tools for visual client consistency
3. ✅ Upgrade findSimilarParam to use edit distance for better typo detection
4. ✅ Add progress notifications to the compile tool for long-running security scans
5. ✅ Explore exposing .lock.yml files as MCP Resources

Next Steps

• Review [#middleware-expansion] — extend argumentValidationMiddleware for all schema error types
• Quick PR: add icons to all registered tools
• Evaluate: MCP Resources for workflow files (RFC-level discussion)

---

Module summary saved to: scratchpad/mods/modelcontextprotocol-go-sdk.md
Run: §25545119330

Generated by Go Fan · ● 255.5K · ◷

• expires on May 9, 2026, 8:26 AM UTC

[pelikhan]

/q create-issue instead of create-discussion , label with cookie

[github-actions[bot]]

🔧 Pay attention, 007! Q is preparing your gadgets for this discussion comment...

[pelikhan]

/plan 3 major quickwins in a single issue

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment