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

[github-actions]

🐹 Go Fan Report: modelcontextprotocol/go-sdk

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go SDK for the Model Context Protocol, maintained in collaboration with Google (~4,850⭐). It powers gh-aw's built-in MCP server and its MCP inspection tooling — tool registration, transports (stdio/streamable-HTTP), sessions, middleware, and JSON-schema argument validation. It was the most recently updated direct dependency at review time (pushed 2026-07-24). 🎉

Current Usage in gh-aw

• Files: 13 non-test files (12 in pkg/cli/, 1 in pkg/parser/)
• Import paths: .../mcp and .../jsonrpc
• Key APIs Used: mcp.TextContent (58), mcp.CallToolParams (53), mcp.Implementation (52), mcp.CallToolResult (36), mcp.Tool (30), mcp.NewClient (29), mcp.CommandTransport (26), mcp.NewServer (23), mcp.AddTool (10), mcp.ToolAnnotations (10), plus Middleware, MethodHandler, StreamableClientTransport, NewStreamableHTTPHandler, NewInMemoryTransports.

Version: v1.6.1 (latest stable). Upstream is iterating toward v1.7.0 (currently v1.7.0-pre.3, targeting MCP protocol 2026-07-28). No stable v1.7.0 exists yet, so staying on v1.6.1 is correct.

Research Findings

Recent Updates

• v1.6.1 added MCPGODEBUG=disablecontenttypecheck=1 — an escape hatch to skip the POST Content-Type: application/json check.
• v1.7.0-pre (not yet stable):
  • StreamableHTTPOptions.PropagateRequestCancellation — opt-in: aborting an in-flight POST cancels the handler context (stateless servers, 2026-07-28 protocol), so long-running tool handlers stop paying for orphaned work.
  • OAuth2 session persistence (NewTokenSource / InitialTokenSource).
  • Spec-compliance fixes with MCPGODEBUG escape hatches (nowrapinvalidparams=1, disablecompleteparamsvalidation=1).

Best Practices — gh-aw already nails these ✅

• Generic typed mcp.AddTool[Args] with jsonschema:"..." struct tags (modern, reflection-cached path; schema caching automatic since v1.3.0).
• Rich ToolAnnotations (ReadOnlyHint / IdempotentHint / OpenWorldHint).
• Receiving middleware (AddReceivingMiddleware) that rewrites raw schema errors into friendly "Did you mean?" messages.
• Per-operation context timeouts + explicit ctx.Done() cancellation checks.
• Security-aware HTTP defaults: loopback bind, SDK localhost Host-header checks kept on, DisableStandaloneSSE on the inspector client.

Improvement Opportunities

🏃 Quick Wins

• Track v1.7.0 stable and bump when it lands — do not pin a -pre tag in go.mod. Nothing to change today.
• Document the MCPGODEBUG escape hatches (content-type check, invalid-params wrapping) in the MCP server docs so operators know the available knobs.

✨ Feature Opportunities

• PropagateRequestCancellation for mcp_server_http.go's StreamableHTTPOptions: several tool handlers shell out to gh aw ... subprocesses. On a future stable v1.7.0, enabling this flag would let an aborted client POST cancel those handlers instead of leaving orphaned work. Pre-req: confirm handlers thread the request ctx into exec.CommandContext so cancellation actually propagates.

📐 Best Practice Alignment

• Derive the arg-validation registry from live tool schemas. mcpToolParams() already reflects field names off the *Args structs, but still enumerates the ten tool names by hand. After registration the server holds each tool's InputSchema; deriving the name→params map from the registered tools would remove the last manual list and prevent drift when a new tool is added.

🔧 General Improvements

• Consider a small helper for the repeated &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: s}}}, nil, nil pattern used in every tool handler, to cut boilerplate and centralize result construction.

Recommendations

1. No action needed today — the SDK is used idiomatically and on the latest stable. This is a healthy, well-maintained integration.
2. Watch upstream for v1.7.0 stable; bump then and evaluate PropagateRequestCancellation.
3. Low-effort docs task: document the MCPGODEBUG flags.
4. Optional cleanup: auto-derive mcpToolParams() tool names from registered schemas.

Next Steps

• Add a changelog watch for go-sdk v1.7.0 stable.
• (When stable) prototype PropagateRequestCancellation on the HTTP handler and verify ctx propagation into subprocess handlers.
• Optional: refactor mcpToolParams() to read from registered tool schemas.

---

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

Generated by 🐹 Go Fan · age00 · 130.6 AIC · ⌖ 13.2 AIC · ⊞ 7.2K · ◷

• expires on Jul 25, 2026, 12:52 AM UTC-08:00

[github-actions]

This issue was automatically closed because it expired on 2026-07-25T08:52:49.892Z.

Closed by Workflow