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

[github-actions[bot]]

🐹 Go Fan Report: modelcontextprotocol/go-sdk

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go implementation of the Model Context Protocol (MCP) — the standard for how AI agents interact with tools, resources, and prompts. This is one of the most strategically important dependencies in gh-aw: it is the backbone of the entire mcp-server command and the mcp-inspect functionality.

Current version: v1.5.0 | Repository | Docs

---

Current Usage in gh-aw

• Files: 14 production files + ~15 test files in pkg/cli/
• Import Count: 2 packages — mcp (main) and jsonrpc (error codes)
• Role: Both server (hosting tools for AI agents) and client (inspecting external MCP servers)

Key APIs Used:

API	Purpose
mcp.NewServer() + mcp.AddTool[In,Out]()	Host 10 typed tools (status, compile, logs, audit, audit-diff, checks, mcp-inspect, add, update, fix)
mcp.StdioTransport + mcp.StreamableHTTPHandler	Dual transport support (local CLI + remote HTTP clients)
mcp.ToolAnnotations	ReadOnlyHint, IdempotentHint, OpenWorldHint on all tools
mcp.Middleware + server.AddReceivingMiddleware()	"Did you mean?" argument validation middleware
mcp.NewClient() + mcp.CommandTransport + mcp.StreamableClientTransport	Inspector connects to external MCP servers
jsonrpc.CodeInternalError / CodeInvalidParams	Structured JSON-RPC error responses

The codebase already uses several advanced features well: generic typed tool registration with struct binding, middleware pipelines, dual transport support, and DisableStandaloneSSE on the inspector client. The comment noting schema caching since v1.3.0 shows active tracking of SDK evolution.

---

Research Findings

Recent Updates (v1.3.0 → v1.5.0)

• v1.3.0: Automatic schema caching (already annotated in codebase at mcp_server.go:43)
• v1.4.0: Improved elicitation support, better progress notification ergonomics
• v1.5.0: Enhanced roots management, CreateMessageWithTools, improved pagination, URLElicitationCapabilities

Best Practices from Maintainers

1. Structured Output: AddTool[In, Out] where Out is a typed struct populates structuredContent — AI clients parse this more reliably than raw JSON text
2. Progress Tokens: Always check req.Params.GetProgressToken() and call req.Session.NotifyProgress() for operations > 1 second
3. InMemoryTransport for Tests: The SDK provides mcp.NewInMemoryTransports() specifically to avoid spawning subprocesses in tests

---

Improvement Opportunities

🏃 Quick Wins

1. Use InMemoryTransport for Unit Tests

All integration tests (//go:build integration) spawn actual binary subprocesses, requiring a compiled binary. The SDK provides in-process transport:

clientT, serverT := mcp.NewInMemoryTransports()
go server.Run(ctx, serverT)
session, _ := client.Connect(ctx, clientT, nil)

Converting the core tool tests (e.g., TestMCPServer_ListTools) to unit tests would remove the binary dependency and run 10-100x faster.

2. Populate Structured Output in Tool Handlers

All 10 tool handlers return nil as the second (structured) return value:

return result, nil, nil
//            ^^^ always nil - structured output never populated

For tools like status and compile that already return JSON text, the second value should be the typed Go struct — AI clients parse structuredContent more reliably without re-parsing embedded JSON.

✨ Feature Opportunities

3. Progress Notifications for Long-Running Tools

logs, audit, and audit-diff can execute for 30+ seconds. MCP clients (Claude, Copilot) display progress indicators when the server calls NotifyProgress. Pattern:

if token := req.Params.GetProgressToken(); token != nil {
    _ = req.Session.NotifyProgress(ctx, &mcp.ProgressNotificationParams{
        ProgressToken: token,
        Progress:      0, Total: 100,
        Message:       "Downloading workflow logs...",
    })
}

This is a low-effort change with high UX impact for the tools users care about most.

4. Event Store for HTTP Sessions

The HTTP server configures SessionTimeout: 2 * time.Hour but no EventStore. Adding mcp.NewMemoryEventStore() enables reconnecting clients to replay missed messages without re-running tools.

5. Elicitation for Missing Parameters

When a required parameter is absent, the server can interactively request it via ServerSession.Elicit(). More conversational than an error, especially for tools like logs where workflow_name is often needed but not always known upfront.

📐 Best Practice Alignment

6. Fix mcpToolParams() Maintenance Burden

mcp_argument_validation.go contains a hardcoded map of tool names → valid parameter names (acknowledged with a // MAINTENANCE: comment). This can drift from the actual struct JSON tags. The same reflection pass used for schema generation could auto-extract JSON tag names, eliminating the maintenance hazard.

7. Mid-Execution Context Cancellation

Tools check ctx.Done() only at entry. For subprocess-based tools, exec.CommandContext propagates the cancel (good!) but there is no goroutine watching for cancellation mid-stream if the subprocess hangs.

🔧 General Improvements

8. Roots Support in Inspector Client

mcp_inspect_mcp.go uses extractRootsFromResources() to infer roots from the resource list — a workaround for the proper MCP Roots protocol. Setting up ClientOptions.RootsHandler would enable proper roots discovery from compliant servers.

---

Recommendations (Prioritized)

1. Progress notifications (item 3) — High impact, low effort. logs/audit are the most-used tools and progress feedback matters for long-running operations.
2. Structured output (item 2) — Medium effort, significant AI-client UX improvement. Start with status tool.
3. InMemoryTransport tests (item 1) — Reduces test latency, removes binary build requirement for unit tests.
4. Fix mcpToolParams() reflection (item 6) — Eliminates a known maintenance hazard.
5. Event store (item 4) — Nice-to-have for production HTTP deployments.

---

References:

• §25309484713

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

Generated by Go Fan · ● 339.4K · ◷

• expires on May 5, 2026, 8:51 AM UTC

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment