Merge branch 'main' into add-io-transport

Author: atomAltera

.github/workflows/readme-check.yml

@@ -19,14 +19,13 @@ jobs:
       uses: actions/checkout@v4
     - name: Check README is up-to-date
       run: |
-        cd internal/readme
-        make
+        go generate ./internal/readme
         if [ -n "$(git status --porcelain)" ]; then
           echo "ERROR: README.md is not up-to-date!"
           echo ""
-          echo "The README.md file differs from what would be generated by running 'make' in internal/readme/."
+          echo "The README.md file differs from what would be generated by `go generate ./internal/readme`."
           echo "Please update internal/readme/README.src.md instead of README.md directly,"
-          echo "then run 'make' in the internal/readme/ directory to regenerate README.md."
+          echo "then run `go generate ./internal/readme` to regenerate README.md."
           echo ""
           echo "Changes:"
           git status --porcelain

README.md

@@ -1,13 +1,13 @@
 <!-- Autogenerated by weave; DO NOT EDIT -->
-# MCP Go SDK v0.3.0
+# MCP Go SDK v0.4.0
 
 [![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.3.0) for details.
+https://github.com/modelcontextprotocol/go-sdk/releases/tag/v0.4.0) for details.
 
 [![PkgGoDev](https://pkg.go.dev/badge/github.com/modelcontextprotocol/go-sdk)](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk)
 
@@ -19,18 +19,6 @@ software development kit (SDK) for the Model Context Protocol (MCP).
 > changes. We aim to tag v1.0.0 in September, 2025. See
 > https://github.com/modelcontextprotocol/go-sdk/issues/328 for details.
 
-## 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).
-
-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.
-
 ## Package documentation
 
 The SDK consists of three importable packages:
@@ -39,19 +27,56 @@ The SDK consists of three importable packages:
   [`github.com/modelcontextprotocol/go-sdk/mcp`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp)
   package defines the primary APIs for constructing and using MCP clients and
   servers.
-- The
-  [`github.com/modelcontextprotocol/go-sdk/jsonschema`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonschema)
-  package provides an implementation of [JSON
-  Schema](https://json-schema.org/), used for MCP tool input and output schema.
 - The
   [`github.com/modelcontextprotocol/go-sdk/jsonrpc`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonrpc) package is for users implementing
   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.
 
-## Example
+## Getting started
 
-In this example, an MCP client communicates with an MCP server running in a
-sidecar process:
+To get started creating an MCP server, create an `mcp.Server` instance, add
+features to it, and then run it over an `mcp.Transport`. For example, this
+server adds a single simple tool, and then connects it to clients over
+stdin/stdout:
+
+```go
+package main
+
+import (
+	"context"
+	"log"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type Input struct {
+	Name string `json:"name" jsonschema:"the name of the person to greet"`
+}
+
+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) {
+	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
+	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:
 
 ```go
 package main
@@ -96,42 +121,20 @@ func main() {
 }
 ```
 
-Here's an example of the corresponding server component, which communicates
-with its client over stdin/stdout:
-
-```go
-package main
-
-import (
-	"context"
-	"log"
-
-	"github.com/modelcontextprotocol/go-sdk/mcp"
-)
-
-type HiParams struct {
-	Name string `json:"name" jsonschema:"the name of the person to greet"`
-}
-
-func SayHi(ctx context.Context, req *mcp.CallToolRequest, args HiParams) (*mcp.CallToolResult, any, error) {
-	return &mcp.CallToolResult{
-		Content: []mcp.Content{&mcp.TextContent{Text: "Hi " + args.Name}},
-	}, nil, nil
-}
+The [`examples/`](/examples/) directory contains more example clients and
+servers.
 
-func main() {
-	// Create a server with a single tool.
-	server := mcp.NewServer(&mcp.Implementation{Name: "greeter", Version: "v1.0.0"}, nil)
+## Design
 
-	mcp.AddTool(server, &mcp.Tool{Name: "greet", Description: "say hi"}, SayHi)
-	// Run the server over stdin/stdout, until the client disconnects
-	if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
-		log.Fatal(err)
-	}
-}
-```
+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).
 
-The [`examples/`](/examples/) directory contains more example clients and servers.
+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.
 
 ## Acknowledgements
 

auth/auth.go

@@ -24,9 +24,13 @@ type TokenInfo struct {
 // The error that a TokenVerifier should return if the token cannot be verified.
 var ErrInvalidToken = errors.New("invalid token")
 
+// The error that a TokenVerifier should return for OAuth-specific protocol errors.
+var ErrOAuth = errors.New("oauth error")
+
 // A TokenVerifier checks the validity of a bearer token, and extracts information
 // from it. If verification fails, it should return an error that unwraps to ErrInvalidToken.
-type TokenVerifier func(ctx context.Context, token string) (*TokenInfo, error)
+// The HTTP request is provided in case verifying the token involves checking it.
+type TokenVerifier func(ctx context.Context, token string, req *http.Request) (*TokenInfo, error)
 
 // RequireBearerTokenOptions are options for [RequireBearerToken].
 type RequireBearerTokenOptions struct {
@@ -52,14 +56,16 @@ 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 {
 	// Based on typescript-sdk/src/server/auth/middleware/bearerAuth.ts.
 
 	return func(handler http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			tokenInfo, errmsg, code := verify(r.Context(), verifier, opts, r.Header.Get("Authorization"))
+			tokenInfo, errmsg, code := verify(r, verifier, opts)
 			if code != 0 {
 				if code == http.StatusUnauthorized || code == http.StatusForbidden {
 					if opts != nil && opts.ResourceMetadataURL != "" {
@@ -75,22 +81,23 @@ func RequireBearerToken(verifier TokenVerifier, opts *RequireBearerTokenOptions)
 	}
 }
 
-func verify(ctx context.Context, verifier TokenVerifier, opts *RequireBearerTokenOptions, authHeader string) (_ *TokenInfo, errmsg string, code int) {
+func verify(req *http.Request, verifier TokenVerifier, opts *RequireBearerTokenOptions) (_ *TokenInfo, errmsg string, code int) {
 	// Extract bearer token.
+	authHeader := req.Header.Get("Authorization")
 	fields := strings.Fields(authHeader)
 	if len(fields) != 2 || strings.ToLower(fields[0]) != "bearer" {
 		return nil, "no bearer token", http.StatusUnauthorized
 	}
 
 	// Verify the token and get information from it.
-	tokenInfo, err := verifier(ctx, fields[1])
+	tokenInfo, err := verifier(req.Context(), fields[1], req)
 	if err != nil {
 		if errors.Is(err, ErrInvalidToken) {
 			return nil, err.Error(), http.StatusUnauthorized
 		}
-		// TODO: the TS SDK distinguishes another error, OAuthError, and returns a 400.
-		// Investigate how that works.
-		// See typescript-sdk/src/server/auth/middleware/bearerAuth.ts.
+		if errors.Is(err, ErrOAuth) {
+			return nil, err.Error(), http.StatusBadRequest
+		}
 		return nil, err.Error(), http.StatusInternalServerError
 	}
 

auth/auth_test.go

@@ -7,18 +7,20 @@ package auth
 import (
 	"context"
 	"errors"
+	"net/http"
 	"testing"
 	"time"
 )
 
 func TestVerify(t *testing.T) {
-	ctx := context.Background()
-	verifier := func(_ context.Context, token string) (*TokenInfo, error) {
+	verifier := func(_ context.Context, token string, _ *http.Request) (*TokenInfo, error) {
 		switch token {
 		case "valid":
 			return &TokenInfo{Expiration: time.Now().Add(time.Hour)}, nil
 		case "invalid":
 			return nil, ErrInvalidToken
+		case "oauth":
+			return nil, ErrOAuth
 		case "noexp":
 			return &TokenInfo{}, nil
 		case "expired":
@@ -47,6 +49,10 @@ func TestVerify(t *testing.T) {
 			"invalid", nil, "bearer invalid",
 			"invalid token", 401,
 		},
+		{
+			"oauth error", nil, "Bearer oauth",
+			"oauth error", 400,
+		},
 		{
 			"no expiration", nil, "Bearer noexp",
 			"token missing expiration", 401,
@@ -61,7 +67,9 @@ func TestVerify(t *testing.T) {
 		},
 	} {
 		t.Run(tt.name, func(t *testing.T) {
-			_, gotMsg, gotCode := verify(ctx, verifier, tt.opts, tt.header)
+			_, gotMsg, gotCode := verify(&http.Request{
+				Header: http.Header{"Authorization": {tt.header}},
+			}, verifier, tt.opts)
 			if gotMsg != tt.wantMsg || gotCode != tt.wantCode {
 				t.Errorf("got (%q, %d), want (%q, %d)", gotMsg, gotCode, tt.wantMsg, tt.wantCode)
 			}

copyright_test.go

@@ -0,0 +1,57 @@
+// 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.
+
+package gosdk
+
+import (
+	"fmt"
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+func TestCopyrightHeaders(t *testing.T) {
+	var re = regexp.MustCompile(`Copyright \d{4} 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.`)
+
+	err := filepath.WalkDir(".", func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+
+		// Skip directories starting with "." or "_", and testdata directories.
+		if d.IsDir() && d.Name() != "." &&
+			(strings.HasPrefix(d.Name(), ".") ||
+				strings.HasPrefix(d.Name(), "_") ||
+				filepath.Base(d.Name()) == "testdata") {
+
+			return filepath.SkipDir
+		}
+
+		// Skip non-go files.
+		if !strings.HasSuffix(path, ".go") {
+			return nil
+		}
+
+		// Check the copyright header.
+		f, err := parser.ParseFile(token.NewFileSet(), path, nil, parser.ParseComments|parser.PackageClauseOnly)
+		if err != nil {
+			return fmt.Errorf("parsing %s: %v", path, err)
+		}
+		if len(f.Comments) == 0 {
+			t.Errorf("File %s must start with a copyright header matching %s", path, re)
+		} else if !re.MatchString(f.Comments[0].Text()) {
+			t.Errorf("Header comment for %s does not match expected copyright header.\ngot:\n%s\nwant matching:%s", path, f.Comments[0].Text(), re)
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+}

examples/client/listfeatures/main.go

@@ -31,10 +31,10 @@ func main() {
 	flag.Parse()
 	args := flag.Args()
 	if len(args) == 0 {
-		fmt.Fprintf(os.Stderr, "Usage: listfeatures <command> [<args>]")
-		fmt.Fprintf(os.Stderr, "List all features for a stdio MCP server")
+		fmt.Fprintln(os.Stderr, "Usage: listfeatures <command> [<args>]")
+		fmt.Fprintln(os.Stderr, "List all features for a stdio MCP server")
 		fmt.Fprintln(os.Stderr)
-		fmt.Fprintf(os.Stderr, "Example: listfeatures npx @modelcontextprotocol/server-everything")
+		fmt.Fprintln(os.Stderr, "Example:\n\tlistfeatures npx @modelcontextprotocol/server-everything")
 		os.Exit(2)
 	}