Merge branch 'main' into fgrosse/goleaks

Author: fgrosse

README.md

@@ -1,25 +1,14 @@
 <!-- Autogenerated by weave; DO NOT EDIT -->
-# MCP Go SDK v0.5.0
+# MCP Go SDK
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/modelcontextprotocol/go-sdk)
 
-***BREAKING CHANGES***
-
-This version contains breaking changes.
-See the [release notes](
-https://github.com/modelcontextprotocol/go-sdk/releases/tag/v0.5.0) for details.
-
 [![PkgGoDev](https://pkg.go.dev/badge/github.com/modelcontextprotocol/go-sdk)](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk)
 
-This repository contains an unreleased implementation of the official Go
-software development kit (SDK) for the Model Context Protocol (MCP).
+This repository contains an implementation of the official Go software
+development kit (SDK) for the Model Context Protocol (MCP).
 
-> [!WARNING]
-> The SDK is not yet at v1.0.0 and may still be subject to incompatible API
-> changes. We aim to tag v1.0.0 in September, 2025. See
-> https://github.com/modelcontextprotocol/go-sdk/issues/328 for details.
-
-## Package documentation
+## Package / Feature documentation
 
 The SDK consists of several importable packages:
 
@@ -32,12 +21,14 @@ The SDK consists of several importable packages:
   their own transports.
 - The
   [`github.com/modelcontextprotocol/go-sdk/auth`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth)
-  package provides some primitives for supporting oauth.
-
+  package provides some primitives for supporting OAuth.
 - The
   [`github.com/modelcontextprotocol/go-sdk/oauthex`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/oauthex)
   package provides extensions to the OAuth protocol, such as ProtectedResourceMetadata.
 
+The SDK endeavors to implement the full MCP spec. The [`docs/`](/docs/) directory
+contains feature documentation, mapping the MCP spec to the packages above.
+
 ## Getting started
 
 To get started creating an MCP server, create an `mcp.Server` instance, add
@@ -63,24 +54,28 @@ type Output struct {
 	Greeting string `json:"greeting" jsonschema:"the greeting to tell to the user"`
 }
 
-func SayHi(ctx context.Context, req *mcp.CallToolRequest, input Input) (*mcp.CallToolResult, Output, error) {
+func SayHi(ctx context.Context, req *mcp.CallToolRequest, input Input) (
+	*mcp.CallToolResult,
+	Output,
+	error,
+) {
 	return nil, Output{Greeting: "Hi " + input.Name}, nil
 }
 
 func main() {
 	// Create a server with a single tool.
 	server := mcp.NewServer(&mcp.Implementation{Name: "greeter", Version: "v1.0.0"}, nil)
 	mcp.AddTool(server, &mcp.Tool{Name: "greet", Description: "say hi"}, SayHi)
-	// Run the server over stdin/stdout, until the client disconnects
+	// Run the server over stdin/stdout, until the client disconnects.
 	if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
 		log.Fatal(err)
 	}
 }
 ```
 
-To communicate with that server, we can similarly create an `mcp.Client` and
-connect it to the corresponding server, by running the server command and
-communicating over its stdin/stdout:
+To communicate with that server, create an `mcp.Client` and connect it to the
+corresponding server, by running the server command and communicating over its
+stdin/stdout:
 
 ```go
 package main
@@ -99,7 +94,7 @@ func main() {
 	// Create a new client, with no features.
 	client := mcp.NewClient(&mcp.Implementation{Name: "mcp-client", Version: "v1.0.0"}, nil)
 
-	// Connect to a server over stdin/stdout
+	// Connect to a server over stdin/stdout.
 	transport := &mcp.CommandTransport{Command: exec.Command("myserver")}
 	session, err := client.Connect(ctx, transport, nil)
 	if err != nil {
@@ -128,24 +123,18 @@ func main() {
 The [`examples/`](/examples/) directory contains more example clients and
 servers.
 
-## Design
-
-The design doc for this SDK is at [design.md](./design/design.md), which was
-initially reviewed at
-[modelcontextprotocol/discussions/364](https://github.com/orgs/modelcontextprotocol/discussions/364).
+## Contributing
 
-Further design discussion should occur in
-[issues](https://github.com/modelcontextprotocol/go-sdk/issues) (for concrete
-proposals) or
-[discussions](https://github.com/modelcontextprotocol/go-sdk/discussions) for
-open-ended discussion. See [CONTRIBUTING.md](/CONTRIBUTING.md) for details.
+We welcome contributions to the SDK! Please see See
+[CONTRIBUTING.md](/CONTRIBUTING.md) for details of how to contribute.
 
-## Acknowledgements
+## Acknowledgements / Alternatives
 
-Several existing Go MCP SDKs inspired the development and design of this
-official SDK, notably [mcp-go](https://github.com/mark3labs/mcp-go), authored
-by Ed Zynda. We are grateful to Ed as well as the other contributors to mcp-go,
-and to authors and contributors of other SDKs such as
+Several third party Go MCP SDKs inspired the development and design of this
+official SDK, and continue to be viable alternatives, notably
+[mcp-go](https://github.com/mark3labs/mcp-go), originally authored by Ed Zynda.
+We are grateful to Ed as well as the other contributors to mcp-go, and to
+authors and contributors of other SDKs such as
 [mcp-golang](https://github.com/metoro-io/mcp-golang) and
 [go-mcp](https://github.com/ThinkInAIXYZ/go-mcp). Thanks to their work, there
 is a thriving ecosystem of Go MCP clients and servers.

auth/auth.go

@@ -56,8 +56,6 @@ func TokenInfoFromContext(ctx context.Context) *TokenInfo {
 // If verification succeeds, the [TokenInfo] is added to the request's context and the request proceeds.
 // If verification fails, the request fails with a 401 Unauthenticated, and the WWW-Authenticate header
 // is populated to enable [protected resource metadata].
-//
-
 //
 // [protected resource metadata]: https://datatracker.ietf.org/doc/rfc9728
 func RequireBearerToken(verifier TokenVerifier, opts *RequireBearerTokenOptions) func(http.Handler) http.Handler {

auth/client.go

@@ -0,0 +1,109 @@
+// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+//go:build mcp_go_client_oauth
+
+package auth
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"sync"
+
+	"github.com/modelcontextprotocol/go-sdk/internal/oauthex"
+	"golang.org/x/oauth2"
+)
+
+// An OAuthHandler conducts an OAuth flow and returns a [oauth2.TokenSource] if the authorization
+// is approved, or an error if not.
+type OAuthHandler func(context.Context, OAuthHandlerArgs) (oauth2.TokenSource, error)
+
+// OAuthHandlerArgs are arguments to an [OAuthHandler].
+type OAuthHandlerArgs struct {
+	// The URL to fetch protected resource metadata, extracted from the WWW-Authenticate header.
+	// Empty if not present or there was an error obtaining it.
+	ResourceMetadataURL string
+}
+
+// HTTPTransport is an [http.RoundTripper] that follows the MCP
+// OAuth protocol when it encounters a 401 Unauthorized response.
+type HTTPTransport struct {
+	handler OAuthHandler
+	mu      sync.Mutex // protects opts.Base
+	opts    HTTPTransportOptions
+}
+
+// NewHTTPTransport returns a new [*HTTPTransport].
+// The handler is invoked when an HTTP request results in a 401 Unauthorized status.
+// It is called only once per transport. Once a TokenSource is obtained, it is used
+// for the lifetime of the transport; subsequent 401s are not processed.
+func NewHTTPTransport(handler OAuthHandler, opts *HTTPTransportOptions) (*HTTPTransport, error) {
+	if handler == nil {
+		return nil, errors.New("handler cannot be nil")
+	}
+	t := &HTTPTransport{
+		handler: handler,
+	}
+	if opts != nil {
+		t.opts = *opts
+	}
+	if t.opts.Base == nil {
+		t.opts.Base = http.DefaultTransport
+	}
+	return t, nil
+}
+
+// HTTPTransportOptions are options to [NewHTTPTransport].
+type HTTPTransportOptions struct {
+	// Base is the [http.RoundTripper] to use.
+	// If nil, [http.DefaultTransport] is used.
+	Base http.RoundTripper
+}
+
+func (t *HTTPTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	t.mu.Lock()
+	base := t.opts.Base
+	t.mu.Unlock()
+
+	resp, err := base.RoundTrip(req)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode != http.StatusUnauthorized {
+		return resp, nil
+	}
+	if _, ok := base.(*oauth2.Transport); ok {
+		// We failed to authorize even with a token source; give up.
+		return resp, nil
+	}
+
+	resp.Body.Close()
+	// Try to authorize.
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	// If we don't have a token source, get one by following the OAuth flow.
+	// (We may have obtained one while t.mu was not held above.)
+	// TODO: We hold the lock for the entire OAuth flow. This could be a long
+	// time. Is there a better way?
+	if _, ok := t.opts.Base.(*oauth2.Transport); !ok {
+		authHeaders := resp.Header[http.CanonicalHeaderKey("WWW-Authenticate")]
+		ts, err := t.handler(req.Context(), OAuthHandlerArgs{
+			ResourceMetadataURL: extractResourceMetadataURL(authHeaders),
+		})
+		if err != nil {
+			return nil, err
+		}
+		t.opts.Base = &oauth2.Transport{Base: t.opts.Base, Source: ts}
+	}
+	return t.opts.Base.RoundTrip(req.Clone(req.Context()))
+}
+
+func extractResourceMetadataURL(authHeaders []string) string {
+	cs, err := oauthex.ParseWWWAuthenticate(authHeaders)
+	if err != nil {
+		return ""
+	}
+	return oauthex.ResourceMetadataURL(cs)
+}

auth/client_test.go

@@ -0,0 +1,102 @@
+// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+//go:build mcp_go_client_oauth
+
+package auth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"golang.org/x/oauth2"
+)
+
+// TestHTTPTransport validates the OAuth HTTPTransport.
+func TestHTTPTransport(t *testing.T) {
+	const testToken = "test-token-123"
+	fakeTokenSource := oauth2.StaticTokenSource(&oauth2.Token{
+		AccessToken: testToken,
+		TokenType:   "Bearer",
+	})
+
+	// authServer simulates a resource that requires OAuth.
+	authServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		authHeader := r.Header.Get("Authorization")
+		if authHeader == fmt.Sprintf("Bearer %s", testToken) {
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+
+		w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="http://metadata.example.com"`)
+		w.WriteHeader(http.StatusUnauthorized)
+	}))
+	defer authServer.Close()
+
+	t.Run("successful auth flow", func(t *testing.T) {
+		var handlerCalls int
+		handler := func(ctx context.Context, args OAuthHandlerArgs) (oauth2.TokenSource, error) {
+			handlerCalls++
+			if args.ResourceMetadataURL != "http://metadata.example.com" {
+				t.Errorf("handler got metadata URL %q, want %q", args.ResourceMetadataURL, "http://metadata.example.com")
+			}
+			return fakeTokenSource, nil
+		}
+
+		transport, err := NewHTTPTransport(handler, nil)
+		if err != nil {
+			t.Fatalf("NewHTTPTransport() failed: %v", err)
+		}
+		client := &http.Client{Transport: transport}
+
+		resp, err := client.Get(authServer.URL)
+		if err != nil {
+			t.Fatalf("client.Get() failed: %v", err)
+		}
+		defer resp.Body.Close()
+
+		if resp.StatusCode != http.StatusOK {
+			t.Errorf("got status %d, want %d", resp.StatusCode, http.StatusOK)
+		}
+		if handlerCalls != 1 {
+			t.Errorf("handler was called %d times, want 1", handlerCalls)
+		}
+
+		// Second request should reuse the token and not call the handler again.
+		resp2, err := client.Get(authServer.URL)
+		if err != nil {
+			t.Fatalf("second client.Get() failed: %v", err)
+		}
+		defer resp2.Body.Close()
+
+		if resp2.StatusCode != http.StatusOK {
+			t.Errorf("second request got status %d, want %d", resp2.StatusCode, http.StatusOK)
+		}
+		if handlerCalls != 1 {
+			t.Errorf("handler should still be called only once, but was %d", handlerCalls)
+		}
+	})
+
+	t.Run("handler returns error", func(t *testing.T) {
+		handlerErr := errors.New("user rejected auth")
+		handler := func(ctx context.Context, args OAuthHandlerArgs) (oauth2.TokenSource, error) {
+			return nil, handlerErr
+		}
+
+		transport, err := NewHTTPTransport(handler, nil)
+		if err != nil {
+			t.Fatalf("NewHTTPTransport() failed: %v", err)
+		}
+		client := &http.Client{Transport: transport}
+
+		_, err = client.Get(authServer.URL)
+		if !errors.Is(err, handlerErr) {
+			t.Errorf("client.Get() returned error %v, want %v", err, handlerErr)
+		}
+	})
+}

docs/README.md

@@ -1,9 +1,9 @@
 <!-- Autogenerated by weave; DO NOT EDIT -->
-These docs are a work-in-progress.
-
 # Features
 
 These docs mirror the [official MCP spec](https://modelcontextprotocol.io/specification/2025-06-18).
+Use the index below to learn how the SDK implements a particular aspect of the
+protocol.
 
 ## Base Protocol
 
@@ -15,21 +15,21 @@ These docs mirror the [official MCP spec](https://modelcontextprotocol.io/specif
 1. [Authorization](protocol.md#authorization)
 1. [Security](protocol.md#security)
 1. [Utilities](protocol.md#utilities)
-    1. [Cancellation](utilities.md#cancellation)
-    1. [Ping](utilities.md#ping)
-    1. [Progress](utilities.md#progress)
+    1. [Cancellation](protocol.md#cancellation)
+    1. [Ping](protocol.md#ping)
+    1. [Progress](protocol.md#progress)
 
 ## Client Features
 
 1. [Roots](client.md#roots)
 1. [Sampling](client.md#sampling)
-1. [Elicitation](clients.md#elicitation)
+1. [Elicitation](client.md#elicitation)
 
 ## Server Features
 
 1. [Prompts](server.md#prompts)
 1. [Resources](server.md#resources)
-1. [Tools](tools.md)
+1. [Tools](server.md#tools)
 1. [Utilities](server.md#utilities)
     1. [Completion](server.md#completion)
     1. [Logging](server.md#logging)