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

🐹 Go Fan Report: modelcontextprotocol/go-sdk

Deep dive on github.com/modelcontextprotocol/go-sdk v1.8.0 — the official Go SDK for MCP servers/clients, picked as today's module because it had the most recent pushed_at among gh-aw's direct dependencies.

Module Overview

The official Go implementation of the Model Context Protocol (JSON-RPC 2.0 wire protocol, tool/resource/prompt registration, stdio + streamable-HTTP transports, OAuth client-auth helpers), maintained by the modelcontextprotocol org with Google.

Current Usage in gh-aw

• Files: 13 non-test .go files (pkg/cli/mcp_*.go, pkg/parser/mcp.go), ~20 test files.
• Import count: 18 import lines of mcp/jsonrpc subpackages.
• Key APIs used: mcp.NewServer/ServerOptions/ServerCapabilities, mcp.AddTool with typed-args generics for all 11 registered tools, mcp.ToolAnnotations (ReadOnly/Idempotent/OpenWorld hints), mcp.NewStreamableHTTPHandler + StreamableHTTPOptions, server.AddReceivingMiddleware (custom argument-validation middleware), req.Session.NotifyProgress for progress on long-running tools, jsonrpc.Error/Code* for structured errors, mcp.Icon, and jsonschema.For[T] (from the companion google/jsonschema-go module) wrapped in a local GenerateSchema[T]() helper.

Usage is idiomatic: a single long-lived *mcp.Server built once, small register<Name>Tool functions per tool, typed handlers returning (*mcp.CallToolResult, any, error), and explicit reliance on the SDK's automatic schema caching (called out in a code comment) instead of a hand-rolled cache.

Research Findings

Version status: go.mod pins v1.8.0, published 2026-09-14 — this is the latest stable release. No upgrade needed.

Best Practices: Typed-args mcp.AddTool generics, ToolAnnotations hints, and structured jsonrpc.Error responses are exactly what the SDK's own docs recommend — gh-aw already follows this.

Improvement Opportunities

🏃 Quick Wins

• None required for correctness — current usage already matches SDK best practice.

✨ Feature Opportunities

• ServerOptions.SupportedProtocolVersions: gh-aw currently documents its stateful-mode protocol-negotiation tradeoff only in a code comment in mcp_server_http.go. Setting this option explicitly would make the supported version range self-documenting in code and fail fast (panic at construction) if an unimplemented version is ever referenced by mistake.
• ServerOptions.SetCacheable: gh-aw's tool list is static (ListChanged: false) — exactly the scenario this hook targets. Marking server/discover/tools/list as cacheable with a TTL could reduce repeated list round-trips from polling MCP clients (editor integrations, etc.).
• ServerSession.NotifyElicitationComplete: not applicable today (no elicitation flow in use), but worth keeping in mind if an interactive tool (add/fix) is ever extended to ask clarifying questions via MCP elicitation instead of CLI prompts.

📐 Best Practice Alignment

• Progress notifications (notifyProgress/NotifyProgress) are wired up only for logs, audit, and audit-diff. compile (can watch/recompile many files) and work-queue (hits a Git-backed store) are also potentially long-running and could reuse the same helper for a consistent UX.

🔧 General Improvements

• No redundant or custom reimplementation of SDK functionality found — gh-aw consistently leans on the SDK's generics, annotations, and schema caching rather than hand-rolling equivalents.

Recommendations

1. Consider adding ServerOptions.SupportedProtocolVersions to createMCPServer to make the protocol-version contract explicit in code (low effort, pkg/cli/mcp_server.go).
2. Evaluate ServerOptions.SetCacheable for tools/list/server/discover given the static tool set (pkg/cli/mcp_server.go).
3. Extend notifyProgress coverage to compile and work-queue tools for UX consistency with logs/audit/audit-diff (pkg/cli/mcp_tools_readonly.go, pkg/cli/mcp_tools_work_queue.go).

Next Steps

No urgent action required — the SDK is already at the latest stable version and usage is idiomatic. The three feature opportunities above are optional enhancements, not fixes.

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

References:

• §38222262333

Generated by 🐹 Go Fan · claude · agent · 167 AIC · ⊞ 6.5K · ◷

• expires on Oct 13, 2026, 12:27 AM UTC-08:00